Keycloak Integration

Keycloak Configuration

Client Setup for YuChat

1. Import the web client configuration: yuchat_web.json

   • In General Settings → Valid redirect URIs and Valid post logout redirect URIs, set: https://yuchat.mycompany.com/*
   • Replace with your actual YuChat server endpoint

2. Import the admin console client: yuchat-dashboard.json

   • In General Settings → Valid redirect URIs and Valid post logout redirect URIs, set: https://admin.yuchat.mycompany.com/*
   • Replace with your actual admin console endpoint

3. Import the backend client: yuchat.json

   • On the Credentials tab:
     • Set Client Authenticator to "Client Id and Secret"
     • Generate a secret and copy it to the YuChat backend configuration (keycloak.clientSecret)
   • On the Service accounts roles tab:
     • Add roles: manage-events and manage-users

4. Get the RSA signing key:

   • Go to Realm settings → Keys
   • Copy the Kid of the RS256 key (used for keycloak.sigKeyKid in backend config)

Token Lifetime Settings

Configure in Realm settings → Sessions and Tokens:

Setting	Path	Recommended Value
SSO Session Idle	Sessions → SSO Session Settings	5 days
SSO Session Max	Sessions → SSO Session Settings	10 days
Access Token Lifespan	Tokens → Access tokens	15 min

tip

Adjust token lifetime based on your security requirements. For example, set SSO Session Max to 30 days for monthly re-authentication.

---

LDAP User Synchronization

Migrating users from LDAP to Keycloak enables:

• Centralized session management
• Automatic workspace assignment
• Independent user blocking (separate from LDAP)

note

Each user must have an email address in LDAP (typically the mail attribute). Users without email cannot access YuChat.

Configuration Steps

1. Go to User federation → Add new provider → LDAP

2. Configure connection settings:

   • Set your LDAP server connection parameters
   • In LDAP searching and updating → User DN: specify the OU to migrate
   • In Advanced settings → Trust Email: set to On

3. On the Mappers tab, add attribute mappings (optional):

   LDAP Attribute	YuChat Field
   department	Department
   position	Position
   phone	Phone number
   displayName	Username

warning

After configuration, verify all users are synced correctly by running Actions → Sync All Users.

If ADFS contains users without email addresses, filter them using User LDAP filter:

(&(objectClass=user)
  (objectCategory=person)
  (mail=*)
)

---

Backend Configuration

Client Connection Settings

Add to application.yml:

yuchat:
  client:
    config:
      supportedAuthTypes: "email,keycloak"
      keycloakUrl: "https://auth.yuchat.company.com"
      keycloakRealm: "master"
      keycloakClientId: "yuchat_web"

Server Connection Settings

Add to application.yml:

keycloak:
  enabled: true
  serverUrl: https://auth.yuchat.company.com
  realm: master
  clientId: yuchat
  clientSecret: "${KC_CLIENT_SECRET}"
  sigKeyKid: "${KC_SIG_KEY_SECRET}"

---

User Synchronization to Workspaces

Configure automatic user migration from LDAP to YuChat workspaces.

Add to application.yml:

user:
  sync:
    enabled: true
    cron: "*/5 * * * *"
    lockAtLeastFor: PT3M
    lockAtMostFor: PT6M
    defaultMapping:
      DEPARTMENT: department
      POSITION: position
      PHONE: phone
      ENTRY_DN: entryDn
      FULL_NAME: displayName
    orgUnits:
      - workspaceId: "d16wvhMJkm"
        ldapOU: "dc=company,dc=com"
        updateExisted: false

Configuration Options

Parameter	Description
cron	Sync schedule (cron expression)
lockAtLeastFor	Minimum sync duration (must be ≤ actual sync time)
lockAtMostFor	Maximum sync duration
orgUnits[].workspaceId	Target workspace ID
orgUnits[].ldapOU	Source LDAP organizational unit
orgUnits[].updateExisted	Update existing user attributes on sync

---

Department-Based Synchronization

Automate user assignment to workspaces based on ADFS departments.

Example scenario:

• Single Contacts for the entire organization
• ADFS departments: Sales, Development, Management
• New users automatically added to their department workspace

Configure multiple sync rules:

user:
  sync:
    enabled: true
    cron: "*/1 * * * *"
    lockAtLeastFor: PT1M
    lockAtMostFor: PT2M
    updateExisted: true
    orgUnits:
      # Organization-wide workspace (all users)
      - workspaceId: "d16wvhMJkm"
        ldapOU: "mycompany"
        updateExisted: true
        additionalMapping:
          ENTRY_DN: company_label

      # Sales department
      - workspaceId: "g3jqGXJF7Q"
        ldapOU: "CN=Sales,CN=Users,DC=yuchat,DC=fun"
        updateExisted: true
        additionalMapping:
          ENTRY_DN: memberOf

      # Development department
      - workspaceId: "h78uY3dLSi"
        ldapOU: "CN=Development,CN=Users,DC=yuchat,DC=fun"
        updateExisted: true
        additionalMapping:
          ENTRY_DN: memberOf

      # Management department
      - workspaceId: "h8vM5Yysy0"
        ldapOU: "CN=Management,CN=Users,DC=yuchat,DC=fun"
        updateExisted: true
        additionalMapping:
          ENTRY_DN: memberOf

note

Users with multiple ADFS groups (e.g., Development and Management) will be added to all matching workspaces.

note

When using memberOf synchronization, enable Always Read Value From LDAP in the corresponding Keycloak field mapping.

---

Attribute-Based Filtering

Filter users into workspaces using custom LDAP attributes.

Example: Within the Development department, only sync iOS and Android developers to a Mobile Development workspace.

user:
  sync:
    enabled: true
    cron: "*/1 * * * *"
    updateExisted: true
    orgUnits:
      # iOS developers
      - workspaceId: "h78uY3dLSi"
        ldapOU: "CN=Development,CN=Users,DC=yuchat,DC=fun"
        updateExisted: true
        additionalMapping:
          ENTRY_DN: memberOf
        filterAttributes:
          - name: dev_team
            value: ios
            eqType: LIKE

      # Android developers
      - workspaceId: "h78uY3dLSi"
        ldapOU: "CN=Development,CN=Users,DC=yuchat,DC=fun"
        updateExisted: true
        additionalMapping:
          ENTRY_DN: memberOf
        filterAttributes:
          - name: dev_team
            value: android
            eqType: LIKE

Filter Option	Description
EQ	Exact match
LIKE	Partial string match