Introduction

IriusRisk is able to integrate with SAML v2 based Identity Providers to perform authentication and authorization. Theoretically, IriusRisk can integrate with any provider that uses SAMLv2 although official support is for Salesforce and Azure SSOs. The authentication is performed by challenging the user to authenticate against the Identity Provider. The authorization is then performed by retrieving the groups the user belongs to and mapping them onto IriusRisk permissions.

Mapping SAML Identity Provider server roles with IriusRisk roles

The available default roles in IriusRisk are listed below. (custom roles can be created an mapped).  

• ROLE_ADMIN
• ROLE_DEVELOPER
• ROLE_PORTFOLIO_VIEW
• ROLE_REQUIREMENTS_MANAGE
• ROLE_RISK_MANAGER
• ROLE_RULES_EDITOR
• ROLE_TEMPLATE_EDITOR
• ROLE_LIBRARY_EDITOR
• ROLE_TEST_ONLY
• ROLE_TESTER
• ROLE_FULL_ACCESS_USER
• ROLE_MANAGE_USERS_BU
• ROLE_QUESTIONNAIRE_ONLY

To map the SAML groups to the IriusRisk groups you have three options available:

1. Map the role names in your SAML IdP server with role names in IriusRisk using the setting "userGroupToRoleMapping" in your SAML config file. (recommended)
2. Create the groups mentioned above on the SAML Identity Provider server.
   
3. Change the names of the ROLES in IriusRisk to match those already created on the SAML Identity Provider server. For example, if you already have a user group DEVS on SAML IdP server and you want to map those users to the ROLE_DEVELOPER group in IriusRisk you would just have to change the name in IriusRisk from ROLE_DEVELOPER to DEVS and those users would be automatically assigned these role when they log into IriusRisk.
4. Create a complete new set of ROLES in IriusRisk that matches your current SAML IdP server configuration for groups and individually assign to them the required permissions. The ROLE names you set up into IriusRisk must be the same as those on your SAML IdP server. 

Option #2 requires SAML IdP server configuration, options #3 and #4 can be done by just configuring IriusRisk properly if the SAML IdP server has a reasonable authorization scheme regarding groups.

Mapping SAML Identity Provider server roles with IriusRisk Business Units

Business units are created first by the IriusRisk user here:

Much like mapping roles, you will need to define the group attribute for IriusRisk to look for using:

businessUnitsAttribute = 'department'

(department is a custom value sent from the IdP).

Then you will map unique group IDs to already created business units in IriusRisk based on their Unique ID (shown in the image above). The configuration will look like so:

                businessUnitsMapping = [
                    'Your_okta_group': 'testers',
                    'Your_okta_group': 'managers',
                    'Your_okta_group': 'developers'
                ]

You can also set a default business unit like this:

defaultBusinessUnit = 'testers'

You can also see this as another example in the full groovy config below.

Auto-creating users and auto-assign authorities

IriusRisk supports Just-In-Time (JIT) provisioning, so there is no need to previously create the users on IriusRisk - they can be mapped on-the-fly.

Before we begin configuring SAML integration you must clean up users from IriusRisk. You need to make sure you don’t have any users already created in IriusRisk with the same id or email that the users coming from SAML integration. So start IriusRisk with local login, enter the web UI go to Users & Roles and delete all the conflicting users. Note that you will not loose any projects, comments or audit log. The only thing that will be lost is user-project ownership.

SAML user attributes

All SAML users who want to login in the IriusRisk must have the next attributes set:

• firstName
• lastName
• email

If any of these attributes are not set the login will not succeed.

Configuration

To enable SAML integration, you need to specify a configuration file. This file is read from the path indicated by the property "saml.config.path". This property must be passed to the start up process (i.e. through the catalina.properties file on Tomcat).

#Example of passing the property through catalina.properties:
$ cat /usr/share/tomcat8/conf/catalina.properties
#[...]
saml.config.path=/etc/irius/SAMLv2-config.groovy
#[...]

This file should contain the following configuration sections, (see the comments on the file):

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://your-iriusrisk-endpoint'

                // SAML assertion attribute that holds returned group membership data 
                userGroupAttribute = 'memberOf'

                // Custom Values, mapping IDP groups (used as keys in the configuration map userGroupToRoleMapping) to Irius RoleGroup names (used as values in the configuration map userGroupToRoleMapping)
                userGroupToRoleMapping = [
                    'admin':'ROLE_ADMIN',
                    'dev':'ROLE_DEVELOPER',
                    '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'

                // SAML assertion attribute that holds returned business unit data
                // businessUnitsAttribute = 'department'

                // Custom Values, mapping group names with (used as keys in the configuration map businessUnitsMapping) to Irius business units refs (used as values in the configuration map businessUnitsMapping)
                // businessUnitsMapping = [
                //    'Your_okta_group': 'testers',
                //    'Your_okta_group': 'managers',
                //    'Your_okta_group': 'developers'
                // ]

                // If there is no information about business units in the SAML Response, IriusRisk will use this property to assign a default business unit to the User
                // defaultBusinessUnit = 'testers'

                // Custom entity id for the instance. If it doesn't exist it is set to iriusrisk-sp by default
                // This setting was included in version 3.0.0
                // entityId = "custom-entity-id"

                // force SHA256
                // 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 = 'youridpname'
                    // Configuration map providers, using the name of the provider as key and the file system path to the xml descriptor file from IDP
                    providers = [ youridpname :'/etc/irius/idp.xml']
                    idp {
                        title = 'Your SAML login caption'
                    }
                    sp {
                        file = '/etc/irius/sp.xml'
                        defaults = [
                            // alias: 'custom-entity-id'
                            alias: 'iriusrisk-sp',
                            signingKey: 'iriusrisk-sp',
                            encryptionKey: 'iriusrisk-sp',
                            tlsKey: 'iriusrisk-sp',
                        ]
                    }
                }
            }
        }
    }
}

 This file should contain a reference to other 3 important files:

• iriusrisk-sp.jks - The java keystore file that will contain the key pair.
• idp.xml - metadata downloaded and renamed from identity provider
• sp.xml - metadata that will be downloaded from IriusRisk

Note: youridpname should contain only letters. No spaces or special characters allowed.

iriusrisk-sp.jks

You will need the keys inside the java keystore on both ends.

idp.xml

This is a Federation Metadata File that needs to be downloaded from your Identity Provider.

sp.xml

This file can be downloaded directly running IriusRisk and entering the URL: https://your-iriusrisk-endpoint/saml/metadata

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'

After everything is set, restart IriusRisk instance and renew the Identity Provider session for your users.