Keycloak Setup for Institutions

This guide covers configuring Keycloak for institutional usage, including LDAP user federation and SSO integration.

Overview

For production deployments at institutions, you typically need to:

• Federate existing user directories (LDAP/Active Directory)
• Enable Single Sign-On (SSO) with institutional identity providers
• Configure user attribute mapping from the directory to LAREX
• Set up authorization policies based on directory groups

User Federation with LDAP

Enabling LDAP Federation

1. Access Keycloak Admin Console: https://auth.your-domain.com/admin
2. Navigate to User Federation → Add provider → ldap
3. Configure the LDAP connection:

# Example LDAP Configuration
Connection URL: ldap://ldap.institution.edu:389
Users DN: ou=users,dc=institution,dc=edu
Bind DN: cn=admin,dc=institution,dc=edu
Bind Credential: your-service-account-password

4. Set synchronization options:
   • Edit Mode: READ_ONLY (recommended) or WRITABLE
   • Sync Registrations: Enable to import new users
   • User LDAP Mappings: Configure attribute mappings

Supported LDAP Modes

Active Directory Configuration

For Active Directory:

Connection URL: ldap://ad.institution.edu:389
Users DN: CN=Users,DC=institution,DC=edu
Kerberos Realm: INSTITUTION.EDU

LDAP Attribute Mapping

Map LDAP attributes to Keycloak user attributes:

See Keycloak LDAP Documentation for details.

Identity Provider Federation

SAML 2.0 Integration

For SAML-based SSO:

1. Create a new Identity Provider: Identity Providers → Add provider → saml
2. Configure SAML settings:

Single Sign-On Service URL: https://idp.institution.edu/sso
Single Logout Service URL: https://idp.institution.edu/slo
Entity ID: https://auth.your-domain.com/realms/larex
Want AuthnRequests Signed: true

3. Export SP metadata and provide to your IdP administrator

OIDC Integration

For OIDC-based SSO:

1. Create a new Identity Provider: Identity Providers → Add provider → oidc
2. Configure OIDC settings:

Authorization URL: https://idp.institution.edu/authorize
Token URL: https://idp.institution.edu/token
User Info URL: https://idp.institution.edu/userinfo
Client ID: larex-app
Client Secret: your-client-secret

See Keycloak Identity Provider Documentation for details.

Group and Role Management

LDAP Group Mapping

1. Configure LDAP group mapper:
   • Mapper Type: group-ldap-mapper
   • LDAP Groups DN: ou=groups,dc=institution,dc=edu
   • Group Name LDAP Attribute: cn
2. Map LDAP groups to Keycloak roles:

# Example group-to-role mapping
larex-admins -> larex-admin
larex-editors -> larex-editor
larex-viewers -> larex-user

Role-Based Access Control

Configure realm roles in Keycloak:

1. Navigate to Realm Roles → Create
2. Define roles: admin, editor, viewer
3. Assign roles to users or groups

Configure client roles for LAREX:

Client ID: larex-frontend
Roles:
  - user
  - editor
  - admin

See Keycloak Role Documentation for details.

User Session Management

Session Configuration

1. Navigate to Realm Settings → Sessions
2. Configure session settings:

SSO Session Idle Timeout: 8 hours
SSO Session Max Lifespan: 30 days
User Session Max Lifespan: 8 hours
Login Session Timeout: 60 minutes

Token Configuration

Navigate to Realm Settings → Tokens:

Access Token Lifespan: 5 minutes
Access Token Lifespan for Implicit Flow: 15 minutes
Refresh Token Lifespan: 30 days
ID Token Lifespan: 5 minutes

Multi-Realm Setup

For large institutions, consider separate realms:

Email Configuration

For password resets and notifications:

# In compose.prod.yaml
environment:
  MAIL_HOST: smtp.institution.edu
  MAIL_PORT: 587
  MAIL_FROM: noreply@larex.institution.edu

Configure in Keycloak: Realm Settings → Email

Security Considerations

Password Policies

Navigate to Realm Settings → Password Policy:

Type: Password History
History Size: 10
Minimum Length: 12
Maximum Length: 100
Not Username: true

Brute Force Protection

Navigate to Realm Settings → Security Defenses:

Brute Force Detection:
  Enabled: true
  Max Login Failures: 5
  Wait Increment: 1 minute
  Quick Login Check Milliseconds: 500

SSL/TLS Configuration

Ensure HTTPS is enforced:

environment:
  KC_HOSTNAME_STRICT: true
  KC_HOSTNAME_STRICT_HTTPS: true
  KC_PROXY: edge

Troubleshooting

LDAP Connection Issues

# Test LDAP connection
ldapsearch -H ldap://ldap.institution.edu -D "cn=admin,dc=institution,dc=edu" -W -b "dc=institution,dc=edu" "(objectclass=*)"

Sync Issues

Check synchronization logs in Keycloak Admin Console: User Federation → LDAP → Synchronize all users

User Import Issues

1. Verify LDAP attribute mapping
2. Check for duplicate users
3. Ensure required attributes are present

External Resources

• Keycloak Server Administration Guide
• LDAP Federation
• Identity Brokering
• SAML Configuration
• OIDC Configuration

Next Steps

• Environment Variables - Configure email and auth settings
• Service Reference - Keycloak service configuration