Security Assertion Markup Language (SAML) is a standard protocol which enables Single Sign-On (SSO).
It works by allowing the secure exchange of user authentication and authorization data between a service provider (SP) and a configured SAML Identity Provider (ldP).
Some key terminology that will help with this guide includes:
- Service Provider (SP) - Moogsoft AIOps
- Identity Provider (IdP) - The service/software which maintains the user directory and verifies the identity of your users
- Entity ID (Issuer) - A unique string ID that identifies the provider issuing the SAML request.
Moogsoft AIOps implements SAML 2.0 via the Open SAML v3 Open Library. SAML documentation available here: Open SAML v3.
To set up SAML 2.0 you will need to follow the steps below:
1. Configure IdP according to the IdP's documentation
2. Obtain and transfer IdP's metadata XML file to Moogsoft AIOps
3. Configure the Realm in security.conf as described here and follow the other configuration steps below
4. Restart the apache-tomcat service using the following command:
5. If successfully configured, AIOps will produce an SP metadata file, which if needed can be shared to the IdP.
Please note: AIOps cannot produce a SP metadata file until steps 1-4 have been completed
SAML 2.0 can be configured as a Realm in $MOOGSOFT_HOME/config/security.conf
Only one SAML 2.0 Realm can be configured and used concurrently
Below is an example SAML 2.0 Realm configuration:
When a SAML2 Realm is configured, Moogsoft AIOps enables a separate logout page to be displayed when the Moogsoft AIOps user's session is terminated, either by logging out of the application or when the session expires. The page that is displayed at logout is configured using web.conf configuration file:
When a SAML2 Realm is configured, Moogsoft AIOps's User Interface will no longer display the default Database driven login page. Instead, when a user tries to access AIOps they will be redirected to the IdP's login page, where upon successful authentication, the IdP will redirect the user back to AIOps page.
If a SAML originated user is authorized into Moogsoft AIOps for the first time, they will be given the configured Primary Group, Roles and Teams.
To disable SAML 2.0 SSO and re-enable the default Database driven login page, comment out any SAML2 realms configured in $MOOGSOFT_HOME/config/security.conf
Identity Provider Configuration
The Identity Provider (IdP) being configured to integrate with Moogsoft AIOps has to be configured to point the 'Single Sign-On' URL to:
This tells the IdP where to send the encrypted SAML 2.0 authorization assertion. This request will inform Moogsoft AIOps of the user being authorized and in turn Moogsoft AIOps will inform the user's browser that they have been given permission to access Moogsoft AIOps.
<moogsoft-ui-hostname> refers to the configuration typically specified in $MOOGSOFT_HOME/config/servlets.conf. If the URL configured on the IdP does not matching the webhost specified in servlets.conf then the URL redirect will not work.
The IdP will generally provide an XML metadata file for the Moogsoft AIOps Service Provider. Set the location of this file in the 'idpMetadataFile' configuration.
If the specified file does not exist or is not a valid XML file, apache-tomcat will log errors in catalina.out
Most Identity Providers will allow you to configure attributes that will be passed to the Service Provider when an entity is authorized.
Moogsoft AIOps provides an attribute mapping section in the SAML 2.0 Realm configuration, and here you can map attributes provided by the IdP with Moogsoft AIOps's required fields. Mappings are case sensitive.
In this example we are mapping the IdP's 'Email' to both Moogsoft's username and email fields, and fullname is mapped as a concatenation of 'FirstName' and 'LastName'. This mapping functionality is akin to LAM's mapping functionality, except for dots ( ' . ' ) being treated literally.
In Example 2, username has been mapped to an attribute named 'Username', likewise email is mapped to 'Email', fullname however takes attributes but also appends a static suffix, i.e.
If an attribute mapping is not specified or the IdP does not provide this attribute when a user tries to log in, then Moogsoft AIOps will fail to authorize the user, and an error can be seen in catalina.out
Service Provider Configuration
Existing User Mapping
Within the 'SAML2' Realm configuration, Moogsoft AIOps can be told which field value to use when trying to find an existing user in the Moogsoft Database to assign the newly SAML2.0 authorized user to. In other words if you already had users created via Moogsoft AIOps User Interface then these could be mapped to your IdP via the 'existingUserMappingField' configuration.
New User Creation
When a user is authorized via the IdP for the first time and cannot be mapped to an existing user entry, a new user entry will be created in Moogsoft AIOps. Within the SAML 2.0 Realm configuration it is possible to specify what primary group, roles and teams that user should be assigned to by default.
The Realm must be configured with a non-empty list of 'defaultRoles', these will be verified on apache-tomcat startup and so therefore must be created before configuring the Realm. Likewise for 'defaultGroup' it must be specified with a single valid value. It is possible to configure new users to not be assigned to any teams, simply specify an empty list for 'defaultTeams'.
Default roles, teams and groups only apply to users that were not present in the system and only when logging in via IdP for the first time. Once the user is created in Moogsoft AIOps their teams, roles and groups can be adjusted through system settings and these settings will be respected the next time user logs in
Authentication Window Lifetime
The time between the Identity Provider providing the SAML assertion and the time at which the Service Provider (Moogsoft AIOps) receives that assertion and considers it acceptable can be configured. By default a delay of up to an hour is accepted. This can be changed by specifying a value in seconds for the configuration 'maximumAuthenticationLifetime'. A longer lifetime is not recommended.
Entity Id Assertion
Also referred to as 'Audience Restriction'. The Service Provider can specify a unique Entity Id which needs to be configured on the IdP side too, and this will restrict the SAML assertions audience to just this application/service. If configured, the values must match for the SAML authorization to succeed in Moogsoft AIOps.
The implementation of SAML2 integration in Moogsoft AIOps supports the following bindings:
For more information you can check OpenSAML v3 documentation available here: Open SAML v3