Page tree
Skip to end of metadata
Go to start of metadata

Security Assertion Markup Language (SAML) is a standard protocol which enables Single Sign-On (SSO). SAML allows a service provider (SP)  and a configured SAML Identity Provider (ldP) to exchange user authentication and authorization data securely.

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.

Setup Overview

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:

service apache-tomcat restart

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

File-based Configuration

Realm Configuration

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:

"my_saml_realm" : {

   # Do not change realmType
   "realmType": "SAML2",

   #
   # Provide the location of the IdP's metadata file, it has to be an xml file.
   # This file provides information on how to connect to the IdP.
   #
   "idpMetadataFile": "/usr/share/moogsoft/etc/saml/my_idp_metadata.xml",

   #
   # Provide the location of the SP's metadata file, this is where Moogsoft
   # AIOps will write the SP metadata information to.
   # This location needs to be accessible and editable to the tomcat user.
   #
   "spMetadataFile": "/usr/share/moogsoft/etc/saml/my_sp_metadata.xml",

   #
   # Specify the default roles, teams and group for any new users that
   # are created via this realm's login process.
   # Roles and group must be specified; teams can be an empty list to
   # indicate that no teams are to be assigned to that new user.
   #
   "defaultRoles": [ "Operator" ],
   "defaultTeams": [ "Cloud DevOps" ],
   "defaultGroup": "End-User",

   #
   # Specify which field to use to attempt to map an existing AIOps
   # user to a newly logged in user as provided by IdP.
   # i.e. pick from (case sensitive):
   # - username
   # - email
   #
   # By default the username field will be used.
   # NOTE: if there are multiple users mapped to the same field
   # value, then an error will be shown and no user will be created. 
   #
   "existingUserMappingField": "username",

   #
   # Attribute Mapping Section
   # Here you can define the IdP's provided attributes and how they
   # map to Moogsoft's user attributes.
   # Please note: no spaces are allowed in attribute names
   #
   "username": "$Email",
   "email": "$Email",
   "fullname": "$FirstName $LastName"

   #
   # Optional config
   #
   
   #
   # The time in seconds that a valid SAML assertion has from being issued
   # by the IdP to being received by Moogsoft AIOps before that assertion
   # is considered invalid. Default is 1 hour.
   # ,"maximumAuthenticationLifetime": 3600

   #
   # Service Provider Entity Id (Audience Restriction).
   # Some IdPs require SP Entity ID assertion, this can be configured here.
   ,"serviceProviderEntityId": "MoogsoftAIOps"
}

URL 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:

"authentication": {
    "pages": {
        "login": "/login/",
        "logout": "/logout/",
        "failedLogin": "/login/?error=true",
        "sessionTimeout": "/logout/?error=session",
        "dbFailure": "/login/?error=dbfailure"
    },
    "paramNames": {
        "userId": "userid",
        "password": "password"
    }
},

Workflow

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:

https://<moogsoft-ui-hostname>/moogsvr/mooms?request=samlResponse

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.

   #
   # Provide the location of the IdP's metadata file, it has to be an xml file.
   # This file provides information on how to connect to the IdP.
   #
   "idpMetadataFile": "/usr/share/moogsoft/etc/saml/my_idp_metadata.xml",

If the specified file does not exist or is not a valid XML file, apache-tomcat will log errors in catalina.out

Attributes

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.

Example 1:

   #
   # Attribute Mapping Section
   # Here you can define the IdP's provided attributes and how they
   # map to Moogsoft's user attributes.
   # Please note: no spaces are allowed in attribute names
   #
   "username": "$Email",
   "email": "$Email",
   "fullname": "$FirstName $LastName"


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.

Example 2:

   "username": "$Username",
   "email": "$Email",
   "fullname": "$FirstName.$LastName (SAML)"


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. 

"fullname" = "John.Doe (SAML)"

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.

   #
   # Specify the default roles, teams and group for any new users that
   # are created via this realm's login process.
   # Roles and group must be specified; teams can be an empty list to
   # indicate that no teams are to be assigned to that new user.
   #
   "defaultRoles": [ "Operator" ],
   "defaultTeams": [ "Cloud DevOps" ],
   "defaultGroup": "End-User",

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.

   #
   # The time in seconds that a valid SAML assertion has from being issued
   # by the IdP to being received by Moogsoft AIOps before that assertion
   # is considered invalid. Default is 1 hour.
   ,"maximumAuthenticationLifetime": 3600

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.

   #
   # Service Provider Entity Id.
   # Some IdPs require SP Entity ID assertion, this can be configured here.
   ,"serviceProviderEntityId": "MoogsoftAIOps"

Supported bindings

The implementation of SAML2 integration in Moogsoft AIOps supports the following bindings:

  • HTTP-Artifact
  • HTTP-POST
  • HTTP-POST-SimpleSign
  • HTTP-Redirect
  • SOAP

For more information you can check OpenSAML v3 documentation available here: Open SAML v3

  • No labels