Single sign-on: Overview
The single sign-on (SSO) feature can be used to bridge user authentication between a partner website and Kofax AP Essentials, so users can access Kofax AP Essentials using credentials other than their Kofax AP Essentials credentials. This is beneficial because it lets you access multiple applications using a single log-in.
Kofax 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 Kofax 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 Kofax AP Essentials, the OpenID Connect metadata service must be publicly available. Currently, Kofax AP Essentials does not support internal OpenID Connect metadata endpoints. For added security, Kofax AP Essentials uses Hybrid Flow (response type: "code id_token"). Kofax AP Essentials also requires the OpenID Connect scopes, "openid" and "email".
When configuring the identity provider, you must specify an authorized redirect URI from Kofax 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.
Kofax AP Essentials maps the User name to the email address of the identity provider credentials. In other words, your Kofax 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 Kofax 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 Kofax AP Essentials. Therefore, it is important to always keep Kofax 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 Kofax 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 Kofax AP Essentials, multiple customer accounts share the same login address. In other words, multiple organizations log in to Kofax 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.
Kofax 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 Kofax 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 Kofax AP Essentials API key of the partner.
How it works
Sending a SAML SSO request to Kofax AP Essentials
Kofax AP Essentials uses SAML 2.0 to implement single sign-on using POST binding. Kofax 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 Kofax AP Essentials, the identity provider must post a SAML token (example) to the Kofax 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 Kofax 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/
Note: Kofax AP Essentials does not support SAML Metadata.
After you configure your identity provider, you can enable single sign-on with SAML in Kofax 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.