Redirect URI (reply URL) restrictions and limitations
A redirect URI, or reply URL, is the location where the authorization server sends the user once the app has been successfully authorized and granted an authorization code or access token. The authorization server sends the code or token to the redirect URI, so it's important you register the correct location as part of the app registration process.
The Microsoft Entra application model specifies these restrictions to redirect URIs:
Redirect URIs must begin with the scheme
https. There are some exceptions for localhost redirect URIs.
Redirect URIs are case-sensitive and must match the case of the URL path of your running application. For example, if your application includes as part of its path
.../abc/response-oidc, do not specify
.../ABC/response-oidcin the redirect URI. Because the web browser treats paths as case-sensitive, cookies associated with
.../abc/response-oidcmay be excluded if redirected to the case-mismatched
Redirect URIs not configured with a path segment are returned with a trailing slash ('
/') in the response. This applies only when the response mode is
https://contoso.comis returned as
http://localhost:7071is returned as
Redirect URIs that contain a path segment are not appended with a trailing slash in the response.
https://contoso.com/abcis returned as
https://contoso.com/abc/response-oidcis returned as
Redirect URIs do not support special characters -
! $ ' ( ) , ;
Maximum number of redirect URIs
This table shows the maximum number of redirect URIs you can add to an app registration in the Microsoft identity platform.
|Accounts being signed in||Maximum number of redirect URIs||Description|
|Microsoft work or school accounts in any organization's Microsoft Entra tenant||256||
|Personal Microsoft accounts and work and school accounts||100||
The maximum number of redirect URIs can't be raised for security reasons. If your scenario requires more redirect URIs than the maximum limit allowed, consider the following state parameter approach as the solution.
Maximum URI length
You can use a maximum of 256 characters for each redirect URI you add to an app registration.
Redirect URIs in application vs. service principal objects
- Always add redirect URIs to the application object only.
- Do not add redirect URI values to a service principal because these values could be removed when the service principal object syncs with the application object. This could happen due to any update operation which triggers a sync between the two objects.
Query parameter support in redirect URIs
Query parameters are allowed in redirect URIs for applications that only sign in users with work or school accounts.
Query parameters are not allowed in redirect URIs for any app registration configured to sign in users with personal Microsoft accounts like Outlook.com (Hotmail), Messenger, OneDrive, MSN, Xbox Live, or Microsoft 365.
|App registration sign-in audience||Supports query parameters in redirect URI|
|Accounts in this organizational directory only (Contoso only - Single tenant)|
|Accounts in any organizational directory (Any Microsoft Entra directory - Multitenant)|
|Accounts in any organizational directory (Any Microsoft Entra directory - Multitenant) and personal Microsoft accounts (e.g. Skype, Xbox)|
|Personal Microsoft accounts only|
HTTPS: The HTTPS scheme (
https://) is supported for all HTTP-based redirect URIs.
HTTP: The HTTP scheme (
http://) is supported only for localhost URIs and should be used only during active local application development and testing.
|Example redirect URI||Validity|
httpURI schemes are acceptable because the redirect never leaves the device. As such, both of these URIs are acceptable:
- Due to ephemeral port ranges often required by native applications, the port component (for example,
:443) is ignored for the purposes of matching a redirect URI. As a result, all of these URIs are considered equivalent:
From a development standpoint, this means a few things:
Do not register multiple redirect URIs where only the port differs. The login server will pick one arbitrarily and use the behavior associated with that redirect URI (for example, whether it's a
This is especially important when you want to use different authentication flows in the same application registration, for example both the authorization code grant and implicit flow. To associate the correct response behavior with each redirect URI, the login server must be able to distinguish between the redirect URIs and cannot do so when only the port differs.
To register multiple redirect URIs on localhost to test different flows during development, differentiate them using the path component of the URI. For example,
The IPv6 loopback address (
[::1]) is not currently supported.
Prefer 127.0.0.1 over localhost
To prevent your app from being broken by misconfigured firewalls or renamed network interfaces, use the IP literal loopback address
127.0.0.1 in your redirect URI instead of
localhost. For example,
You cannot, however, use the Redirect URIs text box in the Azure portal to add a loopback-based redirect URI that uses the
To add a redirect URI that uses the
http scheme with the
127.0.0.1 loopback address, you must currently modify the replyUrlsWithType attribute in the application manifest.
Restrictions on wildcards in redirect URIs
Wildcard URIs like
https://*.contoso.com may seem convenient, but should be avoided due to security implications. According to the OAuth 2.0 specification (section 3.1.2 of RFC 6749), a redirection endpoint URI must be an absolute URI. As such, when a configured wildcard URI matches a redirect URI, query strings and fragments in the redirect URI are stripped.
Wildcard URIs are currently unsupported in app registrations configured to sign in personal Microsoft accounts and work or school accounts. Wildcard URIs are allowed, however, for apps that are configured to sign in only work or school accounts in an organization's Microsoft Entra tenant.
To add redirect URIs with wildcards to app registrations that sign in work or school accounts, use the application manifest editor in App registrations in the Azure portal. Though it's possible to set a redirect URI with a wildcard by using the manifest editor, we strongly recommend you adhere to section 3.1.2 of RFC 6749. and use only absolute URIs.
If your scenario requires more redirect URIs than the maximum limit allowed, consider the following state parameter approach instead of adding a wildcard redirect URI.
Use a state parameter
If you have several subdomains and your scenario requires that, upon successful authentication, you redirect users to the same page from which they started, using a state parameter might be helpful.
In this approach:
- Create a "shared" redirect URI per application to process the security tokens you receive from the authorization endpoint.
- Your application can send application-specific parameters (such as subdomain URL where the user originated or anything like branding information) in the state parameter. When using a state parameter, guard against CSRF protection as specified in section 10.12 of RFC 6749.
- The application-specific parameters will include all the information needed for the application to render the correct experience for the user, that is, construct the appropriate application state. The Microsoft Entra authorization endpoint strips HTML from the state parameter so make sure you are not passing HTML content in this parameter.
- When Microsoft Entra ID sends a response to the "shared" redirect URI, it will send the state parameter back to the application.
- The application can then use the value in the state parameter to determine which URL to further send the user to. Make sure you validate for CSRF protection.
This approach allows a compromised client to modify the additional parameters sent in the state parameter, thereby redirecting the user to a different URL, which is the open redirector threat described in RFC 6819. Therefore, the client must protect these parameters by encrypting the state or verifying it by some other means, like validating the domain name in the redirect URI against the token.
Learn about the app registration Application manifest.