Documentation:OpenID config

OpenID config

This page was created by Hans.karlsen on 2018-09-10. Last edited by Wikiadmin on 2026-07-29.

You can configure a Turnkey application to authenticate users through an OpenID Connect identity provider, including Azure AD and Amazon Cognito; this page is for administrators who manage Turnkey settings and provider registrations.

Before you configure OpenID Connect

OpenID Connect lets Turnkey redirect a user to an identity provider (IdP) for authentication and receive signed token information in return. Turnkey can then use claims from the returned tokens, such as an email address or an administrator claim, to create or update the local user record.

You need:

A running Turnkey web application.
An application registration at your IdP.
The client ID, authority URL, callback URL, and, when required, client secret from that registration.
A separate registered callback URL for each environment that users will sign in to, such as local development, test, and production.

For the protocol flow and endpoint discovery, see Documentation:How does OpenIdConnect work. For Azure AD registration steps, see Documentation:Openid AzureAD.

Choose the settings file

Place OpenID Connect settings in the application's App_Data settings files.

File	Read order	When to use it
`TurnkeySettingsExtra.xml`	Before `TurnkeySettings.xml`	Settings that are local to the application or are not managed through the portal.
`TurnkeySettings.xml`	Main settings file	Settings for a local installation, or settings generated when you use the portal.
`TurnkeySettingsOverride.xml`	After `TurnkeySettings.xml`	OpenID Connect settings that must survive a Turnkey refresh or replacement. This is the recommended file for manually maintained OpenID settings.

When you use portal.mdriven.net and select Send Settings And Restart, the portal recreates TurnkeySettings.xml. Put manually maintained OpenID settings in TurnkeySettingsOverride.xml so that operation does not replace them. See Documentation:TurnkeySettings for the complete settings-file behavior.

Configure a standard OpenID Connect provider

Register the callback URL first

Configure this callback URL in the IdP application registration:

https://YourTurnkeyURL/signin-oidc

Use the same value in OpenIDConnectRedirectUrl. The IdP redirects the browser back to this URL with a one-time authorization code appended, for example ?code=xxxx.

Use the /signin-oidc suffix. It identifies the redirect as the OpenID Connect sign-in callback to the middleware. A callback that lacks expected referrer or request details may otherwise not be recognized as the response to a sign-in request.

Register every URL that you use. For example, register both a local URL with its port and the production URL if you sign in from both environments:

https://localhost:5020/signin-oidc
https://app.example.com/signin-oidc

Add the settings

Add the following elements inside the existing root element of your selected Turnkey settings file. Replace every placeholder with values from your IdP.

<OpenID_ClientId>your-client-id</OpenID_ClientId>
<OpenID_Authority>https://your-idp-authority</OpenID_Authority>
<OpenIDConnectRedirectUrl>https://YourTurnkeyURL/signin-oidc</OpenIDConnectRedirectUrl>
<OpenIDConnectResponseType>code id_token</OpenIDConnectResponseType>
<OpenIDConnectAppSecret>your-app-secret</OpenIDConnectAppSecret>
<OpenID_TokenEndPoint>https://your-idp-token-endpoint</OpenID_TokenEndPoint>
<OpenIDConnectScope>offline_access openid profile</OpenIDConnectScope>
<SharedSecret>your-private-shared-secret</SharedSecret>
<ShowPII>true</ShowPII>

Do not use // comments in an XML file. If you need to document a setting, use an XML comment, for example .

Setting reference

Setting	Purpose and use
`OpenID_ClientId`	The client or application ID from the IdP registration.
`OpenID_Authority`	The authority URL of the IdP. The provider's OpenID Connect metadata is normally available at `https://<OpenIdAuthority>/.well-known/openid-configuration`.
`OpenIDConnectRedirectUrl`	The registered callback URL. Use `https://YourTurnkeyURL/signin-oidc` for standard OpenID Connect configuration.
`OpenIDConnectResponseType`	Controls which values are returned during sign-in. Use `code id_token` at minimum; it is also the default when the setting is omitted. Use `code id_token token` when the provider should also return an access token in the response.
`OpenIDConnectAppSecret`	The application secret when the IdP registration requires one.
`OpenID_TokenEndPoint`	The IdP token endpoint. This is needed to obtain an access token and refresh token from an Azure AD login.
`OpenIDConnectScope`	The requested scopes. `openid` identifies an OpenID Connect request; `profile` requests profile access. Include `offline_access` when you need a refresh token. If the IdP supports it and your application needs it, consider adding `email`.
`SharedSecret`	A secret that Turnkey uses to encrypt tokens stored in the database as `SysToken`. Create and protect your own value. Do not share it outside the administrators of the system.
`ShowPII`	Enables personally identifiable information (PII) logging in clear text. Enable it only while diagnosing a problem, then disable it.

Understand tokens and claims

The authorization code is exchanged for tokens. The ID token and access token are normally JWTs (JSON Web Tokens): their payload contains claims in readable Base64-encoded form, and the IdP signs them with its key.

When Turnkey accepts the user, it creates or updates the SysUser and its SysUserClaims links using the claims returned by the provider.

With code id_token, Turnkey receives the authorization code and ID token. With code id_token token, it also receives the access token, unpacks its claims, and adds those claims to the user together with claims from the ID token.

To receive a refresh token for later access-token renewal, both of the following are required:

Request offline_access in OpenIDConnectScope.
Configure the provider token endpoint in OpenID_TokenEndPoint when required, such as for Azure AD.

Azure AD

For Azure AD, the authority has this form:

<OpenID_Authority>https://login.microsoftonline.com/your-authority/</OpenID_Authority>

Use the client ID from the Azure application registration and register the Turnkey callback URL at Azure AD. Follow the full registration and portal configuration procedure in Documentation:Openid AzureAD.

Amazon Cognito

Amazon Cognito is an OpenID Connect IdP that uses a Cognito user pool. Its configuration uses a Cognito-specific callback path and an additional authentication-domain setting.

Configure Cognito and Turnkey

In Cognito, register https://<YourTurnkeyURL>/Account/AWSCognito as the callback URL.
Set the Cognito sign-out URL to https://<YourTurnkeyURL>.
Add the following elements inside the existing root element in a Turnkey settings file:

<OpenID_ClientId>your-cognito-client-id</OpenID_ClientId>
<OpenID_Authority>https://cognito-idp.&lt;Region&gt;.amazonaws.com/&lt;UserPoolId&gt;</OpenID_Authority>
<OpenIDConnectRedirectUrl>https://&lt;YourTurnkeyURL&gt;/Account/AWSCognito</OpenIDConnectRedirectUrl>
<OpenIDConnectResponseType>code</OpenIDConnectResponseType>
<OpenIDConnectAuthDomainUrl>https://&lt;CognitoDomain&gt;.auth.&lt;Region&gt;.amazoncognito.com</OpenIDConnectAuthDomainUrl>
<OpenIDConnectAppSecret>your-optional-app-secret</OpenIDConnectAppSecret>

Find the Cognito authentication domain

If you know the authority but not OpenIDConnectAuthDomainUrl:

Open the authority metadata URL by appending /.well-known/openid-configuration. For example:

https://cognito-idp.eu-west-1.amazonaws.com/eu-west-1_OLSOMETHING7/.well-known/openid-configuration

In the JSON response, find token_endpoint, for example:

https://example.auth.eu-west-1.amazoncognito.com/oauth2/token

Remove /oauth2/token. The remaining value is OpenIDConnectAuthDomainUrl:

<OpenIDConnectAuthDomainUrl>https://example.auth.eu-west-1.amazoncognito.com</OpenIDConnectAuthDomainUrl>

Control the login experience

After external authentication is working, you can decide whether users can also use local passwords or the default external-login buttons.

Goal	Related setting or guidance
Require organization sign-in rather than local password registration	Set `HidePasswordLogin`. See Documentation:Hide Password login.
Use the provider email without asking the user to edit it at first external sign-in	Set `AllowUserToChooseSocialLoginEmail` appropriately and consider `SkipExternalAccountConfirmationScreen`.
Hide the default external-login buttons because you provide your own account UI	Set `HideExternalLogin`. See HowTos:Hide External Login Buttons.

For example, an organization that requires users to authenticate with its IdP can hide password login and skip the first external-account confirmation screen, while retaining the provider-supplied email.

Troubleshoot sign-in

Confirm that the provider registration contains the exact callback URL used in OpenIDConnectRedirectUrl. Scheme, host, path, and local port must match.
Confirm that the callback for standard OpenID Connect ends in /signin-oidc.
Open https://<OpenIdAuthority>/.well-known/openid-configuration to inspect the provider's OpenID Connect contract and locate its endpoints.
For a missing refresh token, verify that offline_access is in the requested scope and that the token endpoint is configured where required.
Enable ShowPII only for focused troubleshooting. It writes PII in clear text; disable it after collecting the required diagnostic information.

Contents