Articles in this section

SAML use case: Microsoft Azure as Identity Provider

Vadym Andriyevskyy
  • Updated
Follow

Using Microsoft Azure Active Directory as Identity Provider

The 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, 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 a JKS store in the same command, for simplicity, use the same password for the JKS and the alias of the key.

$ keytool -genkey -alias "iriusrisk-sp" -validity 1825 -keyalg RSA -keystore iriusrisk-sp.jks

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 password.

Import CA signed certificates

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

 

Create an Iriusrisk enterprise application in Azure AD from the Azure application catalog

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:

    image-20200306-091731.png
    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.image-20200306-092137.png

  • Download the Federation Metadata XML file: image-20200306-092316.pngrename 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)

a) 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 as this is an example file:

version: '3'

services:

  nginx:
    ports:
      - "80:80"
      - "443:443"
    environment:
      - NG_SERVER_NAME=azure-saml.iriusrisk.com
    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\://azure-saml.iriusrisk.com
      - 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"

b) Create a “SAMLv2-config.groovy” file with this content, remember to change some parameters:

  • entityBaseUrl - public url of your instance

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

grails {
    plugin {
        springsecurity {
            saml {
                // Activate SAML integration with IriusRisk
                active = true

                // 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/name',
                    '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'
                ]
                
                // 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 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 group membership data
                userGroupAttribute = 'http://schemas.microsoft.com/ws/2008/06/identity/claims/groups'

                // 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: 'iriusrisk-sp',
                            signingKey: 'iriusrisk-sp',
                            encryptionKey: 'iriusrisk-sp',
                            tlsKey: 'iriusrisk-sp',
                        ]
                    }
                }

                keyManager {
                    storeFile = 'file:/etc/irius/iriusrisk-sp.jks'
                    storePass = 'iriusrisk-sp'
                    passwords = [ 'iriusrisk-sp': 'iriusrisk-sp' ]
                    defaultKey = 'iriusrisk-sp'
                }
            }
        }
    }
}

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.

c) Now we need to run the application and wait for UI to be available (it may take up to 10min):

$ docker-compose up -d

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

 

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=azure-saml.iriusrisk.com
    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\://azure-saml.iriusrisk.com
      - 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"
      - "./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 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

 

 

Related articles

Comments

0 comments

Article is closed for comments.

Powered by Zendesk