Configure Single Sign-On with SAML

You can configure Moogsoft Enterprise 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 Enterprise. The integration redirects you from the standard Moogsoft Enterprise login page to the IdP's login page. You can log in to Moogsoft Enterprise if you provide the IdP with valid authentication details.

See SAML Strategies and Tips for strategies to help you decide how to configure the SAML integration.

Moogsoft Enterprise implements SAML 2.0 using the SAML v3 Open Library. See SAML 2.0 for information on supported bindings and Open SAML v3 for information on the library.

Before you begin

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

  • You have an active SAML IdP account with administrator privileges.

  • The webhost URL is the same as your Moogsoft Enterprise instance URL. For example:

    webhost: "https://example.com"

Configure your SAML IdP

Configure your IdP to integrate with Moogsoft Enterprise and enable SSO. Refer to your IdP's documentation for instructions.

Configuration differs for each IdP but common settings include:

  • SSO URL: The URL that sends a SAML login request to the IdP. For example:

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

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

    https://example.com/moogsvr/mooms

Generate the IdP metadata

After you configure your SAML 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 IdP metadata file

The .xml metadata file generated by the IdP provides Moogsoft Enterprise 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 file to the location $MOOGSOFT_HOME/etc/saml.

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

    chmod 644 my_idp_metadata.xml

Configure the SAML realm

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

To configure your SAML realm:

  1. Edit the file $MOOGSOFT_HOME/config/security.conf and uncomment the "my_saml_realm" section. Rename the realm to meet your requirements.

  2. Configure the locations of your metadata files:

    • idpMetadataFile: Location of the IdP's metadata file.

    • spMetadataFile: Location of the service provider's metadata file. When the metadata file is generated in step 10, it is saved in this location.

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

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

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

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

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

    • existingUserMappingField: Defines the field that Moogsoft Enterprise 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 Enterprise.

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

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

  6. Optionally configure additional IdP attribute mappings:

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

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

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

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

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

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

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

    • roleAttribute: Defines the IdP attribute containing role information.

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

  7. Optionally configure your keystore and private key passwords if you want to use encryption with SAML. You can have either an unencrypted keystore password or an encrypted keystore password, but you cannot use both.

    • keystorePassword: Your unencrypted keystore password.

    • encryptedKeystorePassword: Your encrypted keystore password.

    • privateKeyPassword: Your private key password.

    See Moog Encryptor for more information on encrypting passwords.

  8. Optionally configure the lifetime of each SAML assertion:

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

  9. Optionally configure the Service Provider Entity ID:

    • serviceProviderEntityId: Service Provider Entity ID assertion number.

  10. Restart the Apache Tomcat service:

    service apache-tomcat restart

    When Apache Tomcat restarts it generates the Service Provider metadata file. The file is saved to the location specified in the spMetadataFile property.

Additional SAML configuration

You can configure the following additional properties when setting up SAML for Moogsoft Enterprise. Restart Apache Tomcat after you make any of these changes.

Enable encrypted assertion

To enable encrypted assertion for SAML with Moogsoft Enterprise, log in to your SAML IdP and enable encrypted assertions. Refer to your IdP's documentation for information.

Once enabled, the IdP encrypts all SAML assertions made with Moogsoft Enterprise.

Set an assertion time limit

The assertion time limit is the period of time between the IdP providing the SAML assertion and Moogsoft Enterprise accepting it.

Moogsoft Enterprise accepts a delay of up to one hour by default. You can specify a different period of time in minutes using the maximumAuthenticationLifetime property in the security configuration file for your SAML realm. For example:

"maximumAuthenticationLifetime": 3600

Enable entity ID assertion

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

To do this, specify the serviceProviderEntityID property in $MOOGSOFT_HOME/config/security.conf. You must also configure this in your IdP. The values must match for successful SAML authorization. For example:

"serviceProviderEntityId": "MySystemName"

Map user attributes

When you create your SAML realm, you can configure the attributes your IdP passes to Moogsoft Enterprise at SAML authentication.

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

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

You may see errors indicating failure to configure an attribute mapping or 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. For example:

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

If you already have users in Moogsoft Enterprise, you can map the user attributes to the IdP using the existingUserMappingField property. For example:

"existingUserMappingField": "username",

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

You can define which primary group, roles and teams to assign to users using the following properties in the SAML realm configuration:

  • defaultRoles: Default roles to assign to users.

  • defaultTeams: Default teams to assign to users.

  • defaultGroup: Default group to assign to users.

  • teamAttribute: The IdP's attribute for team names.

  • teamMap: Map IdP team names to Moogsoft Enterprise teams.

  • roleAttribute: The IdP's attribute for roles.

  • roleMap: Map IdP role names to Moogsoft Enterprise roles.

For example:

"assignTeams": 
{
    "teamAttribute": "groups",
    "teamMap": 
    {
        "IdP Team": "Networks",
        "Another IdP Team": "Application Support"
    }
}
"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.

Create new teams

Enable the createNewTeams property to create new teams and assign newly created users to these teams as part of the SAML login process, instead of assigning new users to the default teams.

"createNewTeams": true

Note

Enable this property with caution. If a user logs in to Moogsoft Enterprise and createNewTeams is set to true, a new team is defined in Moogsoft Enterprise for every value found in the teamAttribute property in the user's profile. If you are using the "groups" attribute to determine team membership, this could result in the creation of hundreds of teams that are not referenced by Moogsoft Enterprise.

Moogsoft recommends that you enable createNewTeams with a custom profile attribute that you specifically use to determine Moogsoft Enterprise team membership and contains a very limited set of values.

Configure the SAML logout URL

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

To configure the logout URL:

  1. Edit the configuration file: $MOOGSOFT_HOME/ui/web.conf.

  2. Configure the logout property to meet your requirements and save the changes.

An example web configuration file is as follows:

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

Example SAML realm

An example SAML realm in $MOOGSOFT_HOME/config/security.conf is as follows:

"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": "MySystemName"
}

Send the SP metadata file

When you have configured the SAML realm, copy your SP metadata file and send it to the administrator of your IdP. For example:

$MOOGSOFT_HOME/etc/saml/my_idp_metadata.xml

Your IdP must import the metadata file. Note that all certificates are self-signed.

See Troubleshoot SAML for ideas to help you debug SAML connection and configuration problems.