Keycloak Config - bcgov/SIMS GitHub Wiki

Useful links

Instances

SSO Team

BSCS Integration

Configuring a Keycloak instance

Getting access

  1. Access the master instance with your IDIR account (SSO Team needed to provide access).
  2. Configure the IDIR identity provider and give realm administrator access to your own user.
  3. Access the console link to execute further configurations.

Reference: https://stackoverflow.developer.gov.bc.ca/questions/939/940

Identity Providers

IDIR

This is the only IDP that must be configured while in the master instance.

  • Create a new identity provider as shown below.

image

Where to find credentials (Client ID/Secret)

Access the BCeID - Common Hosted Single Sign-on (CSS) and look for the below information.

image

Configuring mappers

  • identity_provider
    • name: identity_provider
    • Sync Mode: force,
    • Mapper Type: Attribute Importer
    • Claim: identity_provider
    • User Attribute Name: identityProvider

BCeID (basic/business)

  • Create a new identity provider as shown below.

image

Configuring mappers

  • identity_provider
    • name: identity_provider
    • Sync Mode: force,
    • Mapper Type: Attribute Importer
    • Claim: identity_provider
    • User Attribute Name: identity_provider
  • bceid_username
    • name: bceid_username
    • Sync Mode: force,
    • Mapper Type: Attribute Importer
    • Claim: bceid_username
    • User Attribute Name: idp_user_name
  • bceid_business_guid
    • name: bceid_business_guid
    • Sync Mode: force,
    • Mapper Type: Attribute Importer
    • Claim: bceid_business_guid
    • User Attribute Name: bceid_business_guid

BCSC

  • Create a new identity provider as shown below.

image

Configuring mappers

  • identity_provider
    • name: identity_provider
    • Sync Mode: force,
    • Mapper Type: Hardcoded Attribute
    • Claim: identity_provider
    • User Attribute Name: bcsc
  • birthdate
    • name: birthdate
    • Sync Mode: force,
    • Mapper Type: Attribute Importer
    • Claim: birthdate
    • User Attribute Name: birthdate
  • firstName
    • name: firstName
    • Sync Mode: force,
    • Mapper Type: Attribute Importer
    • Claim: given_names
    • User Attribute Name: firstName
  • lastName
    • name: lastName
    • Sync Mode: force,
    • Mapper Type: Attribute Importer
    • Claim: family_name
    • User Attribute Name: lastName
  • username
    • name: username
    • Sync Mode: force,
    • Mapper Type: Username Template Importer
    • Template: ${CLAIM.sub}@bcsc

Client Scopes

  • business-bceid
    • Settings
      • Name: business-bceid
      • Protocol: openid-connect
    • Mappers
      • BCeID Business Guid
        • Name: BCeID Business Guid
        • Mapper Type: User Attribute
        • Token Claim Name: bceid_business_guid
  • client-roles
    • Settings
      • Name: client-roles
      • Protocol: openid-connect
    • Mappers
      • client-roles
        • Name: BCeID Business Guid
        • Mapper Type: User Client Role
        • Token Claim Name: resource_access.${client_id}.roles
  • identity-provider
    • Settings
      • Name: identity-provider
      • Protocol: openid-connect
    • Mappers
      • idpUsername
        • Name: idpUsername
        • Mapper Type: User Attribute
        • User Attribute: idp_user_name
        • Token Claim Name: idp_user_name
        • Claim JSON Type: String
      • Identity Provider
        • Name: Identity Provider
        • Mapper Type: User Attribute
        • User Attribute: identity_provider
        • Token Claim Name: identity_provider
        • Claim JSON Type: String
  • default-name-scope
    • Settings
      • Name: default-name-scope
      • Protocol: openid-connect
    • Mappers
      • lastName
        • Name: lastName
        • Mapper Type: User Property
        • Property: lastName
        • Token Claim Name: lastName
        • Claim JSON Type: String
      • givenNames
        • Name: givenNames
        • Mapper Type: User Property
        • Property: firstName
        • Token Claim Name: givenNames
        • Claim JSON Type: String
  • username
    • Settings
      • Name: username
      • Protocol: openid-connect
    • Mappers
      • userName
        • Name: userName
        • Mapper Type: User Property
        • Property: username
        • Token Claim Name: userName
        • Claim JSON Type: String
  • sims-api-audience-scope
    • Settings
      • Name: sims-api-audience-scope
      • Protocol: openid-connect
    • Mappers
      • sims-api-audience
        • Name: sims-api-audience
        • Mapper Type: Audience
        • Included Custom Audience: sims-api
  • load-test-gateway-audience-scope(!!STRICTLY FOR DEV ENVIRONMENT ONLY!!)
    • Settings
      • Name: load-test-gateway-audience-scope
      • Protocol: openid-connect
    • Mappers
      • load-test-gateway
        • Name: load-test-gateway
        • Mapper Type: Audience
        • Included Custom Audience: load-test-gateway

Allowing mononymous names

By default, if the identity provider does not provide all information to create an account, the user will be redirected to a screen to provide the missing information. To allow users with mononymous names (where the first name is not present), we should disable this behavior, as shown below.

image

Clients

Ministry (AEST)

  • Create the client as below.

image

image

  • Configure Client Scopes as shown below.

image

Groups configurations

The Ministry client is the only one currently using Keycloak groups and roles. The list of groups and roles is kept in the internal Microsoft Teams files General>Files>Analisys>SIMS Users Profiles and Access Permissions.

The below mappers must be created to have "groups" presents on the token.

image image

The roles must be created as shown below.

image

The groups must be created as below.

image

For every group, the specific roles must be configured under the specific client, as shown below.

image

Institution

  • Create the client as below.

image

image

Students

  • Create the client as below.

image

image

Supporting Users (Parent/Partners)

  • Create the client as below.

image

image

Load test gateway (!!STRICTLY FOR DEV ENVIRONMENT ONLY!!)

  • Create the client as below.

image

image

Allowing duplicated user emails

Out-of-box Keycloak is configured to prevent two users to be created using the same email. If the second user is tried to be created and the same email is already associated with a different user, the below error will be displayed on the screen.

image

For non-production environment tests users can share many times the same email. To allow the email duplication we need to explicitly have it configured as below.

image