Skip to main content

SSO Configuration via ADFS

Prerequisites​

Required:

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

HTTPS Configuration:

  • AD FS: https://fs.domain.com
  • YuChat Keycloak: https://kc-yuchat.domain.com
tip

Global certificates are required for both AD FS and Keycloak.

note

We recommend using a dedicated Keycloak realm for AD FS SSO authorization.

Configuring AD FS​

AD FS serves as the trusted identity provider. Keycloak connects as an OAuth 2 client.

Create Application Group​

  1. In AD FS, open Application Groups → right-click → Add Application Group
Adding server application to AD FS

  1. Configure with these settings:

    • Client Identifier: keycloak
    • Redirect URI: https://kc-yuchat.domain.com/auth/realms/yuchat/broker/ADFS/endpoint (adjust realm name as needed)
    • Credentials: Generate a shared secret — save it for later

  2. Complete the wizard. The keycloak application appears in the Application Groups folder.

Application group created

Create API​

  1. Double-click keycloak in Application Groups → Add application
Adding API to AD FS
  1. Configure:
    • Name: keycloak - API
    • Identifier: keycloak (must match Client Identifier above)
    • Access control policy: Permit everyone
    • Permitted scopes: Select allatclaims and openid

The allatclaims scope copies all access token fields to the ID token for Keycloak.

API configuration complete

Configure Claim Mappings​

Required fields for YuChat: email, given_name, family_name

  1. Open the keycloak application → double-click keycloak - Web API
  2. Go to Issuance Transform Rules → Add Rule
  3. Select template: Send LDAP Attributes as Claims

Configure:

  • Claim rule name: Attributes
  • Attribute store: Active Directory
  • Mappings:
    • E-Mail-Addresses → email
    • Given-Name → given_name
    • Surname → family_name
note

The fields email, given_name, family_name must be entered manually — they don't appear in the dropdown.

Claim mapping configuration

Configuring Keycloak​

Import AD FS as Identity Provider​

  1. In Keycloak, select your realm → Identity Providers → Add OpenID Connect v1.0
Adding OpenID provider to Keycloak
  1. Get the discovery endpoint URL:
curl https://fs.domain.com/adfs/.well-known/openid-configuration

  1. Configure:

    • Alias: ADFS (used in redirect URL)
    • Discovery endpoint: Your AD FS OpenID configuration URL
    • Client ID: keycloak (must match AD FS Client Identifier)
    • Client Secret: The secret generated in AD FS

  2. Save, then reopen and set:

    • Disable User Info: ON

  3. Verify the Redirect URI matches AD FS configuration

Configure Attribute Mapping​

  1. Open the ADFS identity provider → Mappers tab
  2. Add three rules using Attribute Importer type:
ClaimUser Attribute
emailemail
given_namefirstName
family_namelastName
Keycloak attribute mappers

Transparent SSO​

Enable automatic redirection to AD FS login.

  1. Go to Authentication
  2. Duplicate the browser flow → name it yuchat-adfs-flow
  3. Configure Identity Provider Redirector:
    • Click the gear icon
    • Set Default Identity Provider to your ADFS alias
Identity provider redirector
tip

The Default Identity Provider field is case-sensitive. It must exactly match the Alias.

  1. Set Identity Provider Redirector to Required
  2. Remove "Username, password, otp and other auth forms" from the flow
Browser authentication flow
tip

With transparent SSO, clicking "Login via SSO" in YuChat redirects directly to AD FS. Users already authenticated (e.g., via Outlook Web) enter YuChat immediately.

Combining SSO with Workspace Sync​

To use SSO together with automatic workspace assignment, add LDAP user migration to the same Keycloak realm.

tip

Configure attribute mapping at the LDAP level, not the identity provider level.

Configuration Steps​

  1. Configure LDAP user migration with attribute mapping
note

Ensure LDAP and Identity Provider configurations use consistent username and email field mappings.

  1. In Keycloak → Authentication, create a new flow:
    • Name: First login link
    • Add steps:
      • Detect existing broker user (Required)
      • Automatically set existing user (Required)
First login link flow
  1. Update your ADFS identity provider:
    • Set First login flow override to First login link
    • Set Sync mode to Import
tip

After configuration, verify that:

  • All LDAP users appear in Keycloak's Users tab
  • SSO login creates an "Identity provider links" entry connecting the AD FS identity to the LDAP user
Last updated on