Using Microsoft Azure Active Directory as Identity Provider

Azure AD can be used with local users on Azure or synchronized with an on-premises AD, but the configuration is the same. The way the customer feeds the users to the Azure AD is not relevant for this configuration to work.

For this setup to work, it is needed that the IriusRisk instance has a public endpoint. In this tutorial we will use a SaaS instance on AWS with a DNS record called azure-saml.iriusrisk.com.

Set certificates

This task needs to be done by the owner of the instance where IriusRisk is running. If it is a SaaS instance, IriusRisk 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-tomcat sh

Execute key generation procedure. The default password for the keystore is "changeit". There is no need to fill the information about the name/country etc, but providing a password is mandatory. 

$ 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 10
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-tomcat:/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 application in Azure AD

Create IriusRisk application in Azure AD

Log into https://portal.azure.com, login and enter to the Azure AD section, then in the left menu, go to Enterprise applications, then above, click “New application”. In the gallery search box, type: “iriusrisk”, click it and select “Add”. Wait until Azure finishes the task.

Allow users/groups to connect to the application

In the trail above, click on “Enterprise applications - All applications”

Click on the Iriusrisk application you just created, then click on “1. Assign users and groups”, click above on “Add User”.

NOTE: You will need to add the groups of their Azure AD into this section, but using groups requires a premium Azure account. You can use individual users here for testing purposes only, but not on production.

Click and select the users/groups you want to allow to connect to the application using the search box.

A customer would use an Azure group called “iriusrisk” for example.

For testing purposes you can add yourself.

Click “Assign” when done.

Configure SAML

• Go to the “Single sign-on” section and click on “SAML”. Edit “Basic SAML configuration” with the correct values. It is mandatory to set Identifier (Entity ID) to iriusrisk-sp, this is a hard-coded value. The rest should depend on customer’s IriusRisk URL.
  This is an example of a working configuration:

  
  Click “Save” above!!! 

• Leave the “User Attributes & Claims” section as it is, we will hardcode that information in our configuration later. There is no need to configure anything here. But make sure that every attribute mentioned here exists and it’s filled for every user. Sometimes people forget to fill the email address attribute for the users, which is mandatory by IriusRisk.
  
  In case you also want to manage IriusRisk roles with Azure groups you will also need to add a claim. Edit “User Attributes & Claims” and add a new group claim for all groups:
  

• Download the Federation Metadata XML file:
  
  rename it to “idp.xml” and place it in your docker folder along with the rest of your files.

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 Azure)

• 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 this 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.7'

networks:
 iriusrisk-frontend:

services:

nginx:
 ports:
   - "80:80"
   - "443:443"
 environment:
   - NG_SERVER_NAME=matthoffman.iriusrisk.com
 image: continuumsecurity/iriusrisk-prod:nginx
 container_name: iriusrisk-nginx
 networks:
  - iriusrisk-frontend
 mem_reservation: 50M
 mem_limit: 200M
 cpu_shares: 128
 restart: unless-stopped
 volumes:
   - "./cert.pem:/etc/nginx/ssl/star_iriusrisk_com.crt:ro"
   - "./key.pem:/etc/nginx/ssl/star_iriusrisk_com.key:ro"

tomcat:
 environment:
   - IRIUS_DB_URL=jdbc\:postgresql\://172.17.0.1\:5432/iriusprod?user\=iriusprod&password\=alongandcomplexpassword2523
   - IRIUS_EDITION=saas
   - IRIUS_EXT_URL=http\://matthoffman.iriusrisk.com
   - grails_env=production
   - CATALINA_OPTS="-Dsaml.config.path=/etc/irius/SAMLv2-config.groovy"
 image: continuumsecurity/iriusrisk-prod:tomcat9-3
 container_name: iriusrisk-tomcat
 networks:
   - iriusrisk-frontend
 mem_reservation: 2G
 cpu_shares: 1024
 volumes:
   - "./logs:/usr/local/tomcat/logs"
   - "./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 = 'https://azure-saml.iriusrisk.com'

                // Custom entity id for the instance. If it doesn't exist it is set to iriusrisk-sp by default
                // entityId = "iriusrisk-sp"

                // 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' : 'http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress',
                    'firstName': 'http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname',
                    'lastName' : 'http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname',
                    'email'    : 'http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress'
                ]
                
                // SAML assertion attribute that holds returned group membership data
                userGroupAttribute = 'http://schemas.microsoft.com/ws/2008/06/identity/claims/groups'

                // Custom Values, mapping Azure Groups GUIDs (used as keys in the configuration map userGroupToRoleMapping) to Irius RoleGroup names (used as values in the configuration map userGroupToRoleMapping)
                userGroupToRoleMapping = [
                    'h06aNZyl-Bzjc-bR6X-qlew-CZvMHvbsG0sq':'ROLE_TEST_ONLY',
                    'IVfp1C0J-ujQT-y6Ky-2WPE-o4h5mdiEiPZR':'ROLE_ADMIN',
                    'a06wlKy2-3NEj-fsEv-JrPc-i6rl4YuRX2YP':'ROLE_PORTFOLIO_VIEW',
                    'd6FL45u8-nFzW-RHl0-64Vv-NeZbLDKdrr5F':'ROLE_DEVELOPER',
                    'vjvIVt2Y-1m9w-YAHA-kfNf-TvrvQjfDV5SI':'ROLE_FULL_ACCESS_USER',
                    'cVKF1BWo-xOnx-kqyb-jS0N-JCeioBU9QfzY':'ROLE_MANAGE_USERS_BU',
                    'lGqiGVlK-wftf-sbNJ-uft0-bpGya43Tu1Lu':'ROLE_RISK_MANAGER',
                    'xQ2fb3qR-IApK-ByIz-gTFr-bueb8ieVSwn5':'ROLE_RULES_EDITOR',
                    'yoHoV6OL-qfTz-6nAa-WOI2-JKl0IyqnIJDm':'ROLE_TEMPLATE_EDITOR',
                    'Spg72Xwt-O3Oq-au0x-SAFk-U86mCDbfYJ3K':'ROLE_REQUIREMENTS_MANAGE',
                    '8aHPFQz7-ZK1Q-jEgq-voDj-J0nI42zWVza6':'ROLE_TESTER',
                    '3ePo7Vvz-6Aeu-4nCo-3eTx-02tYgRPsFy5g':'ROLE_QUESTIONNAIRE_ONLY',
                    't26dkV2b-Tds6-YcW9-7tdO-gGCc23Dm6K6v':'ROLE_LIBRARY_EDITOR'
                ]

                // 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_DEVELOPER'

                // SAML assertion attribute that holds returned business unit data
                // businessUnitsAttribute = 'http://schemas.microsoft.com/ws/2008/06/identity/claims/groups'

                // businessUnitsMapping = [
                // '77b7b701-7388-3207-ga3e-1891abec1951':'testers',
                // '823c072c-2e41-4ddf-ea28-db00a971e888':'managers',
                // '1fae5bb2-3c73-43d1-97fc-a2dba22bbc07':'developers'
                // ]

                // Custom entity id for the instance if it doesn't exist it is set to iriusrisk-sp by default
                // entityId = "custom-entity-id"

                metadata {
                    // Relative URL in IriusRisk to download sp.xml metadata
                    url = '/saml/metadata'
                    // Provider to be used from the configuration map providers
                    defaultIdp = 'azure'
                    // Configuration map providers, using the name of the provider as key and the file system path to the xml descriptor file from Azure
                    providers = [ azure :'/etc/irius/idp.xml']
                    idp {
                        title = 'Azure-SAML login caption'
                    }
                    sp {
                        file = '/etc/irius/sp.xml'
                        defaults = [
                            // alias should correspond to your entity id
                            alias: 'iriusrisk-sp',
                            signingKey: 'iriusrisk-sp',
                            encryptionKey: 'iriusrisk-sp',
                            tlsKey: 'iriusrisk-sp',
                        ]
                    }
                }

                keyManager {
                    storeFile = 'file:/etc/irius/iriusrisk-sp.jks'
                    storePass = 'changeit'
                    passwords = [ 'iriusrisk-sp': 'changeit' ]
                    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 Azure (Note: if setting custom entity this must be reflected in the "alias:" definition under the sp configuration)

• userGroupToRoleMapping - map you Azure group IDs to IriusRisk roles
  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 Azure to Azure provider
• idp.title - sentence you want to appear on the login page as the hyperlink to the Azure AD
• keyManager section with your generated certificate parameters

Note that due to particular Azure SAML Response message format this file has 2 big differences with the standard one. First, userGoupToRoleMapping attribute should map Azure AD group IDs to IriusRisk roles. Second, userGroupAttibute should be set to http://schemas.microsoft.com/ws/2008/06/identity/claims/groups instead of standard memberOf.

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 azure-saml.iriusrisk.com to your own IriusRisk endpoint):

$ curl https://azure-saml.iriusrisk.com/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.7'

networks:
 iriusrisk-frontend:

services:

 nginx:
  ports:
    - "80:80"
    - "443:443"
  environment:
    - NG_SERVER_NAME=matthoffman.iriusrisk.com
  image: continuumsecurity/iriusrisk-prod:nginx
  container_name: iriusrisk-nginx
  networks:
    - iriusrisk-frontend
  mem_reservation: 50M
  mem_limit: 200M
  cpu_shares: 128
  restart: unless-stopped
  volumes:
    - "./cert.pem:/etc/nginx/ssl/star_iriusrisk_com.crt:ro"
    - "./key.pem:/etc/nginx/ssl/star_iriusrisk_com.key:ro"

tomcat:
 environment:
   - IRIUS_DB_URL=jdbc\:postgresql\://172.17.0.1\:5432/iriusprod?user\=iriusprod&password\=alongandcomplexpassword2523
   - IRIUS_EDITION=saas
   - IRIUS_EXT_URL=http\://matthoffman.iriusrisk.com
   - grails_env=production
   - CATALINA_OPTS="-Dsaml.config.path=/etc/irius/SAMLv2-config.groovy"
 image: continuumsecurity/iriusrisk-prod:tomcat9-3
 container_name: iriusrisk-tomcat
 networks:
   - iriusrisk-frontend
 mem_reservation: 2G
 cpu_shares: 1024
 volumes:
   - "./logs:/usr/local/tomcat/logs"
   - "./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"

Load Balancer Config

If your application is behind a load balancer you may need to add the following to your goovy file:

contextProvider{
    providerClass = 'SAMLContextProviderLB'
    scheme = 'https'
    serverName = 'your external hostname'
    serverPort = 443
    includeServerPortInRequestURL = false
    contextPath ='/MicroStrategyLibrary'
}

Errors relating to this issue should resemble this:

ERROR org.opensaml.common.binding.decoding.BaseSAMLMessageDecoder - SAML message intended destination endpoint 'https://host.com/saml/SSO/alias/iriusrisk-sp' did not match the recipient endpoint 'http://host.com/saml/SSO/alias/iriusrisk-sp'

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-tomcat

Before trying to login into IriusRisk with your Azure account for the first time it also is important to logout from Azure first. In order to do so you can follow this link:
https://login.microsoftonline.com/common/oauth2/logout?post_logout_redirect_uri=https%3A%2F%2Fgraphexplorer.azurewebsites.net%2F