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
# Comparing the Azure AD v2.0 endpoint with the v1.0 endpoint
24
24
25
-
When developing a new application, it's important to know the differences between the Azure Active Directory (Azure AD) v1.0 and v2.0 endpoints. This article covers the main differences, as well as some existing limitations for the v2.0 endpoint.
25
+
When developing a new application, it's important to know the differences between the Azure Active Directory (Azure AD) v1.0 and v2.0 endpoints. This article covers the main differences between the endpoints and some existing limitations for the v2.0 endpoint.
26
26
27
27
> [!NOTE]
28
-
> Not all Azure AD scenarios and features are supported by the v2.0 endpoint. To determine if you should use the v2.0 endpoint, read about [v2.0 limitations](#limitations).
28
+
> The v2.0 endpoint doesn't support all Azure AD scenarios and features. To determine if you should use the v2.0 endpoint, read about [v2.0 limitations](#limitations).
29
29
30
30
## Who can sign in
31
31
@@ -35,36 +35,34 @@ When developing a new application, it's important to know the differences betwee
35
35
* The v2.0 endpoint allows work and school accounts from Azure AD and personal Microsoft accounts (MSA), such as hotmail.com, outlook.com, and msn.com, to sign in.
36
36
* Both v1.0 and v2.0 endpoints also accept sign-ins of *[guest users](https://docs.microsoft.com/azure/active-directory/b2b/what-is-b2b)* of an Azure AD directory for applications configured as *[single-tenant](single-and-multi-tenant-apps.md)* or for *multi-tenant* applications configured to point to the tenant-specific endpoint (`https://login.microsoftonline.com/{TenantId_or_Name}`).
37
37
38
-
The v2.0 endpoint allows you to write apps that accept sign-ins from personal Microsoft accounts, and work and school accounts. This gives you the ability to write your app completely account-agnostic. For example, if your app calls the [Microsoft Graph](https://graph.microsoft.io), some additional functionality and data will be available to work accounts, such as their SharePoint sites or Directory data. But for many actions, such as [Reading a user's mail](https://developer.microsoft.com/graph/docs/api-reference/v1.0/api/user_list_messages), the same code can access the email for both personal and work and school accounts.
38
+
The v2.0 endpoint allows you to write apps that accept sign-ins from personal Microsoft accounts, and work and school accounts. This gives you the ability to write your app completely account-agnostic. For example, if your app calls the [Microsoft Graph](https://graph.microsoft.io), some additional functionality and data will be available to work accounts, such as their SharePoint sites or directory data. But for many actions, such as [Reading a user's mail](https://developer.microsoft.com/graph/docs/api-reference/v1.0/api/user_list_messages), the same code can access the email for both personal and work and school accounts.
39
39
40
-
For v2.0 endpoint, you can use the Microsoft Authentication Library (MSAL) to gain access to the consumer, educational, and enterprise worlds.
41
-
42
-
The Azure AD v1.0 endpoint accepts sign-ins from work and school accounts only.
40
+
For v2.0 endpoint, you can use the Microsoft Authentication Library (MSAL) to gain access to the consumer, educational, and enterprise worlds. The Azure AD v1.0 endpoint accepts sign-ins from work and school accounts only.
43
41
44
42
## Incremental and dynamic consent
45
43
46
44
Apps using the Azure AD v1.0 endpoint are required to specify their required OAuth 2.0 permissions in advance, for example:
The permissions set directly on the application registration are **static**. While static permissions of the app defined in the Azure portal keeps the code nice and simple, it presents some possible issues for developers:
48
+
The permissions set directly on the application registration are **static**. While static permissions of the app defined in the Azure portal keep the code nice and simple, it presents some possible issues for developers:
51
49
52
-
* The app needs to request all the permissions it would ever need upon the user's first sign-in. In some cases this led to a long list of permissions, which discouraged end users from approving the app's access on initial sign-in.
50
+
* The app needs to request all the permissions it would ever need upon the user's first sign-in. This can lead to a long list of permissions that discourages end users from approving the app's access on initial sign-in.
53
51
54
52
* The app needs to know all of the resources it would ever access ahead of time. It was difficult to create apps that could access an arbitrary number of resources.
55
53
56
-
With the v2.0 endpoint, you can ignore the static permissions defined in the app registration information in the Azure portal and request permissions incrementally instead, for example, asking for a bare minimum set of permissions upfront and accruing more over time as the customer uses additional app features. To do so, you can specify the scopes your app needs at any given point in time by including the new scopes in the `scope` parameter when requesting an access token - without the need to pre-define them in the application registration information. If the user has yet not consented to new scopes added to the request, they will be prompted to consent only to the new permissions. To learn more, see [permissions, consent, and scopes](v2-permissions-and-consent.md).
54
+
With the v2.0 endpoint, you can ignore the static permissions defined in the app registration information in the Azure portal and request permissions incrementally instead, which means asking for a bare minimum set of permissions upfront and accruing more over time as the customer uses additional app features. To do so, you can specify the scopes your app needs at any time by including the new scopes in the `scope` parameter when requesting an access token - without the need to pre-define them in the application registration information. If the user hasn't yet consented to new scopes added to the request, they'll be prompted to consent only to the new permissions. To learn more, see [permissions, consent, and scopes](v2-permissions-and-consent.md).
57
55
58
-
Allowing an app to request permissions dynamically through the `scope` parameter gives developers full control over your user's experience. If you wish, you can also front load your consent experience and ask for all permissions in one initial authorization request. If your app requires a large number of permissions, you can gather those permissions from the user incrementally as they attempt to use certain features of your app over time.
56
+
Allowing an app to request permissions dynamically through the `scope` parameter gives developers full control over your user's experience. You can also front load your consent experience and ask for all permissions in one initial authorization request. If your app requires a large number of permissions, you can gather those permissions from the user incrementally as they try to use certain features of the app over time.
59
57
60
-
Admin consent done on behalf of an organization still requires the static permissions registered for the app, so we recommend that you set those permissions for apps in the app registration portal if you need an admin to give consent on behalf of the entire organization. This reduces the cycles required by the organization admin to setup the application.
58
+
Admin consent done on behalf of an organization still requires the static permissions registered for the app, so you should set those permissions for apps in the app registration portal if you need an admin to give consent on behalf of the entire organization. This reduces the cycles required by the organization admin to set up the application.
61
59
62
60
## Scopes, not resources
63
61
64
-
For apps using the v1.0 endpoint, an app can behave as a **resource**, or a recipient of tokens. A resource can define a number of **scopes** or **oAuth2Permissions** that it understands, allowing client apps to request tokens to that resource for a certain set of scopes. Consider the Azure AD Graph API as an example of a resource:
62
+
For apps using the v1.0 endpoint, an app can behave as a **resource**, or a recipient of tokens. A resource can define a number of **scopes** or **oAuth2Permissions** that it understands, allowing client apps to request tokens from that resource for a certain set of scopes. Consider the Azure AD Graph API as an example of a resource:
65
63
66
-
* Resource Identifier, or `AppID URI`: `https://graph.windows.net/`
67
-
* Scopes, or `OAuth2Permissions`: `Directory.Read`, `Directory.Write`, and so on.
64
+
* Resource identifier, or `AppID URI`: `https://graph.windows.net/`
65
+
* Scopes, or `oAuth2Permissions`: `Directory.Read`, `Directory.Write`, and so on.
68
66
69
67
This holds true for the v2.0 endpoint. An app can still behave as a resource, define scopes, and be identified by a URI. Client apps can still request access to those scopes. However, the way that a client requests those permissions has changed.
Here, the **scope** parameter indicates which resource and permissions the app is requesting authorization. The desired resource is still present in the request - it is simply encompassed in each of the values of the scope parameter. Using the scope parameter in this manner allows the v2.0 endpoint to be more compliant with the OAuth 2.0 specification, and aligns more closely with common industry practices. It also enables apps to perform [incremental consent](#incremental-and-dynamic-consent) - only requesting permissions when the application requires them as opposed to up front.
89
+
Here, the **scope** parameter indicates which resource and permissions the app is requesting authorization. The desired resource is still present in the request - it's encompassed in each of the values of the scope parameter. Using the scope parameter in this manner allows the v2.0 endpoint to be more compliant with the OAuth 2.0 specification, and aligns more closely with common industry practices. It also enables apps to perform [incremental consent](#incremental-and-dynamic-consent) - only requesting permissions when the application requires them as opposed to up front.
92
90
93
91
## Well-known scopes
94
92
95
93
### Offline access
96
94
97
95
Apps using the v2.0 endpoint may require the use of a new well-known permission for apps - the `offline_access` scope. All apps will need to request this permission if they need to access resources on the behalf of a user for a prolonged period of time, even when the user may not be actively using the app. The `offline_access` scope will appear to the user in consent dialogs as **Access your data anytime**, which the user must agree to. Requesting the `offline_access` permission will enable your web app to receive OAuth 2.0 refresh_tokens from the v2.0 endpoint. Refresh tokens are long-lived, and can be exchanged for new OAuth 2.0 access tokens for extended periods of access.
98
96
99
-
If your app does not request the `offline_access` scope, it will not receive refresh tokens. This means that when you redeem an authorization code in the OAuth 2.0 authorization code flow, you will only receive back an access token from the `/token` endpoint. That access token will remain valid for a short period of time (typically one hour), but will eventually expire. At that point in time, your app will need to redirect the user back to the `/authorize` endpoint to retrieve a new authorization code. During this redirect, the user may or may not need to enter their credentials again or re-consent to permissions, depending on the type of app.
97
+
If your app doesn't request the `offline_access` scope, it will not receive refresh tokens. This means that when you redeem an authorization code in the OAuth 2.0 authorization code flow, you'll only receive back an access token from the `/token` endpoint. That access token remains valid for a short period of time (typically one hour), but will eventually expire. At that point in time, your app will need to redirect the user back to the `/authorize` endpoint to retrieve a new authorization code. During this redirect, the user may or may not need to enter their credentials again or reconsent to permissions, depending on the type of app.
100
98
101
99
To learn more about OAuth 2.0, `refresh_tokens`, and `access_tokens`, check out the [v2.0 protocol reference](active-directory-v2-protocols.md).
102
100
103
101
### OpenID, profile, and email
104
102
105
103
Historically, the most basic OpenID Connect sign-in flow with Azure AD would provide a lot of information about the user in the resulting *id_token*. The claims in an id_token can include the user's name, preferred username, email address, object ID, and more.
106
104
107
-
The information that the `openid` scope affords your app access to is now restricted. The `openid` scope will only allow your app to sign in the user and receive an app-specific identifier for the user. If you want to obtain personal data about the user in your app, your app needs to request additional permissions from the user. Two new scopes, `email` and `profile`, will allow you to request additional permissions.
105
+
The information that the `openid` scope affords your app access to is now restricted. The `openid` scope will only allow your app to sign in the user and receive an app-specific identifier for the user. If you want to get personal data about the user in your app, your app needs to request additional permissions from the user. Two new scopes, `email` and `profile`, will allow you to request additional permissions.
108
106
109
107
* The `email` scope allows your app access to the user’s primary email address through the `email` claim in the id_token, assuming the user has an addressable email address.
110
108
* The `profile` scope affords your app access to all other basic information about the user such as their name, preferred username, object ID, and so on in the id_token.
@@ -130,46 +128,49 @@ The v2.0 endpoint will evolve to eliminate the restrictions listed here, so that
130
128
131
129
### Restrictions on app registrations
132
130
133
-
Currently, for each app that you want to integrate with the v2.0 endpoint, you can create an app registration in the [Microsoft Application Registration Portal](https://apps.dev.microsoft.com/?referrer=https://azure.microsoft.com/documentation/articles&deeplink=/appList). Alternatively, you can register an app using the [**App registrations (Preview)** experience](https://portal.azure.com/#blade/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/RegisteredAppsPreview) in the Azure portal. Existing Microsoft account apps are not compatible with the preview portal, but all AAD apps are, regardless of where or when they were registered.
131
+
For each app that you want to integrate with the v2.0 endpoint, you can create an app registration in the [Microsoft Application Registration Portal](https://apps.dev.microsoft.com/?referrer=https://azure.microsoft.com/documentation/articles&deeplink=/appList). Alternatively, you can register an app using the [**App registrations (Preview)** experience](https://portal.azure.com/#blade/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/RegisteredAppsPreview) in the Azure portal. Existing Microsoft account apps are not compatible with the preview portal, but all AAD apps are, regardless of where or when they were registered.
134
132
135
-
App registrations that support work and school accounts as well as personal accounts have the following caveats:
133
+
App registrations that support work and school accounts and personal accounts have the following caveats:
136
134
137
135
* Only two app secrets are allowed per application ID.
138
136
* An app registration registered by a user with a personal Microsoft account in the App Registration Portal can be viewed and managed only by a single developer account. It can't be shared between multiple developers. If you'd like to share your app registration with multiple developers, you can create the application using the App Registrations (Preview) section of the Azure portal.
139
137
* There are several restrictions on the format of the redirect URL that is allowed. For more information about redirect URL, see the next section.
140
138
141
139
### Restrictions on redirect URLs
142
140
143
-
Apps that are registered for v2.0 are restricted to a limited set of redirect URL values. The redirect URL for web apps and services must begin with the scheme `https`, and all redirect URL values must share a single DNS domain. The registration system compares the whole DNS name of the existing redirect URL to the DNS name of the redirect URL that you are adding. `http://localhost` is also supported as a redirect URL.
141
+
Apps that are registered for v2.0 are restricted to a limited set of redirect URL values. The redirect URL for web apps and services must begin with the scheme `https`, and all redirect URL values must share a single DNS domain. The registration system compares the whole DNS name of the existing redirect URL to the DNS name of the redirect URL that you're adding. `http://localhost` is also supported as a redirect URL.
144
142
145
143
The request to add the DNS name will fail if either of the following conditions is true:
146
144
147
-
* The whole DNS name of the new redirect URL does not match the DNS name of the existing redirect URL.
148
-
* The whole DNS name of the new redirect URL is not a subdomain of the existing redirect URL.
149
-
150
-
For example, if the app has this redirect URL:
145
+
* The whole DNS name of the new redirect URL doesn't match the DNS name of the existing redirect URL.
146
+
* The whole DNS name of the new redirect URL isn't a subdomain of the existing redirect URL.
151
147
152
-
`https://login.contoso.com`
148
+
#### Example 1
153
149
154
-
You can add to it, like this:
150
+
If the app has a redirect URL of `https://login.contoso.com`, you can add a redirect URL where the DNS name matches exactly, as shown in the following example:
155
151
156
152
`https://login.contoso.com/new`
157
153
158
-
In this case, the DNS name matches exactly. Or, you can do this:
154
+
Or, you can refer to a DNS subdomain of login.contoso.com, as shown in the following example:
159
155
160
156
`https://new.login.contoso.com`
161
157
162
-
In this case, you're referring to a DNS subdomain of login.contoso.com. If you want to have an app that has `login-east.contoso.com` and `login-west.contoso.com` as redirect URLs, you must add those redirect URLs in this order:
158
+
#### Example 2
159
+
160
+
If you want to have an app that has `login-east.contoso.com` and `login-west.contoso.com` as redirect URLs, you must add those redirect URLs in the following order:
163
161
164
162
`https://contoso.com`
165
163
`https://login-east.contoso.com`
166
164
`https://login-west.contoso.com`
167
165
168
166
You can add the latter two because they are subdomains of the first redirect URL, contoso.com. This limitation will be removed in an upcoming release.
169
167
170
-
Also note, you can have only 20 reply URLs for a particular application - this applies across all app types that the registration supports (SPA, native client, web app, and service).
168
+
Also note, you can have only 20 reply URLs for a particular application - this limit applies across all app types that the registration supports (SPA, native client, web app, and service).
169
+
170
+
To learn how to register an app for use with v2.0, see these quickstarts:
171
171
172
-
To learn how to register an app for use with v2.0, see [How to register an app with the v2.0 endpoint](quickstart-v2-register-an-app.md).
172
+
*[Register an app using the Application Registration Portal](quickstart-v2-register-an-app.md)
173
+
*[Register an app using the App registrations (Preview) experience](quickstart-register-app.md)
0 commit comments