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:
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 web host URL in
$MOOGSOFT_HOME/config/servlets.confis the same as your Moogsoft AIOps instance URL:
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:
Assertion Consumer Service URL: The Moogsoft AIOps URL that receives the IdP response to each SAML assertion:
Entity ID: A unique identifier for the SP SAML entity:
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:
- Save the IdP metadata file to your local machine.
Copy the metadata file to
Grant the Apache Tomcat user read permissions to the metadata file. For example:
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:
Copy the file to
Grant the Apache Tomcat user read permissions to the metadata file. For example:
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:
"my_saml_realm" section in the
$MOOGSOFT_HOME/config/security.confconfiguration file. Rename the realm to meet your requirements.
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.
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.
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.
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.
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 Moogsoft 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.
Optionally configure your keystore and private key passwords if you want to use encryption with SAML. See Optional SAML Security Features:
keystorePassword: Your keystore password.
privateKeyPassword: Your private key password.
Optionally configure the lifetime of each SAML assertion. See Optional SAML Security Features:
maximumAuthenticationLifeTime: Maximum time in seconds for Moogsoft AIOps to receive an IdP's SAML assertion before it becomes invalid.
Optionally configure the Service Provider Entity Id. See Optional SAML Security Features:
serviceProviderEntityId: Service Provider Entity ID assertion number.
Restart the Apache Tomcat service:
Enable Encrypted Assertion
To enable encrypted assertion for SAML with Moogsoft AIOps:
- 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.
- Log in to your SAML IdP and enable encrypted assertions. Refer to your IdP's documentation for information.
- Provide your KeyStore password and import your KeyStore file if required to do so.
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.
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:
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:
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:
If you already have users in Moogsoft AIOps you can map the user attributes to the IdP using the
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 the
defaultGroup properties 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
To create a team that does not exist already, enable the
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
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:
- Change the sub URL for "logout" to meet your requirements.
- 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: