-
Notifications
You must be signed in to change notification settings - Fork 1
Login
There are two types of login flows supported by App Service Authentication: client-directed login and server-directed login. In all cases, the URL for this API is in the form /.auth/login/{provider} where {provider} is the name of a supported identity provider (Azure AD, Google, etc.).
Server-directed login means that the server-side App Service Authentication module controls the provider login flow using a web browser, HTTP redirection, and session cookies. No client-side code is required.
This is the easiest option of the two, but is less flexible compared to client-directed logins. It works best for web apps.
GET /.auth/login/{provider}
The following query string parameters are supported with all identity providers.
| Query String Param | Description |
|---|---|
| post_login_redirect_uri=uri | Specifies a URI to redirect the browser to after a successful login. If not specified, the browser will redirect to /.auth/login/complete. Both absolute and relative URLs are supported. If an absolute URL is specified, it must either match the local domain or the domain must be included in the allowedExternalRedirectUris configuration. |
| session_mode=mode | Specifies whether to return an auth cookie or a session token in the response. When cookie is specified, a AppServiceAuthSession cookie is written back to the browser which can be used to authenticate with the web app. When token is specified, a session token JWT is returned in the fragment part of the URL which can be used to authenticate with the web app. When neither is specified, App Service will guess which mode to use based on the request's User-Agent header, the Referer header, and the configuration of the app. |
| completion_origin=uri | Used for JavaScript popup-window logins. Specifies the HTTP origin of the JavaScript code which initiated the login. This must be the same origin as the web app or it must be an origin in the allowedExternalRedirectUris configuration. |
| completion_type=type | Used for JavaScript popup-window logins. Specifies the protocol which should be used to complete the login process. Different browsers support different protocols. Valid values include iframe and post_message. |
| code_challenge=challenge | Used for PKCE logins from mobile devices. |
| code_challenge_method=method | Used for PKCE logins from mobile devices. Supported values are s256 and plain. |
Individual identity providers also support a range of query string parameters, as described below.
The following query string parameters are supported for Azure AD logins. Full documentation can be found in the Azure AD documentation page.
| Query String Param | Description |
|---|---|
| client_id=guid | The Application ID assigned to your app when you registered it with Azure AD. You can find this in the Azure Portal. It is always a GUID. By default the value of the WEBSITE_AUTH_CLIENT_ID environment variable is used (NOTE: This environment is set automatically when Azure AD is configured via Easy Auth). |
| resource=url | The App ID (URI or GUID) of the web API when requesting access tokens. Valid values can be found in the Azure AD section of the Azure Portal. This configuration is only valid for Azure AD 1.0 apps. Azure AD 2.0 apps should use scopes instead. |
| scope=list | A space-separated list of OpenID Connect scopes supported by Azure AD 2.0. The default values are openid profile email. When requesting access tokens for other services, the desired permissions can be listed here. See the Azure AD scopes documentation for more information. This configuration is only valid for Azure AD 2.0 apps. Azure AD 1.0 apps should use resource instead. |
| response_type=type | The OpenID Connect response type to use in the authentication flow. If not specified, a default is chosen based on the current configuration. If the Azure AD settings include a non-empty client-secret, then this defaults to code id_token. Otherwise, id_token is the default. Other combinations are not supported. |
| response_mode=mode | The OpenID Connection response mode to use in the authentication flow. The only supported value is form_post, and this is the default. However, it is possible to override it with fragment for custom client-side processing, though there is no support or documentation for how to make this work. |
| redirect_uri=uri | The URI where the authentication response should be sent. This must exactly match one of the Reply URL values in your Azure AD configuration. The default value is /.auth/login/aad/callback. |
| domain_hint=domain | Provides a hint about the tenant or domain that the user should use to sign in. The value of the domain_hint is a registered domain for the tenant. If the tenant is federated to an on-premises directory, AAD redirects to the specified tenant federation server. Setting this is recommended for single-tenant applications as it allows bypassing the home realm discovery page. |
| login_hint=email | Can be used to pre-fill the username/email address field of the sign-in page for the user, if you know their username ahead of time. |
| prompt=string | Indicate the type of user interaction that is required. Common values include login, consent, and admin_consent. See the Azure AD docs mentioned previously for more information on these settings. |
| amr_values=list | The required authentication methods. WARNING: This setting is not officially documented by Azure AD, so use with caution. Known values include pwd for password authentication and mfa for Multi-Factor Authentication. Multi-Factor Authentication may not be available for all tenants. |
| msafed=value | App developers can set msafed=0 to disable MSA federation in the AAD login UI. WARNING: This setting is not officially documented by Azure AD, so use with caution. |
| p=b2c_policy | The name of the Azure AD B2C policy to execute. This setting only applies to Azure AD B2C tenants. |
The following query string parameters are supported for legacy Microsoft Account (a.k.a. Live SDK) logins. Note that legacy Microsoft Accounts are no longer supported by Microsoft and official documentation is no longer available. Instead, Microsoft is encouraging all developers to use the new "converged" Azure Active Directory / Microsoft Account applications for any new apps targeting consumers.
I currently use internet archives to lookup the old documentation. For example: https://web.archive.org/web/20140806225539/http://msdn.microsoft.com/en-us/library/hh826528.aspx
| Query String Param | Description |
|---|---|
| scope=list | A space-separated list of OAuth 2.0 scopes supported by Live SDK sign-in. The most common values are wl.offline_access (required for refresh tokens), wl.signin, and wl.basic. If no values are specified, wl.basic is assumed. |
| display | The display type to be used for the authorization page. Valid values are:
|
| locale=locale | A market string that determines how the consent UI is localized. For example, en for English, ja for Japanese, etc. If the value of this parameter is missing or is not valid, a market value is determined by using an internal algorithm. |
| login_hint=email | The email address to pre-populate in the authorization page. |
TODO
TODO
TODO
Client-directed login means that the client (e.g. a mobile app, or JavaScript in a browser) controls the provider login flow. The server-side App Service Authentication module is completely unaware of the interaction between the client and the identity provider. Once the login is complete, the client establishes an auth session with App Service by POST'ing the provider OAuth tokens to the login API. This is the recommended flow for most production applications since it offers the most flexibility.
TODO: Protocol details
POST /.auth/login/aad HTTP/1.1
Content-Type: application/json
{"id_token":"<JWT>","access_token":"<JWT>"}
TODO
TODO
TODO
TODO