Smart Tenant - Single Sign-On (SSO)

Single Sign-On

Smart supports Single Sign-On (SSO) using the SAML 2.0 protocol. Any Identity Provider (IdP) that supports SAML 2.0 should work with Smart SSO.

Smart will use the customer’s 3rd party IdP for authentication only. Authorization will be the responsibility of Smart. This means that each Smart user will need to be created within Smart and User permissions will need to be allocated/revoked within Smart. These actions are performed via the Smart web application by an authorized Smart Security Administrator. This means that if a user is authenticated by the IdP, the user will not be able to access Smart if the user is not configured within Smart.

Smart uses email addresses as the primary identifier for users. As a result, the user’s email address will be used as the mapping attribute to enable the IdP to inform Smart who the authenticated user is.

SSO can be switched on/off for all users or individual users. Once SSO is switched on for a particular user, they will not be permitted to log into Smart directly via the Smart login screen using their username and password.

SAML Response Configuration

As mentioned above, the SAML token passed from the IdP to Smart must contain the email address of the authenticated user. There are two ways of providing this email address in the SAML token:

  1. NameID: standard SAML identifier in format urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress.
  2. Attribute: regular SAML attribute with configurable name.

Switching SSO on in Smart

Tenant Wide Configuration

Single Sign-On configuration is done by exchanging metadata files between IdP and Smart.

To enable SSO for a Smart tenant, it is recommended that 2 Security Administrators are active on your Smart tenant.

SSO for a customer tenant can only be switched on by one of the Security Administrators of the Smart tenant. The Security Administrators are recommended as being employee(s) from the customer.

When a Security Administrator enables SSO for the Smart tenant, it will immediately enable it for all users of that Smart tenant, with the exception of the Security Administrator who enabled SSO. A second Security Administrator will then be required to log into Smart via the newly configured SSO, to enable SSO for the Security Administrator who enabled SSO initially. The primary reason for this is to force the validation that SSO has been configured correctly before enforcing it for all users.

Individual User Configuration

A Security Administrator has the permissions to switch SSO on/off for individual users. However, for security reasons, a Security Administrator cannot switch SSO on for themselves.

Users who are not enabled for SSO can continue to login directly to the Smart tenant via the Smart login screen.

The ability to disable SSO for a single user(s) is primarily in place to allow a customer to grant access to their Smart tenant to Kainos Smart support staff, without the need for them to exist in the customer’s IdP.

Configuring Single Sign-On in Smart

Select the Single Sign On option from the ADMIN menu. This will bring the user straight to the configuration page for Single Sign On, as seen below.

Enable the Switch SSO checkbox, then paste the Identity Provider metadata file into the Identity Provider metadata field.

Paste Identity Provider metadata file into 'Identity Provider metadata' field.

Configure the name of the attribute where email will be provided (Enter 'NameID' if you want to use NameID).

Click Save to save your configuration. On this action, SSO will be enabled for the Smart tenant and subsequently enabled for all users in the tenant (except the Security Administrator that is configuring SSO). It also generates a signing and encryption certificate used for SAML communication (if it doesn’t already exist).

After saving your initial configuration, further actions can be taken on the configuration.

The Generate new private key button can be used for regenerating the signing and encryption certificate used for the SAML communication. This certificate is initially generated automatically after enabling SSO for a tenant. It is worth noting that after certificate regeneration, the Smart metadata file will be modified and will need to be applied to the IdP again.

The Smart metadata file can then be redownloaded by clicking the Download metadata button.

Remember, to configure the Identity Provider to work with Smart for SSO, one of the following actions needs to be taken:

  • Configure NameID to be in the format urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress

or

  • Configure attribute with the Email attribute name used in the configuration, and with the value of user email address (as per option 2 in the SAML Response Configuration section)

After completing the setup of SSO, ask your second Smart Security Administrator to log into Smart using SSO to test that SSO has been configured correctly, and is working as expected. If SSO is working correctly this Security Administrator should then enable SSO for the Security Administrator who setup SSO initially.