LDAP and SAML User Authentication

Owned by Ray O'Meara (Unlicensed)
Last updated: Apr 07, 2023 by Chris Potts
10 min read

 

Both SAML and LDAP (Identity Providers) can be used to authenticate users to the Alert application. Before users can authenticate using SAML or LDAP, you must configure both the external system Identity provider (IdP) and the Alert application.
The following list describes the contents of this page.

LDAP or SAML user authentication workflow

The following is a high-level overview of the workflow for LDAP and SAML user authentication.

  1. The LDAP or SAML provider has a list of authenticated/authorized users.

  2. You configure Alert to authenticate by using LDAP or SAML.

  3. You configure Alert with the Identity Provider (IDP) details.

  4. The user logs in to Alert using LDAP or SAML authentication.
    By default, LDAP and SAML users log in with the most restrictive permissions (ALERT_USER).

  5. The external system (IDP) validates or fails to validate the user.

  6. The user is created in Alert upon successful authentication.

  7. An Alert system administrator can assign roles after a successful login by the user.

When users authenticate through LDAP or SAML to log into Alert for the first time, they are added to the Alert database. The Alert administrator can assign roles for the users on the User Management page. As of Alert 6.3.0, LDAP and SAML user's that login into Alert now have the ALERT_USER role assigned to them on first login, by default.

How LDAP and SAML work in Alert

LDAP
Users log into Alert where they are added to the Alert system with the most restricted access to Alert.
After the user has logged in initially to Alert, a System Administrator can assign the user roles. The next time the user logs in they will have their access privileges based on the roles assigned to them.

SAML
SAML works the same as LDAP for non-admin users of Alert. They must log in initially and an administrator grants them privileges afterwards.

The difference with SAML is in the administrative user.
Since the SAML login redirects the user to another site to login an Alert administrative user must have the Attribute containing their ALERT_ADMIN role assigned. This will add them to Alert as a user with administrative access when they log in to Alert that first time, which enables them to assign roles to other users.

Authentication interface changes

  • In Alert versions 5.2.0 and later, the authentication functionality was moved from the Settings page to the Authentication page.

  • On the Authentication page in Alert versions 5.2.0 and later, you can expand and collapse the LDAP, SAML, and User Management (removed in Alert 6.0.0) configuration settings.
    Click + to expand or - to collapse the LDAP Configuration, SAML Configuration.

LDAP configuration in Alert

Alert can authenticate users through LDAP.

To set up your LDAP environment in Alert:  

  1. Navigate to Authentication > LDAP Configuration.

  2. To display the LDAP fields, click + to the left of LDAP Configuration.

Complete the following fields.

  • LDAP Enabled: Select the checkbox to enable LDAP authentication.

  • LDAP Server: Enter your LDAP server IP address.

  • LDAP Manager DN: Enter the distinguished name of the LDAP manager.

  • LDAP Manager Password: Enter the password of the LDAP manager.

  • LDAP Authentication Type: Click the drop-down selector and choose the type of authentication required to connect to the LDAP server.

    • None

    • Simple

    • Digest-MD5

  • LDAP Referral: Select the type of authentication required to connect to the LDAP server.

    • Ignore

    • Follow

    • Throw

  • LDAP User Search Base: Enter the area in the LDAP directory in which user searches are done.

  • LDAP User Search Filter: Enter the filter used to search for user membership.

  • LDAP User DN Patterns: Enter the pattern used to supply a DN for the user. The pattern must be the name relative to the root DN.

  • LDAP User Attributes: Enter the user attributes to retrieve for users.

  • LDAP Group Search Base: Enter the part of the LDAP directory in which group searches are done.

  • LDAP Group Search Filter: Enter the filter used to search for group membership.

  • LDAP Group Role Attribute: Enter the ID of the attribute containing the role name for a group.

After completing your LDAP configuration settings, click Save.

To test your LDAP configuration when your LDAP configuration is enabled.

  1. Click Test Configuration > + LDAP Configuration and enter the user name and password to test LDAP authentication.

  2. Click Send Test Message to test the authentication.

SAML configuration in Alert

Alert supports Security Assertion Markup Language (SAML) authentication. Only one SAML application can be connected to Alert at any time.

For Alert to work properly, roles must be assigned to SAML attributes. Each identity provider is different regarding the assignment of SAML attributes. However, Alert requires the SAML attribute AlertRoles. The AlertRoles must be a list of roles that Alert recognizes. ALERT_ADMIN is currently the only role that should be on the list.

To use the standard Alert login functionality (i.e. login as a user stored in the Alert database rather than an external system) when SAML is enabled, append the query parameter ?ignoreSAML=true to the Alert URL in the address bar.

 WARNING: Always be sure to secure the passwords of users created in Alert including the default Alert users (sysadmin, jobmanager, alertuser).

The Authentication tab under SAML Configuration enables filling in some of the form fields based on the SAML configuration from the chosen Black Duck server (if a SAML configuration exists). 

Synopsys recommends that only Alert administrators have the attribute for the ALERT_ADMIN role set. All other users should have their roles managed in the Alert user interface.

If SAML authentication is enabled from the Authentication page, it takes precedence as the authentication provider. Therefore, you are not able to log into Alert as the default sysadmin administrative user. If you have configured Alert in error, use the ALERT_SAML_DISABLED=true environment variable override to disable SAML authentication when restarting the Alert container and then log in as the default administrator.

To configure SAML authentication, complete the following fields.

  1. SAML Enabled: Select the checkbox to enable SAML. If true, Alert attempts to authenticate using the SAML configuration.

  2. Force Auth: Select the checkbox to enable force auth. If true, the forceAuth flag is set to true in the SAML request to the identity provider (IDP). Check with your identity provider to verify support for force auth.

  3. Identity Provider Metadata URL: The metadata from the external identity provider.

  4. Identity Provider Metadata File: In Alert versions 5.1.0 and higher, you can upload a metadata XML file for SAML in the settings configuration. You can configure a URL if the IDP provides a URL or you can download a metadata XML file and upload it to the server.

    1. Click Browse to select your XML file.

    2. Click Upload.

    3. The Upload input field also includes the ability to remove the uploaded SAML XML configuration file from the server. Click Remove Uploaded File to remove the uploaded file from the server.

  5. Entity ID: The entity ID of the server provider. This is the audience defined in Okta.

  6. Entity Base URL: The URL of your Alert system.

  7. Sign Assertions: Select the checkbox to sign the assertions for SAML.

  8. Click Save.

To test your SAML configuration when your SAML configuration is enabled.

  1. Click + SAML Configuration. No input is required because the SAML metadata fields are tested by the server.

  2. Click Send Test Message to test the authentication.

Only one SAML application can be connected to Alert at any time.

Disabling SAML

There are two methods for disabling SAML authentication.

The first method is:

  1. Log in through SAML.

  2. Navigate to Authentication > SAML Configuration.

  3. Deselect the SAML Enabled checkbox.

The second method is:

  1. Disable SAML by setting the environment variable ALERT_SAML_DISABLED=true.

  2. Restart Alert.

User role mapping

In Alert 6.0.0 the User Role Mapping form was removed from the Authentication page.

On the SAML configuration screen, The SAML Role Attribute Mapping field is retained from the User Role Mapping form to enable the granting of ALERT_ADMIN role privileges to the Alert administrator who logs in to Alert for the first time, which enables the administrator to assign roles to other users.

 

Both for LDAP and SAML, Alert still grants privileges for the corresponding default Alert roles (ALERT_ADMIN, ALERT_JOB_MANAGER, and ALERT_USER) if the user has been assigned the following:

LDAP group names:

  • ROLE_ALERT_ADMIN
    If a user belongs to this group they have ALERT_ADMIN role privileges along with any other role privileges assigned to the user in the Alert user interface.

  • ROLE_ALERT_JOB_MANAGER
    If a user belongs to this group they have ALERT_JOB_MANAGER role privileges along with any other role privileges assigned to the user in the Alert user interface.

  • ROLE_ALERT_USER
    If a user belongs to this group they have ALERT_USER role privileges along with any other role privileges assigned to the user in the Alert user interface.

SAML attribute mapping

  • ALERT_ADMIN
    If a user contains the "AlertRoles" attribute containing a value of "ALERT_ADMIN" then ALERT_ADMIN role privileges are granted along with any other role privileges assigned to the user in the Alert user interface.

  • ALERT_JOB_MANAGER
    If a user contains the "AlertRoles" attribute containing a value of "ALERT_JOB_MANAGER" then ALERT_JOB_MANAGER role privileges are granted along with any other role privileges assigned to the user in the Alert user interface.

  • ALERT_USER
    If a user contains the "AlertRoles" attribute containing a value of "ALERT_USER" then ALERT_USER role privileges are granted along with any other role privileges assigned to the user in the Alert user interface.

The SAML Role Attribute Mapping field enables a user of Alert to configure another SAML attribute other than the default "AlertRoles" attribute to contain the Alert role information. This is intended for Alert system administrators logging in by using SAML.
The SAML attribute in the Attribute Statements that contains the roles for the user logged into Alert.

Cumulative effect of adding role assignments in SAML and LDAP

The user role from external systems such as SAML or LDAP is added to the current role configuration in the Alert database for the logged-in user.

Refer to the following example to see how roles are impacted by changes made by the Identity provider:

  1. The user has an ALERT_ADMIN role because in SAML they have the attribute specifying the role ALERT_ADMIN.

  2. The user logs into Alert 5.3.0 for the first time.

  3. The database is updated to associate the ALERT_ADMIN role with the user.

  4. The user logs out of Alert.

  5. In the SAML provider, the role attribute is changed from ALERT_ADMIN to ALERT_JOB_MANAGER.

  6. The user logs into Alert.

  7. The database is updated to associate the ALERT_JOB_MANAGER role with the user.

  8. The user now has both ALERT_ADMIN and ALERT_JOB_MANAGER roles assigned to them.

The capability to edit the role of a SAML or LDAP user in Alert  is helpful in the following circumstances:

  • The user's role is changed on the SAML or LDAP server, and the system administrator can delete the old role in Alert.

  • The system administrator adds a new role for the user that is higher than the role on the LDAP or SAML server, that role is implemented.

SAML examples

The following examples show how roles were assigned in SAML before the User Management page was added to manage users and roles.
As of Alert 5.3.0 and later, Alert administrators should create, update, and assign roles using the User Management page. Alert administrators can still set the attribute for the ALERT_ADMIN role set for themselves so that they can log in to Alert with full administrative privileges.

  • An Alert Administrators application is created that sets the AlertRoles application attribute with the ROLE_ALERT_ADMIN as the value.

  • An Alert Job managers application is created that sets the AlertRoles application attribute with the ROLE_ALERT_JOB_MANAGER as the value.

  • An Alert Users application is created that sets the AlertRoles application attribute with the ROLE_ALERT_USER as the value.

When these applications are created, the administrator assigns users to those applications. This grants the appropriate roles to the user.

You must add the AlertRoles to the attribute statements of the application. An administrator assigns the roles for the Alert application, and grants access to users of the application. Synopsys recommends creating:

  • An Alert Admin application for administrator users.

  • An Alert Job Manager for job manager users.

  • An Alert for read-only access.

The AlertRoles attribute in SAML contains a list of role names that may include one or more combinations of the following role names:

  • ALERT_ADMIN

  • ALERT_JOB_MANAGER

  • ALERT_USER

User role mapping configuration

Alert versions 5.3.0 and later have the following user roles:

  • Admin

  • Job Manager

  • User

The following fields enable LDAP group names to be mapped to a corresponding role in Alert.

If the user belongs to an LDAP group that matches the name input into one of the following fields, then Alert grants the user access to Alert, according to the mapped Alert role.

Fields for user roles

  • Admin User Role Name: The LDAP group name or SAML role attribute value to grant access as an administrator in Alert.

  • Job Manager Role Name: The LDAP group name or SAML role attribute value to grant access as a job manager in Alert.

  • User Role Name: The LDAP group name or SAML role attribute value to grant access as a user in Alert.

These fields are optional and are only required when role mapping is required for using unique role names in Alert.

 

If SAML is enabled, then SAML contains the Alert roles in an attribute assigned to the application.

For SAML, the functionality is the same: if the attribute containing the Alert roles for the user contains the input into one of these fields, then Alert grants the user access, according to the mapped Alert role. To set up user roles, navigate to Authentication > User Management (Alert 5.3.0 and earlier).

To configure Users and Roles in Alert, on the left navigation, click User Management > Users or Roles.

Redefining the SAML role attribute mapping name

Alert allows the redefinition of the SAML attribute name that contains the roles for Alert. By default, Alert expects an application attribute of AlertRoles. Alert inspects the attributes assigned to your application and retrieves the list of roles from this attribute. Access is granted if there are valid Alert roles assigned to the user. To use a name other than  AlertRoles, you can configure the name using the SAML Role Attribute Mapping field.

 

©2023 Synopsys, Inc. All Rights Reserved