You can let users sign in to your Turnkey application with your organization's Azure AD identity by registering the Turnkey site as an OpenID Connect application and configuring its Azure AD values in Turnkey.
OpenID Connect is the authentication protocol between Turnkey and an identity provider (IDP). Azure AD is the IDP: it authenticates the user, then redirects the browser back to your Turnkey application. Turnkey uses the returned identity information to create or update the local user record.
Before you begin
You need:
- A working Turnkey web application with a stable HTTPS URL.
- Permission to register applications in your organization's Azure AD.
- Access to the Azure portal and to the Turnkey configuration method you use: the Turnkey portal or a settings file.
Plan the URLs before registration. Azure AD checks the redirect URI against the URIs registered for the application. Register a callback for each environment that users will sign in to, such as local development, test, and production.
For a Turnkey site at https://contoso.example, use this callback URI:
https://contoso.example/signin-oidc
The /signin-oidc ending identifies the request as the OpenID Connect sign-in callback. Do not use the normal /Account/Login URL as the OpenID Connect redirect URI.
Register the application in Azure AD
- Sign in to the Azure portal.
- Open Azure Active Directory.
- Note the directory identifier you will use as the Azure AD authority. This is commonly referred to in this configuration as the authority name or tenant identifier.
- Open App registrations, then select New application registration.
- Enter a readable application name. For example,
Contoso Turnkey Production. - Register the Turnkey callback URI, for example
https://contoso.example/signin-oidc. - Complete the registration.
- From the registered application's overview, copy the Application ID. This is the OpenID client ID used by Turnkey.
Keep the Application ID and authority identifier available while configuring Turnkey.
Map Azure AD values to Turnkey settings
The Azure AD authority has this form:
https://login.microsoftonline.com/<your authority>/
For example, if the authority identifier is contoso-tenant, configure:
https://login.microsoftonline.com/contoso-tenant/
| Azure AD value | Turnkey setting | Example |
|---|---|---|
| Application ID | OpenID_ClientId
|
00000000-0000-0000-0000-000000000000
|
| Authority name or tenant identifier | OpenID_Authority
|
https://login.microsoftonline.com/contoso-tenant/
|
| Registered callback URI | OpenIDConnectRedirectUrl
|
https://contoso.example/signin-oidc
|
Configure Turnkey
Choose one configuration approach. The settings have the same meaning in either approach.
Configure in a settings file
Follow OpenID configuration for the supported settings-file locations. To prevent an upgrade from replacing your changes, use TurnkeySettingsOverride.xml when that is appropriate for your deployment.
Add the Azure AD values inside the settings XML. Replace the example values with the values from your Azure AD registration:
<OpenID_ClientId>00000000-0000-0000-0000-000000000000</OpenID_ClientId>
<OpenID_Authority>https://login.microsoftonline.com/contoso-tenant/</OpenID_Authority>
<OpenIDConnectRedirectUrl>https://contoso.example/signin-oidc</OpenIDConnectRedirectUrl>
<OpenIDConnectResponseType>code id_token</OpenIDConnectResponseType>
Restart the application after changing its settings so that it loads the new OpenID configuration.
Configure through the Turnkey portal
If you configure OpenID through portal.mdriven.net:
- Open the settings for the target Turnkey application.
- Enter the Application ID as the OpenID client ID.
- Enter the Azure AD authority as
https://login.microsoftonline.com/<your authority>/. - Enter the registered callback URI, ending in
/signin-oidc. - Select Send Settings And Restart.
- Save the portal configuration.
The Azure AD registration and the Turnkey redirect setting must match exactly, including the scheme, host, path, and trailing path segment.
Verify sign-in
- Open the Turnkey application's login page.
- Select the OpenID sign-in button.
- Confirm that the browser is redirected to the configured Azure AD authority.
- Sign in with a user permitted by the Azure AD application registration.
- Confirm that Azure AD redirects the browser to
https://<your Turnkey URL>/signin-oidcand that Turnkey signs the user in.
On the first successful external sign-in, Turnkey creates a SysUser object. On sign-in, Turnkey also creates or updates SysUserClaim objects from claims supplied by the provider. This lets the Turnkey application retain the user and the identity claims received from Azure AD.
Optional: obtain access and refresh tokens
Basic sign-in does not require token-refresh configuration. If your application must use an Azure AD access token after sign-in, for example to call GraphAPI services, configure the token endpoint, request offline_access, and configure a shared secret for encrypted token storage.
The relevant settings are described in OpenIdConnect access token and refresh token. In particular:
OpenID_TokenEndPointis required to obtain access and refresh tokens from Azure AD.OpenIDConnectScopemust includeoffline_accessfor Azure AD to issue a refresh token.SharedSecretencrypts temporary tokens stored in the database.
Troubleshoot redirect and callback problems
If Azure AD reports that the redirect URI is invalid, compare the registered URI and OpenIDConnectRedirectUrl character for character. Register separate callback URIs for each local, test, and production address that you use.
If Azure AD authenticates the user but Turnkey does not complete sign-in, verify that the callback ends in /signin-oidc. The identity provider returns to this URL with an appended authorization code, such as ?code=...; the callback suffix helps the middleware recognize that return request as an OpenID Connect login callback.
To inspect the provider's OpenID Connect contract, open:
https://login.microsoftonline.com/<tenantid>/.well-known/openid-configuration
For the authentication flow and the Turnkey OpenID logging points, see How does OpenIdConnect work.
Related sign-in choices
If Azure AD should be the only sign-in route, review Hide Password login before hiding local password registration and login. This page covers browser-based Turnkey sign-in; a JavaScript client that authenticates to Turnkey APIs follows the separate SPA integration pattern.