You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: articles/active-directory/develop/active-directory-certificate-credentials.md
+10-10Lines changed: 10 additions & 10 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -9,10 +9,10 @@ ms.service: active-directory
9
9
ms.subservice: develop
10
10
ms.workload: identity
11
11
ms.topic: conceptual
12
-
ms.date: 02/09/2022
12
+
ms.date: 02/27/2023
13
13
ms.author: owenrichards
14
14
ms.reviewer: kenwith
15
-
ms.custom: contperf-fy21q4, aaddev
15
+
ms.custom: aaddev, has-adal-ref, engagement-fy23
16
16
---
17
17
18
18
# Microsoft identity platform application authentication certificate credentials
@@ -25,7 +25,7 @@ If you're interested in using a JWT issued by another identity provider as a cre
25
25
26
26
## Assertion format
27
27
28
-
To compute the assertion, you can use one of the many JWT libraries in the language of your choice - [MSAL supports this using `.WithCertificate()`](msal-net-client-assertions.md). The information is carried by the token in its Header, Claims, and Signature.
28
+
To compute the assertion, you can use one of the many JWT libraries in the language of your choice - [MSAL supports this using `.WithCertificate()`](msal-net-client-assertions.md). The information is carried by the token in its **Header**, **Claims**, and **Signature**.
29
29
30
30
### Header
31
31
@@ -40,10 +40,10 @@ To compute the assertion, you can use one of the many JWT libraries in the langu
40
40
Claim type | Value | Description
41
41
---------- | ---------- | ----------
42
42
`aud` | `https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/token` | The "aud" (audience) claim identifies the recipients that the JWT is intended for (here Azure AD) See [RFC 7519, Section 4.1.3](https://tools.ietf.org/html/rfc7519#section-4.1.3). In this case, that recipient is the login server (login.microsoftonline.com).
43
-
`exp` | 1601519414 | The "exp" (expiration time) claim identifies the expiration time on or after which the JWT MUST NOT be accepted for processing. See [RFC 7519, Section 4.1.4](https://tools.ietf.org/html/rfc7519#section-4.1.4). This allows the assertion to be used until then, so keep it short - 5-10 minutes after `nbf` at most. Azure AD does not place restrictions on the `exp` time currently.
44
-
`iss` | {ClientID} | The "iss" (issuer) claim identifies the principal that issued the JWT, in this case your client application. Use the GUID application ID.
45
-
`jti` | (a Guid) | The "jti" (JWT ID) claim provides a unique identifier for the JWT. The identifier value MUST be assigned in a manner that ensures that there is a negligible probability that the same value will be accidentally assigned to a different data object; if the application uses multiple issuers, collisions MUST be prevented among values produced by different issuers as well. The "jti" value is a case-sensitive string. [RFC 7519, Section 4.1.7](https://tools.ietf.org/html/rfc7519#section-4.1.7)
46
-
`nbf` | 1601519114 | The "nbf" (not before) claim identifies the time before which the JWT MUST NOT be accepted for processing. [RFC 7519, Section 4.1.5](https://tools.ietf.org/html/rfc7519#section-4.1.5). Using the current time is appropriate.
43
+
`exp` | 1601519414 | The "exp" (expiration time) claim identifies the expiration time on or after which the JWT **must not** be accepted for processing. See [RFC 7519, Section 4.1.4](https://tools.ietf.org/html/rfc7519#section-4.1.4). This allows the assertion to be used until then, so keep it short - 5-10 minutes after `nbf` at most. Azure AD does not place restrictions on the `exp` time currently.
44
+
`iss` | {ClientID} | The "iss" (issuer) claim identifies the principal that issued the JWT, in this case your client application. Use the GUID application ID.
45
+
`jti` | (a Guid) | The "jti" (JWT ID) claim provides a unique identifier for the JWT. The identifier value **must** be assigned in a manner that ensures that there is a negligible probability that the same value will be accidentally assigned to a different data object; if the application uses multiple issuers, collisions MUST be prevented among values produced by different issuers as well. The "jti" value is a case-sensitive string. [RFC 7519, Section 4.1.7](https://tools.ietf.org/html/rfc7519#section-4.1.7)
46
+
`nbf` | 1601519114 | The "nbf" (not before) claim identifies the time before which the JWT MUST NOT be accepted for processing. [RFC 7519, Section 4.1.5](https://tools.ietf.org/html/rfc7519#section-4.1.5). Using the current time is appropriate.
47
47
`sub` | {ClientID} | The "sub" (subject) claim identifies the subject of the JWT, in this case also your application. Use the same value as `iss`.
48
48
`iat` | 1601519114 | The "iat" (issued at) claim identifies the time at which the JWT was issued. This claim can be used to determine the age of the JWT. [RFC 7519, Section 4.1.5](https://tools.ietf.org/html/rfc7519#section-4.1.5).
49
49
@@ -91,7 +91,7 @@ You can associate the certificate credential with the client application in the
91
91
92
92
### Uploading the certificate file
93
93
94
-
In the Azure app registration for the client application:
94
+
In the **App registrations** tab for the client application:
2. Click on **Upload certificate** and select the certificate file to upload.
97
97
3. Click **Add**.
@@ -127,12 +127,12 @@ In the Azure app registration for the client application:
127
127
128
128
## Using a client assertion
129
129
130
-
Client assertions can be used anywhere a client secret would be used. So for example, in the [authorization code flow](v2-oauth2-auth-code-flow.md), you can pass in a `client_secret` to prove that the request is coming from your app. You can replace this with `client_assertion` and `client_assertion_type` parameters.
130
+
Client assertions can be used anywhere a client secret would be used. For example, in the [authorization code flow](v2-oauth2-auth-code-flow.md), you can pass in a `client_secret` to prove that the request is coming from your app. You can replace this with `client_assertion` and `client_assertion_type` parameters.
131
131
132
132
| Parameter | Value | Description|
133
133
|-----------|-------|------------|
134
134
|`client_assertion_type`|`urn:ietf:params:oauth:client-assertion-type:jwt-bearer`| This is a fixed value, indicating that you are using a certificate credential. |
135
-
|`client_assertion`| JWT |This is the JWT created above. |
135
+
|`client_assertion`|`JWT`|This is the JWT created above. |
Copy file name to clipboardExpand all lines: articles/active-directory/develop/active-directory-v2-protocols.md
+14-19Lines changed: 14 additions & 19 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -4,67 +4,62 @@ description: A guide to OAuth 2.0 and OpenID Connect protocols as supported by t
4
4
services: active-directory
5
5
author: henrymbuguakiarie
6
6
manager: CelesteDG
7
-
8
7
ms.service: active-directory
9
8
ms.subservice: develop
10
9
ms.workload: identity
11
10
ms.topic: conceptual
12
-
ms.date: 03/31/2022
11
+
ms.date: 02/27/2023
13
12
ms.author: henrymbugua
14
13
ms.reviewer: nickludwig
15
-
ms.custom: aaddev
14
+
ms.custom: aaddev, has-adal-ref, engagement-fy23
16
15
---
17
16
18
17
# OAuth 2.0 and OpenID Connect (OIDC) in the Microsoft identity platform
19
18
20
-
You don't need to learn OAuth or OpenID Connect (OIDC) at the protocol level to use the Microsoft identity platform. You will, however, encounter these and other protocol terms and concepts as you use the identity platform to add auth functionality to your apps.
21
-
22
-
As you work with the Azure portal, our documentation, and our authentication libraries, knowing a few basics like these can make your integration and debugging tasks easier.
19
+
Knowing about OAuth or OpenID Connect (OIDC) at the protocol level is not required to use the Microsoft identity platform. However, you will encounter protocol terms and concepts as you use the identity platform to add authentication to your apps. As you work with the Azure portal, our documentation, and authentication libraries, knowing some fundamentals can assist your integration and overall experience.
23
20
24
21
## Roles in OAuth 2.0
25
22
26
-
Four parties are typically involved in an OAuth 2.0 and OpenID Connect authentication and authorization exchange. Such exchanges are often called *authentication flows* or *auth flows*.
23
+
Four parties are usually involved in an OAuth 2.0 and OpenID Connect authentication and authorization exchange. These exchanges are often called *authentication flows* or *auth flows*.
27
24
28
25
29
26
30
-
***Authorization server** - The Microsoft identity platform itself is the authorization server. Also called an *identity provider* or *IdP*, it securely handles the end-user's information, their access, and the trust relationships between the parties in the auth flow. The authorization server issues the security tokens your apps and APIs use for granting, denying, or revoking access to resources (authorization) after the user has signed in (authenticated).
27
+
***Authorization server** - The identity platform is the authorization server. Also called an *identity provider* or *IdP*, it securely handles the end-user's information, their access, and the trust relationships between the parties in the auth flow. The authorization server issues the security tokens your apps and APIs use for granting, denying, or revoking access to resources (authorization) after the user has signed in (authenticated).
31
28
32
29
***Client** - The client in an OAuth exchange is the application requesting access to a protected resource. The client could be a web app running on a server, a single-page web app running in a user's web browser, or a web API that calls another web API. You'll often see the client referred to as *client application*, *application*, or *app*.
33
30
34
-
***Resource owner** - The resource owner in an auth flow is typically the application user, or *end-user* in OAuth terminology. The end-user "owns" the protected resource--their data--your app accesses on their behalf. The resource owner can grant or deny your app (the client) access to the resources they own. For example, your app might call an external system's API to get a user's email address from their profile on that system. Their profile data is a resource the end-user owns on the external system, and the end-user can consent to or deny your app's request to access their data.
31
+
***Resource owner** - The resource owner in an auth flow is usually the application user, or *end-user* in OAuth terminology. The end-user "owns" the protected resource (their data) which your app accesses on their behalf. The resource owner can grant or deny your app (the client) access to the resources they own. For example, your app might call an external system's API to get a user's email address from their profile on that system. Their profile data is a resource the end-user owns on the external system, and the end-user can consent to or deny your app's request to access their data.
35
32
36
33
***Resource server** - The resource server hosts or provides access to a resource owner's data. Most often, the resource server is a web API fronting a data store. The resource server relies on the authorization server to perform authentication and uses information in bearer tokens issued by the authorization server to grant or deny access to resources.
37
34
38
35
## Tokens
39
36
40
-
The parties in an authentication flow use **bearer tokens** to assure, verify, and authenticate a principal (user, host, or service) and to grant or deny access to protected resources (authorization). Bearer tokens in the Microsoft identity platform are formatted as [JSON Web Tokens](https://tools.ietf.org/html/rfc7519) (JWT).
37
+
The parties in an authentication flow use **bearer tokens** to assure, verify, and authenticate a principal (user, host, or service) and to grant or deny access to protected resources (authorization). Bearer tokens in the identity platform are formatted as [JSON Web Tokens](https://tools.ietf.org/html/rfc7519) (JWT).
41
38
42
-
Three types of bearer tokens are used by the Microsoft identity platform as *security tokens*:
39
+
Three types of bearer tokens are used by the identity platform as *security tokens*:
43
40
44
41
*[Access tokens](access-tokens.md) - Access tokens are issued by the authorization server to the client application. The client passes access tokens to the resource server. Access tokens contain the permissions the client has been granted by the authorization server.
45
42
46
43
*[ID tokens](id-tokens.md) - ID tokens are issued by the authorization server to the client application. Clients use ID tokens when signing in users and to get basic information about them.
47
44
48
-
*[Refresh tokens](refresh-tokens.md) - The client uses a refresh token, or *RT*, to request new access and ID tokens from the authorization server. Your code should treat refresh tokens and their string content as opaque because they're intended for use only by authorization server.
45
+
*[Refresh tokens](refresh-tokens.md) - The client uses a refresh token, or *RT*, to request new access and ID tokens from the authorization server. Your code should treat refresh tokens and their string content as sensitive data because they're intended for use only by authorization server.
49
46
50
47
## App registration
51
48
52
-
Your client app needs a way to trust the security tokens issued to it by the Microsoft identity platform. The first step in establishing that trust is by [registering your app](quickstart-register-app.md) with the identity platform in Azure Active Directory (Azure AD).
53
-
54
-
When you register your app in Azure AD, the Microsoft identity platform automatically assigns it some values, while others you configure based on the application's type.
49
+
Your client app needs a way to trust the security tokens issued to it by the identity platform. The first step in establishing trust is by [registering your app](quickstart-register-app.md). When you register your app, the identity platform automatically assigns it some values, while others you configure based on the application's type.
55
50
56
51
Two of the most commonly referenced app registration settings are:
57
52
58
-
***Application (client) ID** - Also called _application ID_ and _client ID_, this value is assigned to your app by the Microsoft identity platform. The client ID uniquely identifies your app in the identity platform and is included in the security tokens the platform issues.
53
+
***Application (client) ID** - Also called *application ID* and *client ID*, this value is assigned to your app by the identity platform. The client ID uniquely identifies your app in the identity platform and is included in the security tokens the platform issues.
59
54
***Redirect URI** - The authorization server uses a redirect URI to direct the resource owner's *user-agent* (web browser, mobile app) to another destination after completing their interaction. For example, after the end-user authenticates with the authorization server. Not all client types use redirect URIs.
60
55
61
56
Your app's registration also holds information about the authentication and authorization *endpoints* you'll use in your code to get ID and access tokens.
62
57
63
58
## Endpoints
64
59
65
-
The Microsoft identity platform offers authentication and authorization services using standards-compliant implementations of OAuth 2.0 and OpenID Connect (OIDC) 1.0. Standards-compliant authorization servers like the Microsoft identity platform provide a set of HTTP endpoints for use by the parties in an auth flow to execute the flow.
60
+
The identity platform offers authentication and authorization services using standards-compliant implementations of OAuth 2.0 and OpenID Connect (OIDC) 1.0. Standards-compliant authorization servers like the identity platform provide a set of HTTP endpoints for use by the parties in an auth flow to execute the flow.
66
61
67
-
The endpoint URIs for your app are generated for you when you register or configure your app in Azure AD. The endpoints you use in your app's code depend on the application's type and the identities (account types) it should support.
62
+
The endpoint URIs for your app are generated automatically when you register or configure your app. The endpoints you use in your app's code depend on the application's type and the identities (account types) it should support.
68
63
69
64
Two commonly used endpoints are the [authorization endpoint](v2-oauth2-auth-code-flow.md#request-an-authorization-code) and [token endpoint](v2-oauth2-auth-code-flow.md#redeem-a-code-for-an-access-token). Here are examples of the `authorize` and `token` endpoints:
70
65
@@ -94,7 +89,7 @@ Next, learn about the OAuth 2.0 authentication flows used by each application ty
94
89
*[Authentication flows and application scenarios](authentication-flows-app-scenarios.md)
**We strongly advise against crafting your own library or raw HTTP calls to execute authentication flows.** A [Microsoft authentication library](reference-v2-libraries.md) is safer and much easier. However, if your scenario prevents you from using our libraries or you'd just like to learn more about the identity platform's implementation, we have protocol reference:
92
+
**We strongly advise against crafting your own library or raw HTTP calls to execute authentication flows.** A [Microsoft Authentication Library](reference-v2-libraries.md) is safer and much easier. However, if your scenario prevents you from using our libraries or you'd just like to learn more about the identity platform's implementation, we have protocol reference:
98
93
99
94
*[Authorization code grant flow](v2-oauth2-auth-code-flow.md) - Single-page apps (SPA), mobile apps, native (desktop) applications
Copy file name to clipboardExpand all lines: articles/active-directory/develop/msal-acquire-cache-tokens.md
+5-5Lines changed: 5 additions & 5 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -9,10 +9,10 @@ ms.service: active-directory
9
9
ms.subservice: develop
10
10
ms.topic: conceptual
11
11
ms.workload: identity
12
-
ms.date: 03/22/2022
12
+
ms.date: 02/27/2023
13
13
ms.author: cwerner
14
14
ms.reviewer: saeeda
15
-
ms.custom: aaddev
15
+
ms.custom: aaddev, has-adal-ref, engagement-fy23
16
16
#Customer intent: As an application developer, I want to learn about acquiring and caching tokens so my app can support authentication and authorization.
17
17
---
18
18
@@ -45,7 +45,7 @@ The format of the scope value varies depending on the resource (the API) receivi
45
45
46
46
For Microsoft Graph only, the `user.read` scope maps to `https://graph.microsoft.com/User.Read`, and both scope formats can be used interchangeably.
47
47
48
-
Certain web APIs such as the Azure Resource Manager API (`https://management.core.windows.net/`) expect a trailing forward slash ('/') in the audience claim (`aud`) of the access token. In this case, pass the scope as `https://management.core.windows.net//user_impersonation`, including the double forward slash ('//').
48
+
Certain web APIs such as the Azure Resource Manager API (`https://management.core.windows.net/`) expect a trailing forward slash (`/`) in the audience claim (`aud`) of the access token. In this case, pass the scope as `https://management.core.windows.net//user_impersonation`, including the double forward slash (`//`).
49
49
50
50
Other APIs might require that *no scheme or host* is included in the scope value, and expect only the app ID (a GUID) and the scope name, for example:
51
51
@@ -66,7 +66,7 @@ MSAL maintains a token cache (or two caches for confidential client applications
66
66
67
67
### Recommended call pattern for public client applications
68
68
69
-
Application code should first try to get a token silently from the cache. If the method call returns a "UI required" error or exception, try acquiring a token by other means.
69
+
Application source code should first try to get a token silently from the cache. If the method call returns a "UI required" error or exception, try acquiring a token by other means.
70
70
71
71
There are two flows, however, in which you **should not** attempt to silently acquire a token:
72
72
@@ -95,7 +95,7 @@ In public client applications like desktop and mobile apps, you can:
95
95
96
96
### Confidential client applications
97
97
98
-
For confidential client applications (web app, web API, or a daemon application like a Windows service), you:
98
+
For confidential client applications (web app, web API, or a daemon application like a Windows service), you can;
99
99
100
100
- Acquire tokens **for the application itself** and not for a user, using the [client credentials flow](msal-authentication-flows.md#client-credentials). This technique can be used for syncing tools, or tools that process users in general and not a specific user.
101
101
- Use the [on-behalf-of (OBO) flow](msal-authentication-flows.md#on-behalf-of-obo) for a web API to call an API on behalf of the user. The application is identified with client credentials in order to acquire a token based on a user assertion (SAML, for example, or a JWT token). This flow is used by applications that need to access resources of a particular user in service-to-service calls.
0 commit comments