A tenant is a separation of users in your platform. Usually this maps 1:1 with the businesses that you connect.
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.
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:
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.
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.
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.
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.
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.
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.
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.
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.
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.
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://custom.domain.io/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 (with the AccountId specified as your Authress accountId).