Share this page

# Set up SSO authentication

This topic describes how to set up on-premises SSO authentication for connecting to OpenText Software Delivery Management.

Note: SAML2 is supported both as a Service Provider for user authentication for federated customers, and as an Identity Provider for supporting SAML requests from other products SPs.

In this topic:

## Overview

This topic describes how SSO access can be authorized in a federated environment. This way, users can use single sign-on for logging in to OpenText Software Delivery Management as they do with other SSO applications at the site.

To facilitate single sign-on, the OpenText Software Delivery Management service provider (SP) sends an authentication request to the IdP, which is an online service that authenticates users using security tokens.

It is essential that the service provider (SP) can identify users uniquely when communicating with the Identity Provider (IdP). This is a two-step process.

1. Authorization. When a user logs in, OpenText Software Delivery Management attempts to locate a matching user in the IdP. For details, see About authorizing users.

2. Identification. After a user is authorized to log in, OpenText Software Delivery Management identifies which user it is. For details, see About identifying users.

Service providers and protocols

OpenText Software Delivery Management has its own built-in service provider (SP) for this purpose.

It uses the following protocols:

- SAML2 protocol is used for authentication with identity providers (IdPs).

- OAuth2 protocol is used for creating access tokens and validating them.

About authorizing users

When a user logs in, an attempt is made to locate a matching user in the IdP.

Scenario | Description and result
--- | ---
A matching user exists | Checks are made by uuid and then by name. If either of these is located successfully, the user is authorized. If the details of the user do not match, the details are updated in OpenText Software Delivery Management and the user is authorized.
No matching user exists | The user is not authorized and cannot log in. Users can be imported from the IdP using a CSV file. After the import, the user can log in. For details on importing, see Users.

Example:

Assume the following users are defined in the IdP and the OpenText Software Delivery Management SP.

UUID (IdP) | Name (IdP) | UUID (SP) | Name (SP)
--- | --- | --- | ---
100 | Carlos | 100 | Carlos
200 | Sally | 400 | Sally
300 | Lee | 300 | Svetlana
<blank> | <blank> | 900 | George

- A user named Carlos with uuid 100 attempts to log in.

  Carlos is authorized.

- A user named Svetlana with uuid 300 attempts to log in.

  The user is authorized. The name in OpenText Software Delivery Management is updated to Lee.

- A user named Sally with uuid 400 attempts to log in.

  Sally is authorized. The uuid in OpenText Software Delivery Management is updated to 200.

- A user named George with uuid 900 attempts to log in.

  Authorization fails.

About identifying users

For identification, the SP uses the mapping. user-name setting in the sso.conf file to determine how to map the username attributes to the corresponding IdP attribute after receiving the SAML response from the IdP. The mapping is based on the following.

Setting in sso.conf | SAML Response | Description
--- | --- | ---
'{$id}' | <saml2:NameID> attribute, in the <saml2:Subject> | Users are identified by mapping the OpenText Software Delivery Management user-name to the NameID in the SAML subject. This is the default.
user-name | The FriendlyName username in the <saml2:Attribute> in the <saml2:AttributeStatement> | Users are identified by mapping the OpenText Software Delivery Management user-name to the username attribute in the SAML attribute statement.

For details, see Map IdP attributes.

Tip: Other sso.conf settings that you can define for mapping purposes include: mapping uuid, mapping last-name, mapping first-name, mapping full-name, and mapping-mail. For details, see Modify site settings.

Handling existing internal users

Existing internal users defined before switching to SSO authentication already have passwords. These passwords are not overridden when the user is mapped to IdP users.

However, these internal users cannot use their original passwords to log into OpenText Software Delivery Management after it is configured for SSO, even when directly navigating to the login page. They are defined, but the SSO passwords are the only ones in use.

For details, see Import users.

Back to top

## Prerequisites

If you are using SSL with a self-signed or internal certificate, add the certificate to the CA store of the JVM runtime used to run OpenText Software Delivery Management for authentication to succeed.

Back to top

## Configure SSO integration

Configure OpenText Software Delivery Management and its service provider (SP) for SSO integration.

Verify that the initial admin is available in the IdP

The first user created in OpenText Software Delivery Management has superuser permissions and is allowed to perform any action in the system. In effect, the initial user is a site admin, a space admin, and a workspace admin for all default spaces.

This user is defined using the site-administrator > name setting in the octane.conf file.

Make sure that this admin already exists in the IdP.

Later, you can import additional IdP users. For details, see Import users.

Enable the SP

1. Modify the sso.conf file to configure the OpenText Software Delivery Management SP.

   For these settings to take affect, make sure to set the authentication type to sso in this octane.conf file using the authentication-type setting.

   Not all settings are required. Make sure to comment out unnecessary settings using the hash (#) at the beginning of a line.

   These available settings include the following.

   Setting | Description
   --- | ---
   Keystore settings | Include settings that provide the SP with the certificates needed to sign and encrypt authentication messages. Note: If you are using pkcs12, you must use the same password for both the keystore and the key(s). This is a Java limitation.
   OAuth settings | For configuring internal OAuth authentication details.
   Logging settings | For changing the SP's logging level.
   SAML metadata settings | For establishing trust.
   Redirect URI settings | Which contain the allowed addresses for redirection. This is used to validate that an authenticated user is not redirected to an incorrect place.

   For details on the settings to add to the sso.conf file, see Modify site settings.

2. Restart OpenText Software Delivery Management.

Back to top

## Establish SAML trust between the SP and the IdP

Establishing trust between the service provider (SP) and the IdP requires sharing metadata between the providers.

1. Share the IdP's metadata with OpenText Software Delivery Management.

   While enabling the SP, the IdP’s metadata was already shared.

   The metadata can be supplied with a URL or by a file. For details, see Modify site settings.

2. Share OpenText Software Delivery Management’s metadata with the IdP.

   To obtain OpenText Software Delivery Management’s metadata, go to:

   <protocol>://<host>:<port>/osp/a/au/auth/saml2/sp-metadata

   Note:

   - The metadata is available only after the OpenText Software Delivery Management server starts. For details, see Enable the SP.

   - Any additional IdP configuration is not covered here. See the documentation for the IdP. Generally, however, depending on your individual IdP, you either provide this URL in the IdP’s configuration screens, or save the XML and import it into the IdP. This configures the OpenText Software Delivery Management SP as a client for your IdP.

Back to top

## Map IdP attributes

Map the user attributes that are returned by the IdP in a SAML assertion to the equivalent OpenText Software Delivery Management attributes.

There are two ways to define user attributes by SAML. Either by using Attribute Name, or by using Attribute FriendlyName, as described in the examples below.

The attributes are case-sensitive.

The SAML response must be signed. Encryption is optional.

Note:

- OpenText Software Delivery Management overrides the built-in attributes with the ones supplied by the IdP, keeping them up-to-date with your IdP definitions.

- For UUID, Email, Full name, Last name, and First Name attributes:

  - If the IdP sends updated information in the SAML assertion, the updates override existing information in OpenText Software Delivery Management.

  - If the Friendly Name for this attribute is different in the IdP, you can specify the correct Friendly Name using the optional mapping uuid setting in the sso.conf file.

OpenText Software Delivery Management Attribute | IdP Attribute | Description
--- | --- | ---
User name | username | This mapping is mandatory. The SSO functionality does not work without the username attribute mapping. If set to '{$id}', the OpenText Software Delivery Management username is mapped to the NameID in the SAML subject. If set to username, the OpenText Software Delivery Management username is mapped to the NameID in the SAML AttributeStatement section. The value may be changed to the name of any other attribute sent in the SAML response.
UUID | uuid | The uuid of the user. Tip: Mapping by uuid is not required, but recommended. To facilitate automatic synchronization of user details from the IdP to OpenText Software Delivery Management, the uuid (the user identifier, similar to the user name) should be unique and stable. This means the attribute should not be something that is likely to change, such as email. (Using the uuid as the user identifier allows you to change the user name, if necessary.) If the uuid is not provided for mapping, OpenText Software Delivery Management tries to synchronize user details based on the mapped userName or the subject in the SAML response. However, if this value is later changed on the IdP side, OpenText Software Delivery Management is unable to identify the user.
Email | mail | The email of the user.
Full name | fullName | The full name of the user if it is different from the first-name and the last-name together.
Last name | lastName | The last name of the user.
First name | firstName | The first name of the user.

Example using Attribute Name

Here is a sample of SAML using Attribute Name:

Copy code

     <Attribute Name="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name">
            <AttributeValue>Christopher</AttributeValue>
      </Attribute>

If you are using Attribute Name, the sso.conf mapping should look like this (for example):

Copy code

    mapping user-name: 'http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name'

Example using FriendlyName

Here is a sample of SAML using Attribute FriendlyName:

Copy code

    <saml:Attribute FriendlyName="username"
                          Name="username"
                          NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
            <saml:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema"
                                 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                                 xsi:type="xs:string">jon.vilner@mail.com</saml:AttributeValue>
          </saml:Attribute>

If you are using Attribute FriendlyName, the sso.conf mapping should look like this (for example):

Copy code

    mapping user-name: username

Back to top

## Test SSO authentication

You can test SSO authentication for the UI and APIs.

To test SSO authentication:

1. To log in using SSO, enter the OpenText Software Delivery Management URL. You should be redirected to your IdP’s login screen.

2. Log in with the OpenText Software Delivery Management admin credentials.

   You are redirected to OpenText Software Delivery Management, and you can now use the application.

Back to top

## Import users

Import users and assign their permissions in the Settings area.

For details on importing users, see Users.

After users are imported, these users can log in with SSO.

Back to top

See also:

- Users
- OAuth 2.0 authentication for API keys

https://admhelp.microfocus.com Software Delivery Management 8942
Tips to improve your search results... OpenText™ Software Delivery Management Help Center OpenText™ Software Delivery Management Help 26.1 All View Local Help Center View Online Help Center Version: