View source for Documentation:OpenID config

<message>Write the content here to display this box</message>
=== Controlling the OpenID authentication and more ===
The settings described below goes into the App_Data/[[Documentation:TurnkeySettings|TurnkeySettings]].xml file, or in the [[Documentation:TurnkeySettings|TurnkeySettingsExtra]] file, or the '''TurnkeySettingsOverride.xml''' - use the '''TurnkeySettingsOverride''' to avoid having your settings erased by an upgraded version (that may come with a TurnkeySettings of its own)

=== IdentityServer and Most OpenIDConnect Providers ===
 <OpenID_ClientId>yourid</OpenID_ClientId>
 <OpenID_Authority>youridpserver</OpenID_Authority> 
 <OpenIDConnectRedirectUrl><nowiki>https://YourTurnkeyURL/signin-oidc</nowiki></OpenIDConnectRedirectUrl>   
 <OpenIDConnectResponseType>code id_token</OpenIDConnectResponseType>  
 <OpenIDConnectAppSecret>AppSecret</OpenIDConnectAppSecret> 
 <OpenID_TokenEndPoint>yourserverTokenEndpointUsuallyEndsLikeThis/oauth2/v2.0/token</OpenID_TokenEndPoint> // newly added, needed to get access_token and refresh_token from AzureAD login 
 <OpenIDConnectScope>offline_access openid profile</OpenIDConnectScope> //offline_access must be there for AzureAD to give you the refresh_token 
 <SharedSecret>Secret</SharedSecret>  // this will be used to Encrypt tokens stored in the db (SysToken) 
 <ShowPII>true</ShowPII> // turn on PII level logging in clear text

In the OpenIDConnectResponseType, you should at least state "code id_token" (also default if you leave the tag out completly) - this means that the auth-code will be returned and also the id_token - but you may also extend it to "code id_token token" - and this means that also the access_token is returned. If we see the access_token, we will unpack it - see the claims within - add those claims to the user that now will have claims from the id_token AND the access_token.

As the user is accepted into the Turnkey system, we create/update the SysUser - SysUserClaims link with SysUserClaim objects that match the claims from the provider.

Both the id_token and access_token are normally in the jwt token format; they state the claims in clear text (base64 of payload) and are signed with the key from the IDP.

The OpenIDConnectRedirectUrl is often checked against a list of allowed callers on the IDP side. Make sure you request a few different redirects so that your localhost:xxx, your test, and your production environment all work.

The OpenIDConnectScope is were you state what you will use. You will want the '''openid''' - and probably access to the user '''profile''' - but if you want to be able to get refresh an access_token by using a refresh_token you must state that you will use '''offline_access''' (this means that the your server has a key to request a new access_token even when the initial authorization has been done and gone "offline")

==== Findings ====
The IdentityProvider(IDP) will send an answer to the calling page with a redirect back to us using the OpenIDConnectRedirectUrl - but with appended ?code=xxxx. However, if the request from the IDP lacks a referrer or other details, the middleware will not understand that this is the call that is the callback from the IDP for a login request. To help the middleware understand that the callback really is a login request and should be treated as such, you can send in a redirect URL ending with /signin-oidc - this way the middleware cannot miss what it is supposed to do.

This boils down to you setting the redirect url in for example Azure to : <nowiki>https://YourTurnkeyURL/</nowiki>'''signin-oidc'''

=== Configure the AzureAD ===
Read here about how to configure the [[Documentation:Openid AzureAD|AzureAD IDP]].

=== Amazon Cognito ===
Amazon AWS offers an IdP service (Identity Provider) called Cognito.
* It can be used without cost (volume dependent).
* Cognito offers to create and manage User-pools -> a database where you keep users.
* You can register "applications" in Cognito. By referring to this application, your system can then use the Cognito user pool to authenticate users.
* Cognito also allows for other OpenId providers to be associated with the application. The general idea is to let a built system only know about Cognito and allow users with accounts from Google or others to be trusted with an access token to your AWS resources.
* We mainly want to permit Cognito to be used for authentication.
* Cognito is an OpenIdConnect - but it requires a bit more config to integrate with Turnkey than, for example, AzureAD (which is also an OpenIdConnect provider).
This is what is needed:

 <OpenID_ClientId>20sg2i7fOBFUSCATEDk7c7d9de</OpenID_ClientId>
 <OpenID_Authority><nowiki>https://cognito-idp</nowiki>.<Region>.amazonaws.com/eu-west-1_jrOBFUSCATED6M</OpenID_Authority>  <OpenIDConnectRedirectUrl>https://<YourTurnkeyURL>/Account/AWSCognito</OpenIDConnectRedirectUrl>  <OpenIDConnectResponseType>code</OpenIDConnectResponseType> 
 <OpenIDConnectAuthDomainUrl>https://<CognitoDomain>.auth.<Region>.amazoncognito.com</OpenIDConnectAuthDomainUrl> 
 <OpenIDConnectAppSecret>OptionalAppSecret</OpenIDConnectAppSecret>

These entries must be in the TurnkeySettings.xml found in App_Data

In Cognito, set CallbackUrl to [https://localhost:44300/Account/AWSCognito https://<YourTurnkey>/Account/AWSCognito] and the Signout-url to  [https://localhost:44300/Account/AWSCognito https://<YourTurnkey>]
[[File:2018-09-10 13h38 41.png|none|thumb|742x742px]]If you have the Authority but hunt for the AuthDomainURL: Take the Authority and append [https://cognito-idp.eu-west-1.amazonaws.com/eu-west-1_jrX0cqa6M/.well-known/openid-configuration .well-known/openid-configuration]

Like this: [https://cognito-idp.eu-west-1.amazonaws.com/eu-west-1_OL1wckVh7/.well-known/openid-configuration https://cognito-idp.eu-west-1.amazonaws.com/eu-west-1_OLSOMETHING7/.well-known/openid-configuration]

In the JSON response, look for something like this:
 "token_endpoint":"<nowiki>https://????.auth.eu-west-1.amazoncognito.com/oauth2/token</nowiki>"
Your AuthDomainUrl is https://????.auth.eu-west-1.amazoncognito.com in the case above.

{{Edited|July|12|2025}}


[[Category:Authentication & Security Integration]]
[[Category:Integration]]
[[Category:Intermediate-Friendly]]
[[Category:OAuth2 & OpenID Connect (SSO)]]
[[Category:Priority 50]]