1. Open the Keycloak Admin Console

2. Hover the mouse over the dropdown in the top-left corner where it says Master, then click on Add realm

3. Fill in the form with the following values:

   • Name: IriusRisk-realm

4. 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
• email

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.