How we identify tenants to provide a tailored authentication experience

Why multi-tenancy and single-sign-on?

If you are running a SaaS application, you are most probably interested in integrating your customers as seamless as possible. The authentication experience is a very important part of it. It does not only provide a great usability, but also adds additional security if the users of your customers are able to log in with their directory accounts instead of creating new users and groups for your SaaS application. So all security standards of your customers are met and there is no need for an additional user management process since they are already using their main one.

ProAuth acts as your main identity provider and all your applications and services have a single trust to it. ProAuth is able to federate between different identity providers, align the claims and issue the corresponding tokens which are then used by your applications and services. For each tenant in ProAuth, there is a wide range of settings. For example you are able to register a specific federated identity provider for a tenant and create custom login views by applying custom styling and images for your tenant.

ProAuth can be configured during runtime by using the Admin Application, the API or the CLI. This means you are able to integrate new customers (i.e. by an registration wizard) during runtime without a redeployment or restart of ProAuth.

The scenario

We are running a SaaS application which consists of a frontend (portal) and a couple of backend services. This application has a single trust to ProAuth. Calls between the services are also authenticated. Either the user access token is used and forwarded to the backend services (user centric services with impersonation of the user) or the services authenticate to each other (client credential grant). We would like to achieve a seamless authentication experience for our enterprise customers and therefore we will integrate the customers directories as a federated identity providers in ProAuth. In our scenario, our customers use either Azure Active Directory (AAD) or Active Directory Federation Services (ADFS). ProAuth supports a wide range of integration for federated identity providers or you can also host a user store instance to manage users and groups within ProAuth.

To identify the tenant, we provide a custom subdomain to each one of our customers. With this subdomain, we are able to identify the tenant during an authentication request and route the user to the corresponding tenant-specific authentication pipeline. In this case, each tenant has a single identity provider instance (IDP instance) configured and the user is directly redirected to it. Depending on the customer’s setup, the user is prompted for credentials or a single-sign-on is performed without any prompt. ProAuth verifies the token, aligns the claims with its Claim Rule Engine and issues a token which is then used by the SaaS application.

Tenant identification in ProAuth

ProAuth offers three ways to identify a tenant during the authentication request:

• Tenant-specific subdomain or route part

  Use a tenant key or a tenant id as part of the login redirect URI. The placeholder can either be applied as part of a subdomain or as part of the route.

• IP address range

  This is mostly used to identify internal tenants where the login should only be possible while the user is inside the company’s LAN.

• OIDC authentication request parameters

  Provide the tenant id in the authentication request by providing the corresponding acr_values property with a value of tenant:<tenantid>".

The configuration can be performed by API calls, the CLI or the Admin Application. For illustration purposes, we will use the UI.

To configure the above scenario, the following steps need to be performed for each tenant:

• Create a new tenant and define a tenant key which is used as part of the domain.

  

  1. Each tenant has a unique id (GUID) which can be used to identify the tenant by acr_values in the request or by using the id as part of the redirect URI.
  2. The tenant key is a logical name which can be used as part of the redirect URI.
  3. If all of the calls of a tenant originate from one or multiple IP ranges, those can be specified here and will be used for tenant identification during the authentication process.

• Create a IDP instance and assign it to the corresponding tenant.

  

Once the tenants are configured, the client application needs to be created and configured with the proper redirect URIs.

• Create a client application. In order to use dynamic subdomains, a placeholder for the tenant key can be used in the redirect URI definition.

  

Conclusion

ProAuth offers an easy and efficient way to integrate your customers as possible. The configuration is done trough the management API. The API calls can easily be integrated into a registration wizard where your customers can sign up and choose their preferred way of authentication - either manage their users and groups in ProAuth or federate to their company directory. All those changes are performed during runtime and therefore no re-deployment is needed. The tenant-specific pipelines are dynamically updated and the users do not experience any downtime.

If you are interested in ProAuth or if you would like to see more features, please reach out to our team by using the contact form or write us an e-mail. We are looking forward to get to know you and analyze your authentication requirements.