You can use an identity header supplied by your organization's authentication gateway to identify users in an on-premises Turnkey application; this page is for administrators configuring TurnkeySettings and modelers who need to resolve external user references.

Use an authentication header as the Turnkey user identity

Header-based authentication is intended for an on-premises Turnkey installation that sits behind an external authentication system, such as Shibboleth. The external system identifies the user before the request reaches Turnkey and adds an HTTP header to the request.

Turnkey reads the configured header value and uses it as the user identity, which is the email identity for SysUser in your model.

Configure the header

1. Open the TurnkeySettings.xml file for the Turnkey installation.
2. Add HeaderBasedAuthenticationTag and set its value to the name of the header provided by the external authentication system.
3. Restart the application if required by your deployment so that it reads the updated settings.

<HeaderBasedAuthenticationTag>The Header you want to catch</HeaderBasedAuthenticationTag>

Replace The Header you want to catch with the actual header name configured by your authentication gateway.

For example, if the gateway supplies the authenticated user's email in a header named X-Authenticated-Email, configure:

<HeaderBasedAuthenticationTag>X-Authenticated-Email</HeaderBasedAuthenticationTag>

The value received in that header is used as the SysUser email identity. Ensure that the external authentication setup supplies a value that matches the identity your application expects.

When the header contains a reference instead of an email

Some authentication systems supply a reference, such as an employee identifier, rather than the user's email address. In that case, add a property to SysUser that records whether the reference has been resolved. For example, add the Boolean property ReferenceIsResolved.

Create a server-side job that finds unresolved users, obtains the corresponding user information from the external system, and marks each resolved reference. The lookup can call an external service with RESTGet when that is how the identity information is available.

Example job logic:

1. Select all SysUser instances for which ReferenceIsResolved is not true.
2. For each user, resolve the external reference, for example by calling the external service with RESTGet.
3. Update the user information required by your model.
4. Set ReferenceIsResolved to true.

Example selection expression:

SysUser.allinstances->select(not ReferenceIsResolved)

This job design prevents the same unresolved reference from being processed again after it has been successfully resolved.

Redirect users after log out

Use AfterLogOutUrl when users should be sent to a specific URL after they log out of Turnkey. This is useful when the external authentication environment owns the wider sign-out journey.

Add the following setting to TurnkeySettings.xml:

<AfterLogOutUrl>https://www.google.se/</AfterLogOutUrl>

Replace the example URL with the required destination.

Verify the setting

When Turnkey finds this setting during startup, the log records it early in application startup. For the example above, the log entry is similar to:

2018-10-18 22:58:24,045 [8] INFO StreamingAppGenericAPIAndControllers.LogUsageTurnkey - OptionalAfterLogOutUrl set to https://www.google.se/

Open a ViewModel when the user selects their name

By default, selecting the logged-in user's name in the header opens Account/Manage. Configure CurrentUserViewModel when that action should instead open a named ViewModel.

Add the ViewModel name to TurnkeySettings.xml:

<CurrentUserViewModel>CurrentUserInfo</CurrentUserViewModel>

In this example, create and maintain a ViewModel named CurrentUserInfo. When the user selects their name in the header, Turnkey navigates to that ViewModel instead of Account/Manage.

Verify the setting

When Turnkey finds this setting during startup, the log records the generated manage-user URL. For the preceding example, the log entry is similar to:

2018-10-18 23:02:20,551 [6] INFO StreamingAppGenericAPIAndControllers.LogUsageTurnkey - ManageUserUrl set to https://localhost:44300/Turnkey/AngularApp#/CurrentUserInfo/$null$

Choose the appropriate authentication approach

Requirement	Use
An upstream authentication gateway places the authenticated identity in every request header.	HeaderBasedAuthenticationTag
Users need to leave Turnkey at a specified URL after log out.	AfterLogOutUrl
Selecting the signed-in user's name should open a ViewModel rather than Account/Manage.	CurrentUserViewModel
Your application uses JWTs to authenticate requests.	Documentation:Authenticate with a jwt
Your application uses social logins and should remove local password registration and login choices.	Documentation:Hide Password login

See also

• Documentation:Hide Password login
• Documentation:Authenticate with a jwt
• Documentation:Access control system in MDriven
• Documentation:Rest API