Single sign-on: Overview

The single sign-on (SSO) feature can be used to bridge user authentication between a partner website and Tungsten AP Essentials, so users can access Tungsten AP Essentials using credentials other than their Tungsten AP Essentials credentials. This is beneficial because it lets you access multiple applications using a single log-in.

Tungsten AP Essentials supports SSO using OpenID Connect and SAML. Of the two options, OpenID Connect is more modern and easier to configure.

OpenID Connect

OpenID Connect is an authentication protocol based on OAuth 2.0. It uses REST/JSON messages to authenticate users across websites and apps without having to own and manage password files. This means you can login to Tungsten AP Essentials using Google account credentials, for example, or other identity providers that use OpenID Connect.

How it works

When you set up an identity provider in Tungsten AP Essentials, the OpenID Connect metadata service must be publicly available. Currently, Tungsten AP Essentials does not support internal OpenID Connect metadata endpoints. For added security, Tungsten AP Essentials uses Hybrid Flow (response type: "code id_token"). Tungsten AP Essentials also requires the OpenID Connect scopes, "openid" and "email".

OpenID Connect authorities (identity providers) must be whitelisted before use. Contact support to request whitelisting.

When configuring the identity provider, you must specify an authorized redirect URI from Tungsten AP Essentials. This is the address that users are redirected to after they have authenticated with the identity provider. When specifying the URI, use this format: https://host-name/sso/openidconnect

...where host-name is the Host name setting specified in the Company profile view.

If you set up an identity provider with Google, you only need to set up one OAuth 2.0 client ID for all your customer accounts.

Tungsten AP Essentials maps the User name to the email address of the identity provider credentials. In other words, your Tungsten AP Essentials user name must match the email that you use to login to the identity provider. When logging in via the identity provider, you must complete the login within 30 minutes from the time the login page is displayed.

After you configure your identity provider, you can enable single sign-on with OpenID Connect in Tungsten AP Essentials.

Some identity providers allow deactivated account names to be recycled. This means, if you have an account at a third-party identity provider, and you delete it, someone else could register a new account with the same name and potentially use it to access Tungsten AP Essentials. Therefore, it is important to always keep Tungsten AP Essentials user accounts up to date, and never leave unused user accounts in the system.

Tenancy

A tenant is a group of users. For example, in Tungsten AP Essentials, a tenant is a group of users that belong to the same customer account. With that in mind, consider the following in the context of single sign-on:

In Tungsten AP Essentials, multiple customer accounts share the same login address. In other words, multiple organizations log in to Tungsten AP Essentials using the same web page. If you use single-tenant authentication, each tenant requires its own authentication portal. Since each tenant shares the same login page, however, this could result in multiple login buttons—one for each customer organization—on the same login screen. If you use multi-tenant authentication, each tenant still shares the same login page, however, Microsoft Azure Active Directory (Azure AD) can route multiple tenants through the same portal. Therefore, with multi-tenant authentication, only one login button is needed, and only one identity provider needs to be specified on the partner level.

Tungsten AP Essentials supports single-tenant authentication and multi-tenant authentication via OpenID Connect.

Single tenant - When choosing an identify provider for single-tenant authentication, you can choose any provider that supports OpenID Connect. You must specify an identity provider for each customer account that uses single sign-on.
Multi tenant - When choosing an identify provider for multi-tenant authentication, only Microsoft Azure Active Directory (Azure AD) is supported at this time. Multi-tenant authentication is beneficial because it allows customers to login using their own Azure AD tenants with only one identity provider configuration on the partner level.

SAML

To implement single sign-on authentication with SAML, you must configure an identity provider on the partner system. After that, you can enable single sign-on in Tungsten AP Essentials.

The partner system requires:

an identity provider that can make encrypted SAML 2.0 requests.
an SSL certificate on the partner system that verifies the identity of the partner system.
an SSL certificate that contains a public key from the partner system.
the Tungsten AP Essentials API key of the partner.

How it works

Sending a SAML SSO request to Tungsten AP Essentials

Tungsten AP Essentials uses SAML 2.0 to implement single sign-on using POST binding. Tungsten AP Essentials acts as the consumer of claims and the authentication is identity-provider initiated; it is not service-provider initiated.

To send an SSO request to Tungsten AP Essentials, the identity provider must post a SAML token (example) to the Tungsten AP Essentials Assertion Consumer Service URL using this format:

https://services.readsoftonline.com/SSO/SAML2/Consume?x-rs-key=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Note that x-rs-key specifies the Tungsten AP Essentials API key of the partner, and you must use the URL that corresponds to your region:

Europe: https://services.readsoftonline.com/
Australia: https://services-au.readsoftonline.com/
US: https://services-us.readsoftonline.com/

All SAML responses from the identity provider must be signed. However, signed SAML assertions are optional. Tungsten AP Essentials accepts encrypted and unencrypted signed SAML assertions. If you choose to encrypt signed SAML assertions, you must use the public key in this ZIP file: https://production.readsoftonline.com/install/readsoftonline-saml.zip

Note: Tungsten AP Essentials does not support SAML Metadata.

After you configure your identity provider, you can enable single sign-on with SAML in Tungsten AP Essentials.

Troubleshooting

If you have problems logging in after you set up SSO for OpenID Connect or SAML, sometimes a track ID is displayed in your web browser. For your security, no other information is displayed about the issue. If you log in as a partner administrator, however, you can search for the track ID in the MESSAGE column of the Audit trail view to see why the login failed.