Controlling the OpenID authentication and more

The settings described below goes into the App_Data/TurnkeySettings.xml file, or in the 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>https://YourTurnkeyURL/signin-oidc</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 : https://YourTurnkeyURL/signin-oidc

Configure the AzureAD

Read here about how to configure the 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>https://cognito-idp.<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://<YourTurnkey>/Account/AWSCognito and the Signout-url to https://<YourTurnkey>

If you have the Authority but hunt for the AuthDomainURL: Take the Authority and append .well-known/openid-configuration

Like this: 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":"https://????.auth.eu-west-1.amazoncognito.com/oauth2/token"

Your AuthDomainUrl is https://????.auth.eu-west-1.amazoncognito.com in the case above.