.. _configure_single_sign-on_for_voss-4-uc: .. rst-class:: chapter-with-expand Configure Single Sign-On for VOSS Automate ------------------------------------------- .. _20.1.1|VOSS-568: .. _20.1.1|VOSS-551|EKB-4383: .. _20.1.1|VOSS-551|EKB-7380: .. _20.1|VOSS-693|EKB-8995: .. _19.3.4-PB5|EKB-8995: .. _21.1|EKB-8995: .. _21.3|VOSS-911: This procedure configures self-service Single Sign-On (SSO) for VOSS Automate. The configuration applies to customers and customer administrators associated with the identify provider (IdP). .. note:: * Administrators are configured for SSO use via the **Users** form (default menu **User Management > Users**). * Administrators can also be configured with multiple user roles, i.e. have a user type "End User + Admin" (see: :ref:`create_a_user`). While the role of such an administrator user is "selfservice", the user's association with a Authorized Hierarchy model instance redirects such an administrator to the *same* interface as a single role administrator when using the SSO URLs for login - as indicated under *Integrating with an SSO Identity Provider* below. Administrators with multiple user roles who wish to access the *Self-service* interface, need to explicitly switch to the Self-service portal URL upon login: :: https:///selfservice/#/ **Prerequisites** * Create a self-signed or third-party-signed system certificate. For more information, see :ref:`sso-certificate-management`. * The VOSS Automate server and the IdP server must be configured so that their clocks are synchronized. .. _sso-service-provider-configuration: SSO Service Provider Configuration ................................... 1. Log in to VOSS Automate as system administrator. #. Choose **Single Sign On > SSO SP Settings**. .. note:: This screen is only available to you if you've logged in as a higher-level administrator. #. Click **Add**. .. note:: Configure only one instance of SSO SP Settings. #. On the **Base** tab: * (Mandatory). From the **System Certificate** drop-down, choose the System Certificate to use. See :ref:`sso-certificate-management`. * To allow the SSO SP Setting to expire, enter a number of hours in the **Validity (Hours)** field. .. note:: * Specifying an unsigned third-party-signed certificate results in an error. * To renew an expired certificate, see :ref:`renew_single_sign-on-certificate_for_voss-4-uc`. #. On the **SAML SP Settings** tab: * Enter the mandatory **FQDN of the Server**. * Select the **Sign Authn Requests** and **Want Assertions Signed** check boxes as required by your security environment. .. note:: * Only select **Want Reponse Signed** if you're sure that all IdPs sign responses. * 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``. #. Click **Save**. #. 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. #. Upload the SP metadata to the IdP. Refer to your IdP documentation for details on adding VOSS Automate as a service provider. .. 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. #. 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, the download, configure and upload of the IdP metadata is not required. Integrating with an SSO Identity Provider ............................................ 1. Log in as provider, reseller, or customer administrator (depending on your IdP configuration level). #. Choose **Administration Tools > File Management** and upload the IdP metadata. #. Choose **Single Sign On > SSO Identity Provider**. #. 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. #. 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:///sso//login`` Admin Portal: ``https:///admin/sso//login`` Business Admin Portal: ``https:///business-admin/sso//login`` The metadata is obtained from: ``https:///sso//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: :: 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. #. Click **Save** to save the SSO Identity Provider Configuration and enable SSO if selected. #. 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:///sso//login`` Admin Portal: ``https:///admin/sso//login`` Business Admin Portal: ``https:///business-admin/sso//login`` See **SAML SP Settings FQDN** in :ref:`sso-service-provider-configuration`. 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 ...................................... .. tabularcolumns:: |p{3.5cm}|p{12cm}| +----------------------+------------------------------------------------------------------------------+ | Field | Description | +======================+==============================================================================+ | | Mandatory. Entity ID of the IDP. This field must exactly match the | | Entity Id | entity ID in the IdP metadata file. | | | | +----------------------+------------------------------------------------------------------------------+ | | Mandatory. Login URI for the IDP. This is the URI that | | Login URI | will be embedded in SSO Login URL. It can | | | contain only alphanumeric characters and | | | forward slashes. | +----------------------+------------------------------------------------------------------------------+ | Service Provider | The FQDN that will be embedded in the SP metadata for this | | Domain Name | IdP for URLs that refer back to the Service Provider. | +----------------------+------------------------------------------------------------------------------+ | Local Metadata | Mandatory. Choose the IdP metadata file. This field | | File | must be unique across the system. | +----------------------+------------------------------------------------------------------------------+ | | Select the check box to enable SSO for users synced in or | | SSO Enabled | 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. | +----------------------+------------------------------------------------------------------------------+ | Business Admin | Read-only. Displays the Business Admin Portal SSO Login URL to use. | | Portal Login URL | | +----------------------+------------------------------------------------------------------------------+ | Admin Portal Login | Read-only. Displays the new Admin Portal SSO Login URL to use. | | URL | | +----------------------+------------------------------------------------------------------------------+ | 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 :ref:`user-login-auth-method-srv-auth-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). .. tabularcolumns:: |p{2cm}|p{1cm}|p{9cm}|p{2cm}|p{2cm}| ============== =========== ======================================================= ========================= ========================== User Role Auth Admin? URL used UI (Session Limiting) Expected Behavior ============== =========== ======================================================= ========================= ========================== selfservice Yes https:///sso//login administrator Redirect to Classic Admin selfservice Yes https:///business-admin/sso//login administrator Redirect to Business Admin selfservice Yes https:///admin/sso//login administrator Redirect to Admin selfservice No https:///sso//login selfservice Redirect to Self-service administration Yes https:///sso//login administrator Redirect to Classic Admin administration Yes https:///business-admin/sso//login administrator Redirect to Business Admin administration Yes https:///admin/sso//login administrator Redirect to Admin administration No https:///sso//login administrator Redirect to Classic Admin administration No https:///business-admin/sso//login administrator Redirect to Business Admin administration No https:///admin/sso//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:///selfservice/#/