Using Keycloak as Identity Provider
For this setup to work, it is needed that the IriusRisk instance has a public endpoint. In this tutorial we will use a localhost endpoint as an example.
Set certificates
This task needs to be done by the owner of the instance where IriusRisk is running. If it is a SaaS instance, Continuum will need to execute this, if the instance is on-prem, the customer needs to execute this. You can use auto-signed certificates or import CA signed ones.
Generate auto-signed certificates
Generate a keypair to use as the Service Provider key and put it in a JKS store.
Enter the iriusrisk-tomcat8 container:
$ docker exec -it iriusrisk-tomcat8 sh
Execute key generation procedure. The default password for the keystore it "changeit". There is no need to fill the information about the name/country etc, but providing a password is mandatory. We will also use “iriusrisk-sp” as key password.
$ keytool -genkey -alias "iriusrisk-sp" -validity 1825 -keyalg RSA -keystore /etc/ssl/certs/java/cacerts
Check that the key is properly generated and is present in the keystore:
$ keytool -list -keystore /etc/ssl/certs/java/cacerts | grep iriusrisk-sp -A 1
Enter keystore password: changeit
iriusrisk-sp, Feb 4, 2021, PrivateKeyEntry,
Certificate fingerprint (SHA1): 92:E9:7A:34:BD:B5:97:47:80:22:DA:60:6B:ED:A6:B0:FC:BE:5B:E1
Exit the container and copy the keystore outside:
$ exit
$ docker cp iriusrisk-tomcat8:/etc/ssl/certs/java/cacerts iriusrisk-sp.jks
Import CA signed certificates (optional)
When you get your certificates form the CA, you will have 2 important files (names are just an example):
- 4c62d535c32f5d28.pem - the public certificate with signed CA certification chain
- customer_iriusrisk_com.key - private key for the certificate
TIP: in order to inspect the contents of the PEM certificate, execute:
$ openssl x509 -in 4c62d535c32f5d28.pem -text -noout
First, let's create a PKCS12 file that combines the both mentioned files:
$ openssl pkcs12 -export -in 4c62d535c32f5d28.pem -inkey customer_iriusrisk_com.key -out iriusrisk-sp.p12 -name iriusrisk-sp
After, import the resultant into a new Java Key Store:
$ keytool -importkeystore -deststorepass iriusrisk-sp -destkeystore iriusrisk-sp.jks -srckeystore iriusrisk-sp.p12 -srcstoretype PKCS12 -alias iriusrisk-sp
In order to inspect the contents of the JKS file, execute:
$ keytool -list -v -keystore iriusrisk-sp.jks
Configure IriusRisk client application in Keycloak
Make sure to have a realm
A realm in Keycloak is the equivalent of a tenant. It allows creating isolated groups of applications and users. By default there is a single realm in Keycloak called master
. This is dedicated to manage Keycloak and should not be used for your own applications.
If you don't have a dedicated realm, create a new one.
-
Open the Keycloak Admin Console
-
Hover the mouse over the dropdown in the top-left corner where it says
Master
, then click onAdd realm
-
Fill in the form with the following values:
-
Name:
IriusRisk-realm
-
-
Click
Create
Check your users
Make sure your realm have users in it.
All users should have an email and password set.
In order to test your user's ability to login into the Keycloak you can try to so following the URL (substituting IriusRisk-realm for your own realm ID):
http://localhost:8180/auth/realms/IriusRisk-realm/account/
Create user groups
User groups will map to IriusRisk roles and thus give a set of predefined permissions to each user once he logs in into IriusRisk.
In the Groups menu create the groups you want to map:
After that add the desired users to each group:
Create new client application
Go the Clients
menu and hit Create
button on the top right corner.
Set the your designated ID for IriusRisk and select saml protocol.
In the Client Settings screen leave everything by default and feel the following fields:
Remember to substitute protocol and localhost by your own IriusRisk endpoint and iriusrisk-app by your designated client id.
Import generated certificate
This new client application will need to know the public certificate used by IriusRisk to sign its messages. In the SAML Keys
tab hit the button Import
and provide the iriusrisk-sp key from JKS store created in the beginning of this tutorial.
Add attributes to SAML response
You'll also need to add some mandatory fields into your SAML response. This can be configured in Mappers
section.
First hit Mappers
-> Create
button on the top right corner and create User Property mappers for:
- username
- firstName
- lastName
We'll also need to include an attribute for send group list the user is member of.
The final result should look like this:
Download idp.xml
At this point we completed all the configuration needed in Keycloak side. To conclude go to Realm Settings
-> General
tab, download SAML 2.0 Identity Provider Metadata and save it as idp.xml in the IriusRisk server.
Configure IriusRisk local application
For this setup we will need to configure some files, this is the complete listing of files you will end up having on the docker folder of the instance:
-
cert.pem (nginx public cert)
-
key.pem (nginx private cert)
-
docker-compose.yml (we will configure it in this section)
-
idp.xml (metadata downloaded and renamed from Keycloak)
-
sp.xml (metadata that will be downloaded from IriusRisk)
-
iriusrisk-sp.jks (created in the first step of this guide)
-
SAMLv2-config.groovy (we will configure it in this section)
docker-compose.yml (temporary version)
Create a “docker-compose.yml” file with the following content. Remember to configure NG_SERVERNAME, IRIUS_DB_URL, and IRIUS_EXT_URL with the correct values of your instance endpoints as this is an example file:
version: '3' services: nginx: ports: - "80:80" - "443:443" environment: - NG_SERVER_NAME=localhost links: - tomcat8 image: continuumsecurity/iriusrisk-prod:nginx-prod-ssl container_name: iriusrisk-nginx volumes: - "./cert.pem:/etc/nginx/ssl/star_iriusrisk_com.crt" - "./key.pem:/etc/nginx/ssl/star_iriusrisk_com.key" tomcat8: environment: - IRIUS_DB_URL=jdbc\:postgresql\://172.17.0.1\:5432/iriusprod?user\=iriusprod&password\=alongandcomplexpassword2523 - IRIUS_EDITION=saas - IRIUS_EXT_URL=http\://localhost - grails_env=production - CATALINA_OPTS="-Dsaml.config.path=/etc/irius/SAMLv2-config.groovy" image: continuumsecurity/iriusrisk-prod:tomcat8-2 container_name: iriusrisk-tomcat8 volumes: - "./SAMLv2-config.groovy:/etc/irius/SAMLv2-config.groovy" - "./idp.xml:/etc/irius/idp.xml" - "./iriusrisk-sp.jks:/etc/irius/iriusrisk-sp.jks"
SAMLv2-config.groovy
Create a “SAMLv2-config.groovy” file in IriusRisk server:
grails { plugin { springsecurity { saml { // Activate SAML integration with IriusRisk active = true
// Base to generate URLs for this server. For example: https://my-server:443/app. The public address your server will be accessed from should be used here. entityBaseUrl = 'http://localhost'
// Custom entity id for the instance if it doesn't exist it is set to iriusrisk-sp by default
entityId = 'iriusrisk-app'
// Mapping User fields to SAML fields, e.g: [firstName: givenName], firstName is the user field in IriusRisk (do not change), givenName is SAML field userAttributeMappings = [ 'username' : 'email', 'firstName': 'firstName', 'lastName' : 'lastName', 'email' : 'email' ]
// SAML assertion attribute that holds returned group membership data
userGroupAttribute = 'memberOf'
// Custom Values, mapping Keycloak Group names with (/) prefix (used as keys in the configuration map userGroupToRoleMapping) to Irius RoleGroup names (used as values in the configuration map userGroupToRoleMapping) userGroupToRoleMapping = [ '/IDP_ROLE_ADMIN':'ROLE_ADMIN', '/IDP_ROLE_DEVELOPER':'ROLE_DEVELOPER', '/IDP_ROLE_PORTFOLIO_VIEW':'ROLE_PORTFOLIO_VIEW' ] // If there is no information about roles in the SAML Response, IriusRisk will use this property to assign a default role to the User defaultRole = 'ROLE_PORTFOLIO_VIEW'
// force SHA256 encryption
signatureAlgorithm = 'rsa-sha256'
digestAlgorithm = 'sha256'
metadata { // Relative URL in IriusRisk to download sp.xml metadata url = '/saml/metadata' // Provider to be used from the configuration map providers defaultIdp = 'keycloak' // Configuration map providers, using the name of the provider as key and the file system path to the xml descriptor file from IDP providers = [ keycloak :'/etc/irius/idp.xml'] idp { title = 'Keycloak-SAML login caption' } sp { file = '/etc/irius/sp.xml' defaults = [
// alias should correspond to your entity id alias: 'iriusrisk-app', signingKey: 'iriusrisk-sp', encryptionKey: 'iriusrisk-sp', tlsKey: 'iriusrisk-sp', ] } } keyManager { storeFile = 'file:/etc/irius/iriusrisk-sp.jks' storePass = 'changeit' passwords = [ 'iriusrisk-sp': 'iriusrisk-sp' ] defaultKey = 'iriusrisk-sp' } } } } }
Remember to change some parameters:
-
entityBaseUrl - public URL endpoint of your IriusRisk instance
- entityId - custom entity ID set to identify IriusRisk application in Keycloak (Note: if setting custom entity this must be reflected in the "alias:" definition under the sp configuration)
-
userGroupToRoleMapping - map you Keycloak group IDs to IriusRisk roles
NOTE: Keycloak add a slash (/) prefix to all the groups sent to IriusRisk.
The default IriusRisk roles can be extracted directly from the database with this command:
$ sudo -u postgres psql --dbname=iriusprod --command="SELECT name FROM role_group;"
name
--------------------------
ROLE_TEST_ONLY
ROLE_ADMIN
ROLE_PORTFOLIO_VIEW
ROLE_DEVELOPER
ROLE_FULL_ACCESS_USER
ROLE_MANAGE_USERS_BU
ROLE_RISK_MANAGER
ROLE_RULES_EDITOR
ROLE_TEMPLATE_EDITOR
ROLE_REQUIREMENTS_MANAGE
ROLE_TESTER
ROLE_QUESTIONNAIRE_ONLY
ROLE_LIBRARY_EDITOR
(13 rows)
- userGroupAttribute - the mapping for the attribute that holds returned group membership data
- defaultRole - is there’s no groups user is part of, what is the default role to assign him or her
- providers - map your Federation Metadata XML file downloaded from Keycloak to Keycloak provider
- idp.title - sentence you want to appear on the login page as the hyperlink to the Keycloak
- keyManager section with your generated certificate parameters
sp.xml
Run the application and wait for UI to be available (it may take up to 10min):
$ docker-compose up -d
The log will show some errors indicating the missing sp.xml file. This is something expected. At this point IriusRisk isn't fully configured yet and the UI will not be accessible.
Once IriusRisk finish started you will need to download IriusRisk SAML metadata file with the following command (change localhost to your own IriusRisk endpoint):
$ curl http://localhost/saml/metadata --output sp.xml
docker-compose.yml (final version)
After you will need to include the both files into your docker-compose.yml:
version: '3' services: nginx: ports: - "80:80" - "443:443" environment: - NG_SERVER_NAME=localhost links: - tomcat8 image: continuumsecurity/iriusrisk-prod:nginx-prod-ssl container_name: iriusrisk-nginx volumes: - "./cert.pem:/etc/nginx/ssl/star_iriusrisk_com.crt" - "./key.pem:/etc/nginx/ssl/star_iriusrisk_com.key" tomcat8: environment: - IRIUS_DB_URL=jdbc\:postgresql\://172.17.0.1\:5432/iriusprod?user\=iriusprod&password\=alongandcomplexpassword2523 - IRIUS_EDITION=saas - IRIUS_EXT_URL=http\://localhost - grails_env=production - CATALINA_OPTS="-Dsaml.config.path=/etc/irius/SAMLv2-config.groovy" image: continuumsecurity/iriusrisk-prod:tomcat8-3 container_name: iriusrisk-tomcat8 volumes: - "./SAMLv2-config.groovy:/etc/irius/SAMLv2-config.groovy" - "./idp.xml:/etc/irius/idp.xml" - "./iriusrisk-sp.jks:/etc/irius/iriusrisk-sp.jks" - "./sp.xml:/etc/irius/sp.xml"
Restart everything and your integration should be finished:
$ docker-compose down && docker-compose up -d
You can also check the logs and see that everything is running correctly:
$ docker logs -f iriusrisk-tomcat8
Before trying to login into IriusRisk with your Keycloak account for the first time it also is important to logout from Keycloak first.
Comments
0 comments
Article is closed for comments.