Keycloak Config - bcgov/SIMS GitHub Wiki
Useful links
Instances
- DEV
- TEST
- PRO
SSO Team
- Rocketchat: https://chat.developer.gov.bc.ca/channel/sso
- Wiki: https://github.com/bcgov/sso-keycloak/wiki
- BCeID - Common Hosted Single Sign-on (CSS): https://bcgov.github.io/sso-requests
BSCS Integration
Configuring a Keycloak instance
Getting access
- Access the master instance with your IDIR account (SSO Team needed to provide access).
- Configure the IDIR identity provider and give
realm administrator
access to your own user. - 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.
- Set the below properties and leave the others with the default values, setting [dev/test] accordingly to the environment.
- Alias: idir
- Display name: idir
- First login flow: first broker login
- Sync Mode: force
- Authorization URL: https://[dev/test].loginproxy.gov.bc.ca/auth/realms/standard/protocol/openid-connect/auth?kc_idp_hint=idir
- Token URL: https://[dev/test].loginproxy.gov.bc.ca/auth/realms/standard/protocol/openid-connect/token
- Logout URL: https://[dev/test].loginproxy.gov.bc.ca/auth/realms/standard/protocol/openid-connect/logout
- User Info URL: https://[dev/test].loginproxy.gov.bc.ca/auth/realms/standard/protocol/openid-connect/userinfo
- Client Authentication: Client secret sent as post
- Client ID: provided using the
Common Hosted Single Sign-on
portal (how to get client/secret). - Client Secret: provided using the
Common Hosted Single Sign-on
portal (how to get client/secret). - Validate Signatures: true
- Use JWKS URL: true
- JWKS URL: https://[dev/test].loginproxy.gov.bc.ca/auth/realms/standard/protocol/openid-connect/certs
- Once the IDIR identity provider is configured, find the user and associate the
/Realm Administrator
role to it. - The remaining configurations can be done using the console link.
Where to find credentials (Client ID/Secret)
Access the BCeID - Common Hosted Single Sign-on (CSS) and look for the below information.
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.
- Set the below properties and leave the others with the default values. As per team decision DEV/TEST is pointing to TEST.
- Alias: bceidboth
- Display name: bceidboth
- First login flow: first broker login
- Sync Mode: force
- Authorization URL: https://[dev/test].loginproxy.gov.bc.ca/auth/realms/standard/protocol/openid-connect/auth?kc_idp_hint=bceidboth
- Token URL: https://[dev/test].loginproxy.gov.bc.ca/auth/realms/standard/protocol/openid-connect/token
- Logout URL: https://[dev/test].loginproxy.gov.bc.ca/auth/realms/standard/protocol/openid-connect/logout
- User Info URL: https://[dev/test].loginproxy.gov.bc.ca/auth/realms/standard/protocol/openid-connect/userinfo
- Client Authentication: Client secret sent as post
- Client ID: provided using the
Common Hosted Single Sign-on
portal (how to get client/secret). - Client Secret: provided using the
Common Hosted Single Sign-on
portal (how to get client/secret). - Validate Signatures: true
- Use JWKS URL: true
- JWKS URL: https://[dev/test].loginproxy.gov.bc.ca/auth/realms/standard/protocol/openid-connect/certs
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.
- Set the below properties and leave the others with the default values. DEV/TEST is pointing to TEST.
- Alias: bcsc
- Display name: bcsc
- First login flow: first broker login
- Sync Mode: force
- Authorization URL: https://idtest.gov.bc.ca/login/oidc/authorize
- Token URL: https://idtest.gov.bc.ca/oauth2/token
- User Info URL: https://idtest.gov.bc.ca/oauth2/userinfo
- Client Authentication: Client secret sent as post
- Client ID: saved to "DeltaDocs" by "Tang, Jason AEST:EX"
- Client Secret: saved to "DeltaDocs" by "Tang, Jason AEST:EX"
- Issuer: https://idtest.gov.bc.ca/oauth2/
- Default Scopes: openid profile email address
- Validate Signatures: true
- Use JWKS URL: true
- JWKS URL: https://idtest.gov.bc.ca/oauth2/jwk.json
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
- BCeID Business Guid
- Settings
- 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
- client-roles
- Settings
- 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
- idpUsername
- Settings
- 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
- lastName
- Settings
- 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
- userName
- Settings
- 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
- sims-api-audience
- Settings
- 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
- load-test-gateway
- Settings
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.
Clients
Ministry (AEST)
- Create the client as below.
- Set the below properties
- Access Type: public
- Valid Redirect URIs:
- https://[dev/test]-aest-sims.apps.silver.devops.gov.bc.ca/*
- http://localhost:8080/* (do not add it for PROD)
- Web Origins:
- https://[dev/test]-aest-sims.apps.silver.devops.gov.bc.ca
- http://localhost:8080/* (do not add it for PROD)
- Backchannel Logout Session Required: false
- Disable "Full Scope Allowed" as shown below.
- Configure Client Scopes as shown below.
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.
The roles must be created as shown below.
The groups must be created as below.
For every group, the specific roles must be configured under the specific client, as shown below.
Institution
- Create the client as below.
- Set the below properties
- Access Type: public
- Valid Redirect URIs:
- https://[dev/test]-aest-sims.apps.silver.devops.gov.bc.ca/*
- http://localhost:8080/* (do not add it for PROD)
- Web Origins:
- https://[dev/test]-aest-sims.apps.silver.devops.gov.bc.ca
- http://localhost:8080 (do not add it for PROD)
- Backchannel Logout Session Required: false
- Configure Client Scopes as shown below.
Students
- Create the client as below.
- Set the below properties
- Access Type: public
- Valid Redirect URIs:
- https://[dev/test]-aest-sims.apps.silver.devops.gov.bc.ca/*
- http://localhost:8080/* (do not add it for PROD)
- Web Origins:
- https://[dev/test]-aest-sims.apps.silver.devops.gov.bc.ca
- http://localhost:8080 (do not add it for PROD)
- Backchannel Logout Session Required: false
- Configure Client Scopes as shown below.
Supporting Users (Parent/Partners)
- Create the client as below.
- Set the below properties
- Access Type: public
- Valid Redirect URIs:
- https://[dev/test]-aest-sims.apps.silver.devops.gov.bc.ca/*
- http://localhost:8080/* (do not add it for PROD)
- Web Origins:
- https://[dev/test]-aest-sims.apps.silver.devops.gov.bc.ca
- http://localhost:8080 (do not add it for PROD)
- Backchannel Logout Session Required: false
- Configure Client Scopes as shown below.
Load test gateway (!!STRICTLY FOR DEV ENVIRONMENT ONLY!!)
- Create the client as below.
-
Set the below properties
- Access Type: confidential
- Service Accounts Enabled: ON
- Valid Redirect URIs:
-
Make sure in credentials tab the right client authenticator is selected
-
Configure Client Scopes as shown below.
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.
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.