# Set up SSO authentication

This topic describes how to set up on-premises SSO authentication for connecting to .

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.

## 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 as they do with other SSO applications at the site.

To facilitate single sign-on, the 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, 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, identifies which user it is. For details, see About identifying users.

### Service providers and protocols

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 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. The users are imported with default roles and are associated with a default space and workspace. For details on setting these defaults, see XXX.

Example:

Assume the following users are defined in the IdP and the 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 is updated to Lee.

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

  Sally is authorized. The uuid in 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 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 user-name to the username attribute in the SAML attribute statement.

For details, see Map IdP attributes.

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 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.

## 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 for authentication to succeed.

## Configure SSO integration

Configure and its service provider (SP) for SSO integration.

### Verify that the initial admin is available in the IdP

The first user created in 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 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 .

## 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 .

   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 ’s metadata with the IdP.

   To obtain ’s metadata, go to:

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

   - The metadata is available only after the server starts. For details, see Enable the [%=_rscC_Basic_Variables._rsc_Product_Name%] 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 SP as a client for your IdP.

## Map IdP attributes

Map the user attributes that are returned by the IdP in a SAML assertion to the equivalent 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.

- 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 .

  - 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.

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 username is mapped to the NameID in the SAML subject. If set to username, the 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 , 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, 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, 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:

<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):

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:

<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):

mapping user-name: username

## 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 URL. You should be redirected to your IdP’s login screen.

2. Log in with the admin credentials.

   You are redirected to , and you can now use the application.

## 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.

## See also

- Users
- OAuth 2.0 authentication for API keys