Configuring External Authentication Types

You can configure multiple external authentication types, and multiple instances of each type. You can support persistent users, who have corresponding Oracle Communications Unified Assurance accounts, and transient users, who do not.

About Transient Users

Externally-authenticated persistent users have matching Unified Assurance user accounts, which, along with their group and role, contain the permissions, properties, and preferences that apply to the user. For persistent users, you create corresponding accounts in the external authenticator or identity provider (IdP) and Unified Assurance.

Unlike persistent users, transient users do not have corresponding Unified Assurance user accounts. Instead, you set up corresponding user groups in your external authenticator or IdP and Unified Assurance. Transient users are useful when you have a large number of user accounts in your IdP; instead of recreating each account in Unified Assurance, you only need to recreate user groups and their related roles and permissions. After setting up the authentication type in Unified Assurance, if you add new users to existing groups in your IdP, they will be able to access Unified Assurance immediately, without additional configuration.

Unified Assurance identifies transient users by the presence of a domain in their username. For example, user123 would be a persistent user, but user123@example.com would be a transient user.

When a transient user logs in using an external authentication method, Unified Assurance applies permissions, properties, and preferences based on the Unified Assurance user group that matches the user group name in the IdP.

For SAML, the SAML response contains the list of user groups. For LDAP and Microsoft Active Directory, Unified Assurance uses an ldapsearch query to identify the user's groups.

If the list in the response contains multiple groups, Unified Assurance uses the first group to identify the primary Unified Assurance user group. The preferences, properties, and permissions from this group apply to the transient user. If the first group in the response does not exist in Unified Assurance, authentication fails.

If there are multiple groups in the response, Unified Assurance treats any beyond the first as subgroups. If they exist in Unified Assurance, their restrictive group properties apply to the transient user. If they do not exist in Unified Assurance, authentication still succeeds, and only the primary group and any existing subgroups apply.

The following example shows a SimpleSAML IdP configuration for a transient user:

'users' => [
   'transientuser1:<password>' => [
   'uid'    => [ 'transientuser1@example.com' ],
   'member' => [ 'employees', 'headoffice', 'devops' ]
]

In this example, the user ID (uid) includes the example.com domain, and the user is a member of three groups configured in the IdP. If only the employees and devops groups apply to Unified Assurance, you would do the following to support this user in Unified Assurance

  1. Configure the SAML authentication type for transient users with the example.com domain and the appropriate NameID format.

  2. Create user groups named employees and devops.

When transientuser1@example.com logs in to Unified Assurance, the permissions and preferences set for the employees user group and associated role apply. The transient user also inherits the restrictive group properties set for the devops group. Because the headoffice group does not exist in Unified Assurance, it is ignored.

About Using Multiple Authentication Types and Instances

You can configure multiple authentication types within a single instance of Oracle Communications Unified Assurance, and multiple instances of each external authentication type.

There will always only be a single instance of the Internal authentication type. You cannot delete, clone, or disable it, and the concept of transient users does not apply to this authentication type.

When a user logs in, Unified Assurance attempts to authenticate with each enabled protocol in sequence, either by matching the username for a persistent user or any specified domain for a transient user.

If it cannot authenticate with the first protocol, it tries again with the next in the following order:

  1. SAML: Users can either log in to their IdP and then navigate to Unified Assurance (IdP initiated), or they can log in directly to Unified Assurance (service provider (SP) initiated).

  2. Active Directory and LDAP

  3. Internal

  4. Default Active Directory or LDAP: If the username does not include a domain and no other persistent user authentication methods worked, treat the user as a transient user and attempt to authenticate at the domain of the default LDAP or Active Directory instance.

About Using Multiple SAML Authentication Type Instances

When you have multiple SAML instances enabled, for IdP initiated logins, Unified Assurance needs more information to identify the correct authentication type instance. In this situation, the Unified Assurance login page loads, prompting the user for their username. Unified Assurance can then find the authentication type instance using either the username for a persistent user or the domain for a transient user.

Authentication Flow Examples

The following examples illustrate the authentication process for the different authentication types. The examples assume:

Persistent SP Initiated SAML User Example

In this example, a user enters their username in the Unified Assurance login page.

Unified Assurance:

  1. Finds a Unified Assurance user account configured with the SAML authentication type that matches the specified username.

  2. Redirects to the IdP to authenticate the user.

  3. Seamlessly opens the Unified Assurance UI.

Transient IdP Initiated SAML User Example

In this example, a user logs in to their organization home page with their user ID, which consists of a username and domain name. They click a link to access a Unified Assurance dashboard.

Unified Assurance:

  1. Prompts the user for their username so that it can identify which of the two enabled SAML authentication type instances to use.

  2. Does not find a user account for any SAML authentication type that matches the username.

  3. Finds a SAML authentication type configured with the specified domain.

  4. Initiates a session with the IdP to authenticate the transient user.

  5. Identifies the appropriate user groups in the SAML response based on the Group Attribute configured for the authentication type instance.

  6. Opens the Unified Assurance dashboard, applying permissions, properties, and settings from the user groups.

Persistent LDAP User Example

In this example, a user enters their username in the Unified Assurance login page.

Unified Assurance:

  1. Does not find a matching SAML account, and since no domain was specified, does not attempt to authenticate a transient SAML user.

  2. Prompts the user for a password.

  3. Finds a Unified Assurance user account configured with the LDAP authentication type that matches the username.

  4. Authenticates the user with the LDAP server.

  5. Opens the Unified Assurance UI.

Transient LDAP User Example

In this example, a user enters their username, including the domain, in the Unified Assurance login page.

Unified Assurance:

  1. Does not find a matching SAML account or SAML authentication type with the specified domain.

  2. Prompts the user for a password.

  3. Does not find a Unified Assurance user account configured with the LDAP authentication type that matches the username.

  4. Finds an LDAP authentication type configured with the specified domain.

  5. Authenticates the transient user with the LDAP server.

  6. Runs an ldapsearch query to get the user's groups.

  7. Identifies the matching Unified Assurance groups.

  8. Opens the Unified Assurance UI, applying permissions, properties, and settings from the user groups.

Forgetful Transient LDAP User Example

In this example, a user enters their username in the Unified Assurance login page, but forgets to include the domain.

Unified Assurance:

  1. Does not find a matching SAML account, and since no domain was specified, cannot attempt to authenticate a transient SAML user.

  2. Prompts the user for a password.

  3. Does not find a Unified Assurance user account configured with the LDAP authentication type that matches the username, and since no domain was specified, cannot attempt to authenticate a transient LDAP user.

  4. Does not find a Unified Assurance user account configured with the internal authentication type that matches the username.

  5. Finds the domain of the LDAP or Active Directory authentication type marked as default.

  6. Authenticates the transient user with the LDAP server at the default domain.

  7. Runs an ldapsearch query to get the user's groups.

  8. Identifies the matching Unified Assurance groups.

  9. Opens the Unified Assurance UI, applying permissions, properties, and settings from the user groups.

Configuring Authentication Type Instances

Each authentication type requires different information and different configurations to support transient users. The following sections describe the requirements and steps.

Configuring a SAML Authentication Type Instance

  1. (Optional) To support transient Unified Assurance users, when configuring user groups and users in your IdP, include the domain in the user IDs. For example, transientuser1@example.com. When authenticating a transient user, Unified Assurance uses the domain to determine the SAML identity provider to authenticate with.

  2. Gather the following information:

    • The SAML entity ID URL

    • The SAML single sign-on service URL

    • The SAML single logout service URL

    • The SAML certificate

    • The SAML NameID format, if different from the default:

      urn:oasis:names:tc:SAML:2.0:nameid-format:persistent

    • The user names of SAML users to create persistent Unified Assurance accounts for

    • (Optional) If you are supporting transient Unified Assurance users:

      • The domain to use for them

      • The name of the attribute used for user groups in the IdP. This can vary. For example, it could be member, eduPersonAffiliation, or another string.

      • The user groups created for transient users in the IdP.

      Note:

      The Unified Assurance concept of transient users is not related to the SimpleSAML transient NameID format. If you are using the same SAML instance for persistent and transient users, do not use the transient or emailAddress NameID formats. These formats prevent persistent SAML users from logging in.

  3. In Unified Assurance, create the authentication type, specifying the gathered values in the Settings (Identity Provider) section of the Authentication Types UI. To open this UI, from the main navigation menu, select Configuration, then AAA, and then Authentication Types.

    Note:

    Although other IdP configurations support multiple single sign-on and single logout services with different links for different connection methods or bindings, such as HTTP-SOAP or HTTP-POST, Unified Assurance SAML only supports the HTTP-Redirect method.

    See Authentication Types - SAML in Unified Assurance User's Guide for information about the fields in the SAML form.

  4. Provide the automatically-populated values from the Settings (Service Provider for Internal Presentation) and Settings (Service Provider for External Presentation) sections to your SAML administrator for the SAML back-end configuration.

    Note:

    When you are using a shared Web FQDN in a Unified Assurance environment, these settings always point to the Web FQDN alias. Users must use the Web FQDN to log in. If a user enters the Host FQDN in the browser, SAML authentication will not work properly because the IdP server does not have the Host FQDN service provider entry. Other authentication types will work when the Host FQDN is used to access the environment.

  5. Restart the Unified Assurance web service:

    systemctl restart assure1-web

  6. For persistent users, create users in Unified Assurance that correspond to the SAML users. See Users in Unified Assurance User's Guide for information about this UI.

  7. (Optional) To support transient Unified Assurance users, create user groups in Unified Assurance that correspond to the SAML user groups. The user group names must match. See User Groups in Unified Assurance User's Guide for information about this UI.

Configuring an Active Directory Authentication Type Instance

  1. Gather the following information:

    • The primary and secondary Active Directory server IP addresses or DNS names

    • The Active Directory domain. The same domain is used for persistent and transient Unified Assurance users.

    • The Active Directory CA certificate, if you are using a secure connection

  2. Create the ldap.conf file to point to the SSL certificate for the Active Directory server:

    1. Get the CA certificate or self-signed certificate for the Active Directory server and place it in the $A1BASEDIR/etc/ssl directory.

      If you are using multiple instances of the Active Directory authentication type, concatenate the certificates from each server into a single certificate.

    2. In the $A1BASEDIR/etc/ directory, create a file called ldap.conf.

    3. Add the following two lines to ldap.conf, replacing <UA_home> with the directory where you installed Unified Assurance (for example, /opt/assure1) and <LDAP_CA_CERT> with the exact name of the CA cert (for example, OCUACA.pem):

      TLS_REQCERT never 
TLS_CACERT <UA_home>/etc/ssl/<LDAP_CA_CERT>

    4. Save and close the file.

    5. Restart the Unified Assurance web service:

      systemctl restart assure1-web

  3. Create the authentication type by using the Authentication Types UI. To open this UI, from the main navigation menu, select Configuration, then AAA, and then Authentication Types.

    See Authentication Types - Active Directory in Unified Assurance User's Guide for information about the fields in the Active Directory form.

  4. For persistent users, create users in Unified Assurance that correspond to the Active Directory users. See Users in Unified Assurance User's Guide for information about this UI.

  5. (Optional) To support transient Unified Assurance users, create user groups in Unified Assurance that correspond to the Active Directory security groups. The user group names must match. See User Groups in Unified Assurance User's Guide for information about this UI.

Configuring an LDAP Authentication Type Instance

  1. (Optional) To support transient Unified Assurance users, when you configure LDAP users and groups, grant users read permission for their own user groups. Because Unified Assurance runs an ldapsearch request as the logged in user to identify the user's groups, users need access to their own groups.

    For example, with OpenLDAP, the olcAccess should include:

    olcAccess: {index}to * by self read by * none

    You can verify that a user can see their own groups with the following ldapsearch command:

    ldapsearch -x -LLL -h <ldap-server>  -D "cn=<username>,ou=<organization_unit>,dc=<domain>,dc=<domain_extension>" -w <password> -b "cn=<username>,ou=<organization_unit>,dc=<domain>,dc=<domain_extension>" memberOf

    The response looks similar to the following:

    dn: cn=<username>,ou=<organization_unit>,dc=<domain>,dc=<domain_extension>
memberOf: cn=<group_name>,dc=<domain>,dc=<domain_extension>

  2. Gather the following information:

    • The primary and secondary LDAP server IP addresses or DNS names

    • The LDAP distinguished name

    • The LDAP CA certificate, if you are using a secure connection

    • (Optional) The LDAP port

    • The user names of LDAP users to create persistent Unified Assurance accounts for

    • (Optional) If you are supporting transient Unified Assurance users:

      • The domain to use for them

      • The group attribute to use in the ldapsearch to identify the user groups that apply to them

      • The LDAP user groups created for them.

  3. Create the ldap.conf file to point to the SSL certificate for the LDAP server:

    1. Get the CA certificate or self-signed certificate for the LDAP server and place it in the $A1BASEDIR/etc/ssl directory.

    2. In the $A1BASEDIR/etc/ directory, create a file called ldap.conf.

    3. Add the following two lines to ldap.conf, replacing <UA_home> with the directory where you installed Unified Assurance (for example, /opt/assure1) and <LDAP_CA_CERT> with the exact name of the CA cert (for example, OCUACA.pem):

      TLS_REQCERT never 
TLS_CACERT <UA_home>/etc/ssl/<LDAP_CA_CERT>

    4. Save and close the file.

    5. Restart the Unified Assurance web service:

      systemctl restart assure1-web

  4. Create the authentication type by using the Authentication Types UI. To open this UI, from the main navigation menu, select Configuration, then AAA, and then Authentication Types.

    See Authentication Types - LDAP in Unified Assurance User's Guide for information about the fields in the LDAP form.

  5. For persistent users, create users in Unified Assurance that correspond to the LDAP users. See Users in Unified Assurance User's Guide for information about this UI.

  6. (Optional) To support transient Unified Assurance users, create user groups in Unified Assurance that correspond to the LDAP user groups, matching the user group names to the LDAP group common names (cn). See User Groups in Unified Assurance User's Guide for information about this UI.

See the following topics for more information about setting up user accounts, user groups, and authentication types: