Skip to main content

SSO Configuration via ADFS

Onprem or Cloud​

SSO can be configured in both the cloud version and Onprem installation. The beginning of the article describes Onprem setup, and the end of the article covers Cloud.

Onprem: Prerequisites​

Required for configuration:

  • Microsoft Windows Server 2019 with AD and AD FS configured
  • YuChat Keycloak server (included in delivery)

HTTPS must be correctly configured on the services:

tip

For proper operation, global certificates are required for AD FS and Keycloak.

note

Recommendation: use a separate realm on the Keycloak side for AD FS SSO authorization.

Adding Keycloak as a client in AD FS​

We will use AD FS as a trusted provider, so Keycloak must be defined as an OAuth 2 client. To do this, you need to create an Application Group in ADFS, which models a set of protected resources and clients that can access them.

OAuth distinguishes between 2 types of clients: public and confidential. The former work on devices under the end user's control, for example, in a browser on a desktop or phone, while the latter work in the backend. Microsoft calls these applications native and server respectively. In this integration, server application configuration is required.

Keycloak will receive an ID token as a client, then create an identity based on the claims in the AD FS ID token. However, some information we need is not available as a standard ID token claim, so you additionally need to configure custom claims. To configure this, you need to create an API in the Application Group.

Create Server Application In Application Group​

In AD FS, open 'Application Groups', and click 'Add Application Group…' in the context menu.

Adding server to adfs

Use the following settings:

The redirect URI will differ if you create multiple realms in Keycloak. We can check this URI later during Keycloak configuration. Confirm the configuration and complete the application creation.

Check the configuration and complete the setup. The 'keycloak' application should appear in the 'Application Groups' folder after completion.

Adding server to adfs - result

Create Api​

To configure the token returned to Keycloak, you need to create a server API. To create it, double-click on 'keycloak' in the application group folder, and select 'Add application…'.

Adding api to adfs

Use the following settings:

  • Name: keycloak - API (or another name)
  • Identifier: keycloak (must match the Client Identifier field in the server application)
  • Access control policy: Permit everyone
  • Permitted scopes: select allatclaims in addition to openid which is selected by default

The allatclaims scope is intended to copy all fields from the access token to the id token from AD FS for transmission to Keycloak.

Check the configuration and complete the API setup. After completion, you will see the created API in the server application 'keycloak'.

Adding api to adfs - result

Configure Data Field Mapping​

The AD FS configuration is almost ready, but for correct user identification in YuChat Keycloak, data field correspondence configuration is necessary. For correct operation, the following fields must be passed: email, given_name, and family_name. Since we have already configured the transmission of all fields through allatclaims, this data will already be contained in the id token transmitted to Keycloak.

Open the server application 'keycloak' and double-click on 'keycloak - Web API' to open the configuration. Go to the 'Issuance Transform Rules' tab and click 'Add Rule…'. We will use the 'Send LDAP Attributes as Claims' template to transmit fields.

Use the following configuration:

  • Claim rule name: Attributes (or another name)
  • Attribute store: Active Directory
  • Mappings:
    • E-Mail-Addresses => email
    • Given-Name => given_name
    • Surname => family_name

The fields email, given_name, family_name will not be displayed in the dropdown list, you need to add these values manually.

Adding field mapping in adfs

If necessary, you can add other attributes. The example above shows the required values necessary for correct YuChat operation. This data is necessary for automatically creating a username on first login to YuChat.

Adding AD FS as an authorization provider​

In the previous sections, Keycloak was added as a client to AD FS, now you need to configure Keycloak and add AD FS as the main authorization method in YuChat.

Import AD FS configuration to Keycloak​

  1. In the Keycloak web interface, select your realm and in the identity-providers tab add "OpenID Connect v1.0".
Adding openid provider to keycloak
  1. Paste the link to the OpenID Connect provider configuration leading to your AD FS in the Discovery endpoint field. You can check if the configuration document is available by sending a GET request using any HTTP client - browser, curl or Postman. The response to the request will be a JSON document.
curl  https://fs.domain.com/adfs/.well-known/openid-configuration
  1. Change the following values:
  • Alias: ADFS (this alias is used in forming the redirect URL)
  • Client ID: keycloak (must match the Client Identifier configured in AD FS)
  • Client Secret: this secret was created during the creation of the server application in AD FS

Save the configured identity provider.

  1. Open the configuration of the created provider again and configure the field:
  • Disable User Info: ON

This setting must be turned off because the token has already been modified on the AD FS side for transmission to Keycloak.

Check the configuration of the new provider in Keycloak again, in particular all 'Redirect URI' which should correspond to the settings in AD FS and save the form.

Configure field mapping in Keycloak​

Keycloak receives information from AD FS and saves it in the local database for further transmission to YuChat. For correct authorization in YuChat and displaying user names, field mapping must be configured.

Open the provider created in the previous step, go to the 'Mappers' tab and add 3 rules, each of which will use the 'Attribute Importer' type:

  • email => email
  • given_name => firstName
  • family_name => lastName
Adding mapping to keycloak

Configure end-to-end SSO via AD FS​

Keycloak is used as a single authorization tool in YuChat. You can also configure end-to-end authorization via AD FS. To do this, you need to create a new scheme for browser authentication.

  1. Go to the Authentication section
  2. Create a new flow by copying the existing "browser" configuration, to do this click the three dots at the end of the line and Duplicate
  3. Enter a name for the new configuration (yuchat-adfs-flow) go to the settings
  4. Configure Identity Provider Redirector (you need to click the gear on the line) and enter the Alias created during the configuration import stage in Keycloak
    redirect to adfs
    tip

    You must specify the name of the Identity provider in the Default Identity Provider field

    note

    The Default Identity Provider field is case-sensitive, you must ensure that the Default Identity Provider name is specified in the same case as in the Alias field for the current Identity Provider

  5. Required as a parameter for Identity Provider Redirector
  6. Remove the step "Username, password, otp and other auth forms" from the list of authorization steps
    authentication settings
tip

After applying the settings, when clicking the "Login via SSO" button in the YuChat interface, the user will be redirected directly to the ADFS authorization form (for example, already authorized in the Outlook Web Interface). If the user is already authorized in AD FS, they will immediately get to YuChat (even on first login)

Using SSO together with user migration to teams​

To combine the functionality of user migration to existing teams (for example, when using groups from ADFS), you need to add user migration from LDAP to the same Realm used for the single sign-on system.

tip

Configure field migration from LDAP/ADFS at the LDAP level.

  1. Configure user migration from LDAP together with field mapping

    note

    You must ensure that the migration configuration from LDAP and the attribute mapping of the Identity Provider ADFS are configured correctly. It is important that the username and email fields are configured the same in both configurations

  2. In Keycloak go to "Authentication" settings and add a new scheme.

    • "Create scheme", enter scheme name, for example "First login link"
    • Add steps "Detect existing broker user" and "Automatically set existing user". You must also add "Required" type for both steps
      First login link

  3. Configure the adfs created earlier

    • In the "First login flow override" field add the configuration made in step 2 (First login link)
    • Change the "Sync mode" field to "Import"
    • Save the configuration
      tip

      After applying the configuration, make sure that all users from LDAP have been migrated and are displayed in the Users tab of the Keycloak interface. To check the configuration, log in using AD FS SSO and make sure that an ADFS provider has appeared in the "Identity provider links" tab (correct linking of the user from AD FS to the user from LDAP has occurred)

Cloud: Prerequisites​

Required for configuration:

  • Microsoft Windows Server 2019 with AD and AD FS configured.
  • Paid Cloud Pro and higher tariffs

Create Server Application In Application Group​

In AD FS, open 'Application Groups', and click 'Add Application Group…' in the context menu.

Adding server to adfs

Use the following settings:

Check the configuration and complete the setup. The 'keycloak' application should appear in the 'Application Groups' folder after completion.

Adding server to adfs - result

Create Api​

To configure the token returned to Keycloak, you need to create a server API. To create it, double-click on 'keycloak' in the application group folder, and select 'Add application…'.

Adding api to adfs

Use the following settings:

  • Name: keycloak - API (or another name)
  • Identifier: keycloak (must match the Client Identifier field in the server application)
  • Access control policy: Permit everyone
  • Permitted scopes: select allatclaims in addition to openid which is selected by default

The allatclaims scope is intended to copy all fields from the access token to the id token from AD FS for transmission to Keycloak.

Check the configuration and complete the API setup. After completion, you will see the created API in the server application 'keycloak'.

Adding api to adfs - result

Configure Data Field Mapping​

For mapping user properties in YuChat, data field correspondence configuration is necessary. For correct operation, the following fields must be passed: email, given_name, and family_name. Since we have already configured the transmission of all fields through allatclaims, this data will already be contained in the id token.

Open the server application 'keycloak' and double-click on 'keycloak - Web API' to open the configuration. Go to the 'Issuance Transform Rules' tab and click 'Add Rule…'. We will use the 'Send LDAP Attributes as Claims' template to transmit fields.

Use the following configuration:

  • Claim rule name: Attributes (or another name)
  • Attribute store: Active Directory
  • Mappings:
    • E-Mail-Addresses => email
    • Given-Name => given_name
    • Surname => family_name

The fields email, given_name, family_name will not be displayed in the dropdown list, you need to add these values manually.

Adding field mapping in adfs

If necessary, you can add other attributes. The example above shows the required values necessary for correct YuChat operation. This data is necessary for automatically creating a username on first login to YuChat.

Complete Setup​

Now you need to contact YuChat support to activate ADFS integration in the cloud.

Recommended message to support:

tip

Hello! We need to configure single sign-on (SSO) in YuChat Cloud via our corporate ADFS.

  • Organization name
  • Address where your AD FS is available
  • Credentials: Generate a shared secret from the Create Server Application In Application Group step

You can send a request through the support portal https://yuchat.ai/support or by email: support@yuchat.ai

Last updated on