You can use OpenID Connect to sign users in to an MDriven Turnkey application through an external identity provider (IdP), then use the returned claims and tokens in your application.
What OpenID Connect does
OpenID Connect is the sign-in protocol used when Turnkey delegates user authentication to an external identity provider (IdP), such as Azure AD or Amazon Cognito. The IdP authenticates the user and sends Turnkey a response that Turnkey can validate.
After a successful sign-in, Turnkey creates or updates the user and its claims. A claim is a piece of identity information supplied by the IdP, such as a user name, email address, or an authorization-related value. Turnkey creates or updates the SysUser and its SysUserClaim objects to match the provider claims.
For example, a user opens your Turnkey application and selects the OpenID Connect login option. Turnkey redirects the browser to the IdP. After the user signs in, the IdP redirects the browser back to Turnkey. Turnkey validates the response, creates or updates the user claims, and continues to the requested page.
The authorization-code flow
The configured OpenID Connect flow uses a short-lived authorization code before tokens are obtained.
- Turnkey redirects the user's browser to the IdP authorization endpoint.
- The IdP authenticates the user.
- The IdP redirects the browser to the configured callback URL. The redirect includes a one-time code, for example
https://your-turnkey-url/signin-oidc?code=xxxx. - Turnkey receives and processes the code.
- When configured for token retrieval, Turnkey uses the code with the token endpoint to obtain tokens.
- Turnkey validates the sign-in response and updates the signed-in user's claims.
The authorization code is not the access token. It is a temporary value that Turnkey can exchange at the token endpoint. See Documentation:OpenIdConnect access token and refresh token when your application must call an external API after the user has signed in.
Discover the provider endpoints
OpenID Connect providers publish their endpoints and capabilities through a discovery document. Start with the provider authority and request:
https://<OpenIdAuthority>/.well-known/openid-configuration
For Azure AD, the discovery URL has this form:
https://login.microsoftonline.com/{tenantid}/.well-known/openid-configuration
The discovery document identifies provider-specific endpoints even when providers use different endpoint names. For example, when configuring Amazon Cognito, you can inspect the document to find its token endpoint and derive the authentication domain from that endpoint. See Documentation:OpenID config for the Turnkey configuration fields and the Cognito-specific example.
Configure a reliable callback URL
The redirect URL or callback URL is the URL to which the IdP sends the browser after authentication. The IdP normally requires you to register each allowed callback URL in advance.
Use a callback URL that ends in /signin-oidc for the standard Turnkey OpenID Connect flow:
https://YourTurnkeyURL/signin-oidc
Register the exact callback URL with the IdP. Register the URLs needed for each environment, such as local development, test, and production.
The /signin-oidc suffix is important when troubleshooting callbacks. The IdP response can lack referrer or other request details that middleware uses to recognize a login callback. A callback URL ending in /signin-oidc identifies the request as the OpenID Connect sign-in callback so the middleware can process it correctly.
Example callback failure
If the IdP has registered https://test.example.com/signin-oidc, but Turnkey sends https://test.example.com/Account/Login as its redirect URL, the IdP can reject the request or redirect to a URL that Turnkey does not process as an OpenID Connect callback. Configure the same https://test.example.com/signin-oidc value on both sides.
Understand tokens and scopes
An ID token describes the authenticated identity. An access token is used when calling a protected external API. These tokens are normally JWT tokens: their payload claims are readable as Base64-encoded content and the token is signed by the IdP.
The OpenID Connect scope states what Turnkey requests from the IdP. Request openid for OpenID Connect sign-in and commonly profile for profile information. Request offline_access when you need a refresh token for later access-token renewal.
For the configured response type, code id_token requests an authorization code and ID token. Adding token, as in code id_token token, also returns an access token; Turnkey can unpack its claims and add them to the user's claims alongside claims from the ID token.
Do not treat an access token as permanently valid. Access tokens are short-lived. When refresh-token support is configured, Turnkey stores the received access_token and refresh_token claims and can renew the access token through SysUser.OpenIdConnectAccessTokenRefresh():String. This requires the token endpoint, offline_access in the scope for Azure AD, and a SharedSecret to encrypt temporary tokens stored in the database. Follow Documentation:OpenIdConnect access token and refresh token for the complete setup and renewal behavior.
Debug an OpenID Connect sign-in
Use the following sequence to find where a login fails.
- Confirm that the authority discovery URL returns the provider configuration document.
- Confirm that the redirect URL configured in Turnkey exactly matches a callback URL registered at the IdP. Prefer
https://YourTurnkeyURL/signin-oidc. - Start login in a browser and inspect the redirect to the IdP. Verify that the requested redirect URL and scope are the intended values.
- After authentication, inspect the browser redirect back to Turnkey. A successful authorization response includes
?code=.... - Check the Turnkey log to determine the last OpenID Connect notification written before the failure.
- If the code is received but token-related processing fails, verify the configured token endpoint, client details, requested scope, and any required application secret in Documentation:OpenID config.
Turnkey log notifications
Turnkey writes the following OpenID Connect notification messages during the flow. The last relevant message helps locate the failing stage.
| Log notification | Meaning | What to check |
|---|---|---|
OpenId RedirectToIdentityProvider
|
Turnkey is about to redirect the browser to the IdP. | Check the logged redirect URI and response type. |
OpenId MessageReceived
|
Turnkey received an OpenID Connect message. | Confirm that the browser returned to the expected callback URL. |
OpenId AuthorizationCodeReceived
|
Turnkey received the authorization code from the callback. | Confirm that the callback contains code and that the callback uses the configured URL.
|
OpenId SecurityTokenReceived
|
Turnkey received a security token. | Check the provider response and token-related configuration. |
OpenId SecurityTokenValidated
|
Turnkey validated a security token. | Check resulting claims and the user's access rules if sign-in succeeds but access is denied. |
OpenId AuthenticationFailed
|
The OpenID Connect authentication process failed. | Read the logged exception message, then verify callback, provider configuration, and token settings. |
Turnkey can be configured with ShowPII to write personally identifiable information in clear-text logging. Use this only when needed for diagnosis and handle the resulting logs appropriately. See Documentation:OpenID config.
Continue users to the page they requested
When a user reaches a protected ViewModel through a deep link, you can direct an unauthenticated user to the OpenID Connect login flow and return the user to the requested ViewModel after authentication. See Documentation:Deeplink with authentication for the returnUrl pattern and the Account/TryExternalLogin?provider=OpenIdConnect navigation example.
If you need to change the Turnkey login experience, use the account ViewModel override approach described in Documentation:Customizing login and other account UI MVC.