Single Identity Provider: Authentication

In our architecture scenarios, we provide general purpose guidance on B2B Authentication, including the use of the Universal Login as a recommended best practice, which we recommend reviewing alongside the guidance provided here.

Authenticating users requires the processing of first-factor credentials. Whether this is performed by Auth0 or by some third-party Identity Provider (IdP), when you use the Auth0 Organizations feature, you must also use Auth0 Universal Login Experience capability.

Using our Hoekstra & Associates example, let's see how this Authentication implementation might flow with a user authenticated via an Auth0 Database Connection; most of the workflow described will typically be handled by using the relevant Auth0 SDK or library associated with your technology stack:

1. Jennifer from Hoekstra & Associates opens her browser and navigates to Hoekstra & Associates' instance of Travel0 Corporate Booking.

   1. If Jennifer already has a session cookie with Hoekstra & Associates' instance of Travel0 Corporate Booking, then she will typically be logged in to the system, and we will exit here. For more information, see Single Sign-On.

2. Hoekstra & Associates' instance of Travel0 Corporate Booking redirects to the Travel0 Auth0 Tenant using Authorization Code Flow (with or without PKCE) by calling the /authorize endpoint and passing parameters, typically via use of an Auth0 SDK or third-party library:

   1. redirect_uri: https://hoekstra.corp.travel0.net/login/callback

   2. response_type: code

   3. state: Unique state generated in this session

   4. scope: openid profile ...

   5. any necessary additional OIDC Scopes, depending on the information required about the user.

   6. client_id: Client ID associated with the Application created in the Travel0 Auth0 Tenant for Hoekstra & Associates' instance of Travel0 Corporate Booking.

   7. organization: Auth0 Organization to use. Where the organization is known ahead of time, a request to /authorize can include this parameter, which is specified in the form organization=organization_id, where organization_id is set to the identifier associated with the corresponding Auth0 Organization definition in your Auth0 Tenant. Alternatively, you can omit the organization parameter from the call to /authorize and configure your Auth0 Tenant to prompt the user to select the appropriate organization as part of first-factor authentication. For more information, see Define Organization Behavior.

      If the organization parameter is included on a call to the /authorize endpoint, then this should be used consistently for the duration of any session with Auth0. The Organizations feature does not associate any selected organization with the Auth0 SSO session, so omitting the parameter will always prompt the user to select the desire organization.

3. The Travel0 Auth0 Tenant redirects to /login to collect credentials from the user. If Jennifer already has a Database session with Hoekstra & Associates, then steps 3a and 4 will be skipped. For more information, see Single Sign-On.

   1. The Universal Login Page, which you can configure to include organization-specific brand collateral as described in Branding, is displayed.

4. The user enters their credentials and clicks login.

5. The Travel0 Auth0 Tenant checks the credentials for the user; if valid, the Rules pipeline executes. Rules can be used to handle access control as described in Authorization. If credentials for the user are invalid, then the user will be prompted to re-enter them.

   Automatic membership assignment will be performed if this option has been specified. For more information, see Grant Just-In-Time Membership to an Organization Connection. For manually-assigned Membership, validation will fail if the user is not already assigned as a member of the Organization.

6. Upon successful first-factor authentication and Rules execution, the user is redirected to the redirect_uri (https://hoekstra.corp.travel0.net/login/callback) with the state passed in step 2, as well as a code.

7. Hoekstra & Associates' instance of Travel0 Corporate Booking validates the state and then calls the Travel0 Auth0 Tenant at https://auth.travel0.net/oauth/token, passing the code and its client id and client secret in exchange for the ID Token. The ID Token is then used to generate a session for https://hoekstra.corp.travel0.net.

8. Hoekstra & Associates' instance of Travel0 Corporate Booking instance displays the appropriate page to the user.

Authenticating via an Enterprise Connection follows a very similar process. Using our MetaHexa Bank example, let's see how this Authentication implementation might flow with a user authenticated via the Enterprise Connection to MetaHexa Bank; again, most of the workflow described will typically be handled by using the relevant Auth0 SDK or library associated with your technology stack

1. Amintha from MetaHexa Bank opens her browser and navigates to MetaHexa Bank's instance of Travel0 Corporate Booking.

   1. If Amintha already has a session cookie with MetaHexa Bank's instance of Travel0 Corporate Booking, then she will typically be logged in to the system, and we will exit here. For more information, see Single Sign-On.

2. MetaHexa Bank's instance of Travel0 Corporate Booking redirects to the Travel0 Auth0 Tenant using Authorization Code Flow (with or without PKCE) by calling the /authorize endpoint and passing parameters, typically via use of an Auth0 SDK or third-party library:

   1. redirect_uri: https://metahexa.corp.travel0.net/login/callback

   2. response_type: code

   3. state: Unique state generated in this session

   4. scope: openid profile ...

   5. any necessary additional OIDC Scopes, depending on the information required about the user.

   6. client_id: Client ID associated with the Application created in the Travel0 Auth0 Tenant for MetaHexa Bank's instance of Travel0 Corporate Booking.

   7. organization: Auth0 Organization to use. Where the organization is known ahead of time, a request to /authorize can include this parameter, which is specified in the form organization=organization_id, where organization_id is set to the identifier associated with the corresponding Auth0 Organization definition in your Auth0 Tenant. Alternatively, you can omit the organization parameter from the call to /authorize and configure your Auth0 Tenant to prompt the user to select the appropriate organization as part of first-factor authentication. For more information, see Define Organization Behavior.

      If the organization parameter is included on a call to the /authorize endpoint, then this should be used consistently for the duration of any session with Auth0. The Organizations feature does not associate any selected organization with the Auth0 SSO session, so omitting the parameter will always prompt the user to select the desire organization.

   8. connection: Name of the configured Auth0 Enterprise Connection for MetaHexa Bank.

      Best Practice

      Always supply the connection parameter. When not provided, the user is prompted to select the Enterprise Connection associated with the upstream Identity Provider (IdP), which is an extra step from a UX perspective.

3. The Travel Auth0 Tenant redirects to the MetaHexa IdP to authenticate first-factor credentials.

   1. The login page is displayed, and the user enters credentials. If Amintha already has a session with the MetaHexa IdP, then steps 3a and 4 will be skipped. For more information, see Single Sign-On (SSO).

4. The user enters their credentials and clicks login.

5. Upon successful first-factor authentication, the Rules pipeline executes. Rules can be used to handle access control as described in Authorization. If credentials for the user are invalid, then the user will be prompted to re-enter them.

Steps 6 through 8 will match those described in the Database Connection scenario, but where Amintha is the user instead of Jennifer, and where MetaHexa Bank (metahexa.corp.travel0.net) will be used in place of Hoekstra & Associates.

Authentication via Social Connection follows a similar pattern to that associated with an Enterprise Connection, but where the upstream IdP is associated with the social provider rather than any specific organization.

With Social Connections, user isolation cannot be modeled consistently on a per-organization basis. Although it may be tempting to model user isolation by creating multiple connections to a social provider, such as by using Custom Social Connections, you should refrain from doing so; such a strategy can result in the same user ID being created in multiple connection definitions, which will invariably lead to problems down the line.