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:
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)
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
Comments
0 comments
Article is closed for comments.