Model: relation/HcsSsoIdpREL

Configure SSO IDP

Tip

Use the Action search to navigate Automate

This procedure configures integration with a SSO identity provider (IdP).

Go to Upload SSO IDP Metadata and upload the IdP metadata file. See Upload SSO IdP metadata.

Go to Configure SSO IDP, then click the Plus (+) icon to add the SSO identity provider configuration.

Note

Only one instance of an SSO identity provider can be configured for a hierarchy node.

While an IdP may exist at more than one hierarchy in Automate, a user will only be permitted to log in if the user exists at or below the hierarchy of a single IdP.

Complete at least the mandatory settings:

Entity ID: Mandatory. Entity ID of the IDP. This field must exactly match the entity ID in the IdP metadata file.
Login URI: Mandatory. Login URI for the IDP. This is the URI that will be embedded in SSO Login URL. It can contain only alphanumeric characters and forward slashes.
Service Provider Domain Name: The FQDN that will be embedded in the SP metadata for this IdP for URLs that refer back to the service provider.

If a customer is using a custom domain, the value for service provider domain name is filled out at the hierarchy level and the login and metadata URLs used will be tied to the IdP as follows:
```
SSO Login URL:  ``https://<Service Provider Domain Name>/sso/<Login URI>/login``
Admin Portal:   ``https://<Service Provider Domain Name>/admin/sso/<Login URI>/login``
```
The metadata is obtained from: https://<Service Provider Domain Name>/sso/<Login URI>/metadata

If the service provider domain name is specified, the metadata XML file from Automate then contains Service.Provider.Domain.Name in the assertion consumer service URL as shown in the example below:
```
<md:AssertionConsumerService
    Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
    Location="https://Service.Provider.Domain.Name/sso/acs/"
    index="1"/>
```
This metadata needs to be uploaded to the IdP (not the generic metadata obtained from SSO Service Provider Configuration).

Important

If you have previously uploaded metadata to the IDP and you subsequently complete this Service Provider Domain Name field, you need to remove the previous record from the IdP and re-upload the metadata so that it contains this field.

If the service provider domain name is not specified for a given IdP, the following URLs formats are used for SSO login:
```
SSO login URL:         ``https://<FQDN of the Service Provider>/sso/<login_URI>/login``
Admin Portal:          ``https://<FQDN of the Service Provider>/admin/sso/<Login URI>/login``
```
The IdP redirects to this FQDN on login.
Local Metadata File: Mandatory. Choose the IdP metadata file. This file must be unique across the system.
Note: A reminder to upload the IdP metadata file.
SSO Enabled: Select the checkbox to enable SSO for users synced in or created at the current hierarchy level. Clear this checkbox to disable SSO for the users associated with the defined IDP.
SSO Login URL: Read-only. Displays the SSO Login URL to use. Users with selfservice role and no Authorized Admin Hierarchy will be redirected to Self-service.
Admin SSO Login URL: Read-only. Displays the Admin Portal SSO Login URL to use.
Business Admin SSO Login URL: Read-only. Displays the new Business Admin Login URL to use. From release 21.4, this will always redirect to the new Admin Portal.
User lookup field: Mandatory. Select the field to bind the VOSS and SSO user - typically, username.
UID Attribute Name: An optional attribute name string value configured on the IdP to be used as UID for authentication. If present, this value is evaluated first by Automate as the UID and used as an alternative user identifier when the default UID record is not present. If this value is not present, the default UID record is used to identify the user.
- If a custom attribute is used as the UID from the identity provider (IdP), then use this attribute as the UID attribute name. Automate evaluates the value in UID Attribute Name first as the UID to identify the user and is for example used as an alternative user identifier when the default UID record is not present.
- If this value is not present, the default UID record is used to identify the user. For example, if the UID attribute is not mapped on the IdP, and an attribute, ElectronicMail, is mapped to mail on the (IdP), the User lookup field on the SSO IdP should be the value from the email field in Automate, and the value for UID Attribute Name should be ElectronicMail (the attribute returned by the IdP).
The full URL of a claim in the assertion may be used as the UID attribute name together with the mapped field on User.

The SAML response may include claims attributes configured on the IdP as follows:
```
'http:\/\/schemas.microsoft.com\/identity\/claims\/objectidentifier': ['e333df87-4321-4889-852e-45c291234a2b'],
'http:\/\/schemas.microsoft.com\/identity\/claims\/displayname': ['Users_Display_Name'],
...
'http:\/\/schemas.xmlsoap.org\/ws\/2005\/05\/identity\/claims\/name': ['User@some_domain.com']
```
If 'User@some_domain.com' maps to username in Automate, the SSO may be configured as follows:
- User lookup field = username
- UID Attribute Name = http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name
Authentication Scope: Hierarchical scope this server applies to.
- Full tree authentication (default): All nodes at and below this node in its tree can authenticate against this server.
- Local authentication: Only users at this node can authenticate against this server.
User Sync Type: Type of users that can authenticate against this server.
- Synced users only: Only users synced in from LDAP can authenticate against this server.
- All users

Click Save to save the SSO IdP configuration and enable SSO if selected.

Go to Admins and filter on Auth Method equals SSO to display enabled SSO users.

Related topics

See SAML SP Settings FQDN in SSO SP Settings

For further details on authentication scope, see also User Login Options by Authentication Method and Server Authentication Scope

SSO scenarios for user roles

Upload SSO IdP metadata

Model Details: relation/HcsSsoIdpREL

An asterisk * in the title indicates the field is mandatory.
If a field has a default value, it is shown in the Description column.
If the field type is an array, the Field Name has a .[n] suffix, where n is the array index placeholder.
Object and array field names are listed to provide context. If a field belongs to an object or an array, the full field name is shown in dot separated notation.

Title			Description	Details
Entity Id *			The unique identifier of the Identity Provider.	Field Name: entity_id Type: String
Login URI			This is a URI that will be embedded in the base SSO login URL in order to authenticate specifically with this IDP. This field must only contain alphanumeric characters and forward slashes, and should match the following regular expression ^\w+(/\w+)*$ Eg. Given a login URI of provider1/customer1, end users wishing to authenticate against this IDP will login via the following URL: http://hostname/sso/provider1/customer1/login/.	Field Name: login_uri Type: String Pattern: ^\w+(/\w+)*$
Service Provider Domain Name			This is a FQDN that will be embedded in the SP metadata for this IDP for URLs that refer back to the Service Provider (eg ACS). It should match the customer-specific FQDN used for the VOSS-4-UC server.	Field Name: sp_fqdn Type: String Format: host-name
User lookup field			User field used to bind SSO user with VOSS user. Default: username	Field Name: user_lookup_field Type: String Default: username
UID Attribute Name			Attribute configured on Identity Provider to be used as UID.	Field Name: uid_attribute_name Type: String
Metadata			Indicates where metadata can be found. This can be either a file accessible locally on the system or somewhere on the network.	Field Name: metadata Type: Object
	Local Metadata File			Field Name: metadata.local Type: String Target: data/File Format: uri
	Remote Metadata URL			Field Name: remote Type: Object
		URL	Location where metadata is to be downloaded from.	Field Name: metadata.remote.url Type: String
		Certificate	To verify the authenticity of the file downloaded from the net the local copy of the public key should be used. This public key must be acquired by some out-of-band method.	Field Name: metadata.remote.certificate Type: String Target: data/File Format: uri
Authentication settings			Authentication settings.	Field Name: authentication Type: Object
	Authentication Scope		Hierarchical scope this server applies to Default: Down	Field Name: authentication.scope Type: String Default: Down Choices: ["Current hierarchy level only", "Current hierarchy level and below"]
	User Sync Type		Type of users that can authenticate against this server. Default: All	Field Name: authentication.user_type Type: String Default: All Choices: ["LDAP synced users only", "All users"]
Login Url				Field Name: loginUrl Type: Object
	IDP Entity ID		The SSO IDP Entity ID	Field Name: loginUrl.entity_id Type: String MaxLength: 1024
	SSO Login URL		The URL will be updated after you add SSO IDP .	Field Name: loginUrl.login_url Type: String MaxLength: 1024
	Business Admin SSO Login URL		The BAP URL will be updated after you add SSO IDP .	Field Name: loginUrl.bap_login_url Type: String MaxLength: 1024
	Admin SSO Login URL		The Admin URL will be updated after you add SSO IDP .	Field Name: loginUrl.admin_login_url Type: String MaxLength: 1024
	Note		Reminder for Uploading IDP Metadata file first.	Field Name: loginUrl.note Type: String MaxLength: 1024