Configure Single Sign-On with SAML

You can configure Moogsoft AIOps so users from an external directory can log in by Single Sign-On (SSO) using Security Assertion Markup Language (SAML).

When you enable the SAML integration, your SAML identity provider (IdP) can exchange authorization and authentication data securely with your service provider (SP), Moogsoft AIOps. The integration redirects you from Moogsoft AIOps' standard login page to the IdP's login page. You can log in to Moogsoft AIOps if you provide the IdP with valid authentication details.

Moogsoft AIOps implements SAML 2.0 using the SAML v3 Open Library. SAML 2.0 supports the following bindings:

  • HTTP-Artifact

  • HTTP-POST

  • HTTP-POST-SimpleSign

  • HTTP-Redirect

  • SOAP

See Open SAML v3 for more information.

Before You Begin

Before you start to set up SAML, ensure you have met the following requirements:

  • You have an active SAML Identity Provider account with administrator privileges.

  • Ensure the webhost URL in $MOOGSOFT_HOME/config/servlets.conf is the same as your Moogsoft AIOps instance URL:

    webhost: "https://example.moogsoftaiops.com"
Configure SAML Identity Provider

You can configure your IdP to integrate with Moogsoft AIOps and enable SSO. Refer to your IdP's documentation for instructions.

Configuration differs for each IdP but common settings include:

  • SSO URL: The Moogsoft AIOps URL that sends a SAML login request to the IdP:

    https://example.moogsoftaiops.com/moogsvr/mooms?request=samlRequest
  • Assertion Consumer Service URL: The Moogsoft AIOps URL that receives the IdP response to each SAML assertion:

    https://example.moogsoftaiops.com/moogsvr/mooms?request=samlResponse
  • Entity ID: A unique identifier for the SP SAML entity:

    https://example.moogsoftaiops.com/moogsvr/mooms

After you complete the IdP configuration, it generates an IdP metadata file in .xml format. Some IdPs also allow you to generate an X509 self-signed certificate. Save the certificate and add it to your SP metadata file if you want your IdP to encrypt SAML assertions.

Copy the Identity Provider Metadata File

You create the IdP metadata file as part of the IdP configuration. This .xml file provides Moogsoft AIOps with a security certificate, endpoints and other processing requirements.

To add this file to your SAML configuration:

  1. Save the IdP metadata file to your local machine.

  2. Copy the metadata file to $MOOGSOFT_HOME/etc/saml.

  3. Grant the Apache Tomcat user read permissions to the metadata file. For example:

    chmod 644 my_idp_metadata.xml
Create the Service Provider Metadata File

You must create an SP metadata file and send it to the IdP you want to integrate with Moogsoft AIOps.

Some IdPs offer an SP metadata generator. If your IdP does not generate the SP metadata file, you can create one manually. See Build a Service Provider Metadata File for information.

After you have generated your SP metadata file:

  1. Copy the file to $MOOGSOFT_HOME/etc/saml.

  2. Grant the Apache Tomcat user read permissions to the metadata file. For example:

    chmod 644 my_sp_metadata.xml
Configure the SAML Realm

You enable SAML authentication in Moogsoft AIOps by creating and configuring a SAML realm. You can only configure and use one SAML Realm at a time. See Security Configuration Reference for full descriptions of the available properties.

To configure your SAML realm:

  1. Uncomment the "my_saml_realm" section in the $MOOGSOFT_HOME/config/security.conf configuration file. Rename the realm to meet your requirements.

  2. Configure the locations of your metadata files:

    • idpMetadataFile: Location of the identity provider's metadata file.

    • spMetadataFile: Location of the service provider's metadata file.

  3. Configure the roles, teams and primary group mappings for new users that log in to Moogsoft AIOps using SAML. These are all required:

    • defaultRoles: Default roles that Moogsoft AIOps assigns to new users at first login.

    • defaultTeams: Default teams that Moogsoft AIOps assigns to new users at first login.

    • defaultGroup: Default primary group that Moogsoft AIOps assigns to new users at first login.

  4. Configure the mappings for existing users that log in to Moogsoft AIOps using SAML. You can choose either username or email:

    • existingUserMappingField: Defines the field that Moogsoft AIOps uses to map existing users to your IdP users.

  5. Configure the mapping of the IdP's provided attributes. These are all required:

    • username: Defines the IdP user attribute that maps to username in Moogsoft AIOps.

    • email: Defines the IdP user attribute that maps to email in Moogsoft AIOps.

    • fullname: Defines the IdP user attribute that maps to full name in Moogsoft AIOps.

  6. Optionally configure additional IdP attribute mappings:

    • contactNumber: Defines the IdP attribute that maps to contact number in Moogsoft AIOps.

    • department: Defines the IdP attribute that maps to department in Moogsoft AIOps.

    • primaryGroup: Defines the IdP attribute that maps to primary group in Moogsoft AIOps.

    • timezone: Defines the IdP attribute that maps to timezone in Moogsoft AIOps.

    • teamAttribute: Defines the IdP attribute that maps to teams in Moogsoft AIOps.

    • teamMap: Defines the IdP attribute or custom attribute that maps to team names in MMoogsoft AIOps.

    • createNewTeams: Creates a team or teams if they did not exist in Moogsoft AIOps.

    • roleAttribute: Defines the IdP attribute containing role information.

    • roleMap: Defines the IdP attribute that maps to Moogsoft AIOps roles.

  7. Optionally configure your keystore and private key passwords if you want to use encryption with SAML.

    • keystorePassword: Your keystore password.

    • privateKeyPassword: Your private key password.

    See Security Configuration Reference for more information on these properties.

  8. Optionally configure the lifetime of each SAML assertion:

    • maximumAuthenticationLifeTime: Maximum time in seconds for Moogsoft AIOps to receive an IdP's SAML assertion before it becomes invalid.

    See Security Configuration Reference for more information.

  9. Optionally configure the Service Provider Entity Id:

    • serviceProviderEntityId: Service Provider Entity ID assertion number.

    See Security Configuration Reference for more information.

  10. Restart the Apache Tomcat service:

    service apache-tomcat restart
Enable Encrypted Assertion

To enable encrypted assertion for SAML with Moogsoft AIOps:

  1. Copy the location of your KeyStore file. This defaults to $MOOGSOFT_HOME/etc/saml/<name of realm>_keystore. Moogsoft AIOps generates this file when you create the realm.

  2. Log in to your SAML IdP and enable encrypted assertions. Refer to your IdP's documentation for information.

  3. Provide your KeyStore password and import your KeyStore file if required to do so. You can use either your encrypted or unencrypted Keystore password.

Once enabled, the Idp encrypts all SAML assertions made with Moogsoft AIOps.

Set an Assertion Time Limit

You can set the assertion time limit for Moogsoft AIOps. The assertion time limit is the duration between the IdP providing the SAML assertion and when Moogsoft AIOps accepts it.

Moogsoft AIOps accepts a delay of up to an hour by default. You can specify a different time to meet your requirements.

"maximumAuthenticationLifetime": 3600
Enable Entity ID Assertion

You can enable enable entity ID assertion, also known as audience restriction, to restrict SAML assertions to Moogsoft AIOps.

You configure the unique SP entity ID in $MOOGSOFT_HOME/config/security.conf. You must also configure this in your IdP. The values must match for successful SAML authorization:

"serviceProviderEntityId": "MoogsoftAIOps"
Map User Attributes

When you create your realm, you can configure the attributes your Identity Provider passes to Moogsoft AIOps at SAML authentication.

By default, the IdP email attribute maps to both the Moogsoft AIOps username and email. The Moogsoft AIOps full name maps to First Name and Last Name from the IdP:

"username"   : "$Email",
"email"      : "$Email",
"fullname"   : "$FirstName.$LastName"

You may see errors indicating failure to configure an attribute mapping or indicating the IdP's failure to provide a configured attribute if something goes wrong at login.

You can map other IdP user attributes such contact number, department, primary group and time zone:

"contactNumber"  : "phone",
"department"     : "department",
"primaryGroup"   : "primaryGroup",
"timezone"       : "timezone",

If you already have users in Moogsoft AIOps you can map the user attributes to the IdP using the existingUserMappingField:

"existingUserMappingField": "username",

When a user logs in via the IdP for the first time but does not map with an existing user entry, Moogsoft AIOps creates a new user.

You can define which primary group, roles and teams to assign users to using thedefaultRoles,defaultTeamsanddefaultGroupproperties in the SAML realm configuration.

You can map the IdP's attribute for team names using teamAttribute. You can configure which IdP attribute maps to Moogsoft AIOps team names using teamMap:

"assignTeams": {
    "teamAttribute": "groups",
    "teamMap": {
        "IdP Team": "Moogsoft AIOps Team",
        "Another IdP Team": "Another AIOps team"
    }
}

To create a team that does not exist already, enable thecreateNewTeamsproperty:

"createNewTeams": true

If you enable createNewTeams, Moogsoft AIOps assigns users to the teams it creates as part of the SAML login instead of the default SAML teams.

You can map the IdP attribute for roles using roleAttribute. You can map the IdP roles to Moogsoft AIOps roles using roleMap:

"assignRoles": {
    "roleAttribute": "groups",
        "roleMap": {
                "IdP Standard User" : "Operator",
                "IdP Manager User" : "Manager"
        }
}

Note

You must map both roles and teams through IdP to prevent users being assigned to the default role and team.

Configure SAML Logout URL

After you enable SAML, you can configure a different logout page to display when a Moogsoft AIOps user ends their session.

To configure a different logout page:

  1. Edit the $MOOGSOFT_HOME/ui/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"
        }
    }
  2. Change the sub URL for "logout" to meet your requirements.

  3. Save the changes.

After you have completed the change, Moogsoft AIOps displays the new logout path when a session expires or if you log out.

Example SAML Realm

You can use the default SAML realm in $MOOGSOFT_HOME/config/security.conf for reference:

"my_saml_realm": {
    "realmType": "SAML2",
    "idpMetadataFile": "/usr/share/moogsoft/etc/saml/my_idp_metadata.xml",
    "spMetadataFile": "/usr/share/moogsoft/etc/saml/my_sp_metadata.xml",
    "defaultRoles": [ "Operator" ],
    "defaultTeams": [ "Cloud DevOps" ],
    "defaultGroup": "End-User",
    "existingUserMappingField": "username",
    "username": "$Email",
    "email": "$Email",
    "fullname": "$FirstName $LastName"
    "contactNumber": "phoneNumber",
    "department": "dept",
    "primaryGroup": "group",
    "timezone": "timezone",
    "assignTeams": {
        "teamAttribute": "groups",
        "createNewTeams": true,
        "teamMap": {
            "Cloud Team": "Cloud DevOps",
            "Database Team": "Database DevOps"
        }
    },
    "assignRoles" : {
        "roleAttribute": "groups",
        "roleMap" : {
            "Standard User": "Operator",
            "Manager User": "Manager"
        }
    },
    "keystorePassword": "my_realm_secret",
    "privateKeyPassword": "my_realm_secret",
    "maximumAuthenticationLifetime": 60,
    "serviceProviderEntityId": "MoogsoftAIOps"
}