[Index]

Model: relation/HcsSsoIdpREL

SSO Identity Provider

System Message: WARNING/2 (<string>, line 2)

Title underline too short.

Configure Single Sign-On for VOSS Automate
--------------------------------------

To access the latest documentation, go to Documentation and Resources at: https://voss.portalshape.com

Before You Begin

Create a self-signed or third-party-signed system certificate before you configure self-service SSO. For more information, see SSO Certificate Management.

The VOSS Automate server and the IdP (identify provider) server must be configured so that their clocks are synchronized.

Follow these steps to configure self-service Single Sign-On (SSO) for VOSS Automate. The configuration applies to the customers and customer administrators associated with the IdP.

Note

Administrators are configured for SSO use via the Users form (default menu User Management > Users).

Procedure

  1. Log in to VOSS Automate as hcsadmin.

  2. Choose Single Sign On > SSO SP Settings.

  3. Click Add.

    Note: Configure only one instance of SSO SP Settings.

  4. On the Base tab, from the mandatory System Certificate drop-down, choose the System Certificate to use. To allow the SSO SP Setting to expire, enter a number of hours in the Validity (Hours) field.

    Note:

  5. On the SAML SP Settings tab, enter the mandatory FQDN of the Server.

    Note

    The FQDN of the Server is stored in the SP metadata that is uploaded to the IdP.

    The SSO login URL then contains the fully qualified domain name (FQDN) :

    https://<FQDN of the Server>/sso/<login_URI>/login

    If you have configured a custom hostname for SSO user login, enter it here.

    Upon login, the IdP will redirect you to this FQDN.

    Select the Sign Authn Requests and Want Assertions Signed check boxes as required by your security environment.

    Note that if a secure connection is required with the secure attribute set on the cookies, the URL values for bindings of End Points must be specified with https.

  6. Click Save.

  7. To view the location of the VOSS Automate SP metadata that you will upload to the IdP, choose Single Sign On > SSO SP Metadata. Point your browser to the URL shown here, and then save a copy of the SP metadata.

  8. Upload the SP metadata to the IdP.

    Refer to your IdP documentation for details on configuring SSO on your IdP.

    Note:

    The IdP must release the UID and map it to an appropriate attribute. For example, an IdP that authenticates with Active Directory can map the uid SAML attribute to sAMAccountName in the Active Directory server.

  9. Download the IdP metadata from the IdP server.

    Refer to your IdP documentation for details on downloading IdP metadata.

    Note:

    If an expired SSO certificate is being renewed and the IdP metadata has not changed, then the download, configure and upload of the IdP metadata is not required.

  10. Log in as provider, reseller, or customer administrator, depending on your IdP configuration level.

  11. Choose Administration Tools > File Management and upload the IdP metadata.

  12. Choose Single Sign On > SSO Identity Provider.

  13. Click Add to add the SSO Identity Provider configuration.

    Note: Only one instance of an SSO Identity Provider can be configured for a hierarchy node.

  14. On the SSO Identity Provider screen, complete at minimum, the mandatory SSO Identity Provider fields (see SSO Identity Provider fields).

  15. Click Save to save the SSO Identity Provider Configuration and enable SSO if selected.

  16. Choose User Management > Users and filter on Auth Method equals SSO to display enabled SSO users.

Use this URL for your SSO login:

https://<FQDN of the Server>/sso/<login_URI>/login

Upon login, the IdP will redirect you to this FQDN.

SSO Identity Provider Fields

Field Description
Entity Id * Entity ID of the IdP. This can be extracted from the IdP metadata file. This field is mandatory.
Login URI * 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. This field is mandatory.
Local Metadata File * Choose the IdP metadata file. This field is mandatory and must be unique across the system.
SSO Enabled Select the check box to enable SSO for users synced in or created at the current hierarchy level. Clear this check box to disable SSO for the users associated with the defined IdP.
Note Reminder to upload the IdP metadata file
SSO Login URL Read-only field displays the SSO Login URL to use.

SSO Identity Provider

Full HTML Help

Integrating with an SSO Identity Provider

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

  1. Log in as Provider, Reseller, or Customer administrator (depending on your IdP configuration level).

  2. Choose Administration Tools > File Management and upload the IdP metadata.

  3. Choose Single Sign On > SSO Identity Provider.

  4. Click Add to add the SSO Identity Provider configuration.

    Note

    Only one instance of an SSO Identity Provider can be configured for a hierarchy node.

  5. On the SSO Identity Provider screen, complete at least the mandatory fields (Entity ID, Login URI, Local Metadata File, User lookup field at minimum, the mandatory SSO Identity Provider fields (see SSO Identity Provider fields):

    If a customer is using a custom domain, the Service Provider Domain Name is filled in 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 VOSS-4UC 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.

  6. Click Save to save the SSO Identity Provider Configuration and enable SSO if selected.

  7. Choose User Management > Users and filter on Auth Method equals SSO to display enabled SSO users.

When the Service Provider Domain Name is not specified for a given IDP, these URLs 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``

See SAML SP Settings FQDN in SSO SP Settings.

The IdP redirects to this FQDN on login.

Note

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

SSO Identity Provider: Field Reference

Field Description
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.
Local Metadata File Mandatory. Choose the IdP metadata file. This field must be unique across the system.
SSO Enabled Select the check box to enable SSO for users synced in or created at the current hierarchy level. Clear this check box to disable SSO for the users associated with the defined IDP.
Note Reminder to upload the IdP metadata file
SSO Login URL Read-only field 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 new 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.
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

For Authentication Scope, also see User Login Options by Authentication Method and Server Authentication Scope.

SSO Scenarios for User Roles

The table below shows the interface a user will be directed to when using a specific SSO URL, according to the user's role: either single role or multiple role (includes Authorized Admin Hierarchy).

User Role Auth Admin? URL used UI (Session Limiting) Expected Behavior
selfservice Yes https:/<hostname>/sso/<login-uri>/login administrator Redirect to Classic Admin
selfservice Yes https:/<hostname>/admin/sso/<login-uri>/login administrator Redirect to Admin
selfservice No https:/<hostname>/sso/<login-uri>/login selfservice Redirect to Self-service
administration Yes https:/<hostname>/sso/<login-uri>/login administrator Redirect to Classic Admin
administration Yes https:/<hostname>/admin/sso/<login-uri>/login administrator Redirect to Admin
administration No https:/<hostname>/sso/<login-uri>/login administrator Redirect to Classic Admin
administration No https:/<hostname>/admin/sso/<login-uri>/login administrator Redirect to Admin

Administrators set up with SSO but who have multiple user roles and who wish to access the Self-service interface must navigate to the Self-service portal URL upon login:

https://<Hostname>/selfservice/#/

Model Details: relation/HcsSsoIdpREL

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