Tenant management
Tenants
Rather than configuring generic connections like Google Login or Azure AD for all your users to login to your platform through Authress, Tenants let you say:
I want to let our customers configure their own connections, so their employees can use their corporate identity to login to the application, without needing to manually set up a connection for every different kind of provider
Then for each of your customers, you can enable them to configure their own tenant and connection. This allows them to control how their users connect and interact with your platform.
A tenant is a separation of users in your platform. Usually this maps 1:1 with the businesses that you connect.
SSO Connection
Most businesses bring their own user identity and login authentication solutions. They federate login for all their users' apps, and will want to also login to your platform via their same SSO solution. Authress provides a solution to register each of these businesses as tenants and specify their login configuration.
Login flow
The common use case is that user arrives at the platform login prompt. This login may be a generic Login with Google or if they want to use their SSO, Login with SSO. Navigating this flow requires that they have at least one piece of information to identify their account. Either their user account or their account on your platform.
This is important, they cannot log in without knowing which account they want to log in to. This is because each account offers a different log in mechanism.
There are usually two solutions to this sort of problem:
- Email account domain matching. As a platform you can keep track of which email domains map to which accounts. When the user shows up they can enter their email address. Since there is a mapping, resolving the domain to accountId is easy. However this requires keeping a list of these domains, and each account may have more than one domain. Additionally, a domain cannot be reused across accounts. For this reason it is usually not advised to handle this mapping.
- Enter the account identifier, this must be a unique identifier for each account, although it need not be the accountId. In other words a Memorable Tenant name => Random generated identifier. Using the accountId can make it challenging for users to remember without bookmarking a link to the login screen. Conversely using a user-provider identifier may make it challenging for your platform to handle an additional mapping. Frequently an identifier is used, and this same identifier is often also used as a subdomain of the platform domain. So if the platform is at https://platform.com, an account may have the subdomain https://sub.platform.com.
Authress provides support for the latter solution. While it is an arbitrary string which is used for no other purpose than to log in (it also shows in the access tokens for visibility), providing this mapping of lookup-subdomain-string to account SSO configuration is a valuable one.
Tenant model
The Authress tenant configuration includes the following information. The purpose here is for each business to configure their connection which gets populated into Authress. In most cases these values are ones that their businesses already know about and can manually populate. In some cases, it makes sense to prepopulate the data, but most platforms should be able to configure this directly. Unless the tenant information will only be used for non-security related purposes, such as display names, email addresses, etc... It is highly recommended that the Connection information should be distinct. Either the clientId or authentication url should be unique to that business.
The Subdomain
As discussed above this provides a unique lookup value for SSO login which dynamically resolves to the account's tenant info. This can be any string, but is best used as a user defined value.
Tenant ID
The tenant ID should map to the generated account ID in your platform. This identifier can be used to make decisions about which tenant or account a user is acting on behalf of.
Connection
A connection is the OpenID OAuth configuration provided which allows users to log in to your platform. It contains the necessary urls and client/secret pairs, so that Authress can verify tokens from the provider and generate an abstracted token with this information.
Authentication tokens
After tenants have been configured, Authress can proceed to log users in and generate tokens. These tokens are unique via the combination of your Authress tenant, the business's SSO, and the user.
UserID: Sub
The user's identifier or the sub is dynamically generated in Authress. It is done to create unique users, and users that are generated through different tenants or connections will have different userIds. This prevents bad actors which signup to your platform from infiltrating other businesses' user protected data.
Issuer: ISS
The Issuer of the tokens generated will match your custom domain configuration. The custom domain is configured for your Authress tenant, and is unique per tenant. This is tied to your DNS provider.
Audience: AUD
The access tokens generated provide the Audience claim which contains the TenantId as configured in the tenant. This value allows services in your platform to detect for which tenant audience permissions should be allowed. Since every user has a unique ID, it may or may not be necessary to use.
Finalizing the setup
SSO OAuth security requires valid redirect urls. Specifically to ease the ability to configure new tenants very quickly, a since redirect url exists for all your users. As such the process to generate a client and OIDC connection information for customer's business includes entering a redirect or callback url.
For them they should always enter https://auth.yourdomain.com/login, where this is your Authress custom domain configured in the Custom Domain section of Authress.
If this has not yet been configured, for ease of testing with your localhost development, a temporary url exists at: https://ACCOUNT_ID.login.authress.io/login (This url can be copied from the API Host setting).