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.

Best Practice

While numerous authentication workflows are supported within Auth0, workflows using Auth0 Universal Login are considered both industry and Auth0 best practice because they provide optimal functionality and security. In particular, Universal Login provides Single Sign On (SSO) out of the box and helps mitigate attacks such as phishing and bucket brigade; for this reason, it should be preferred wherever password credentials are supplied by a user. Crucially, the New Universal Login Experience is also the only mechanism supported when using the Auth0 Organizations feature.

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 New Universal Login Experience capability.

Auth0 supports only one authenticated user context per Auth0 Tenant; tenants cannot selectively switch between authenticated user contexts. Changing user context has an impact on any active SSO session, and this extends to the Auth0 Organizations feature. If per-organization contexts are absolutely necessary, then multiple Auth0 Tenants will need to be deployed to production. Because using multiple tenants has ramifications that affect Single Sign-On (SSO), user profile management, and so on, you should carefully consider before going down this route.

Database Connection

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:

Architecture Scenarios - MOA - Isolated Users, Shared Apps, Database Login Flow
  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.

Enterprise Connection

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

Architecture Scenarios - MOA - Isolated Users, Shared Apps, Enterprise Login Flow
  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.

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.

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.

Social Connection

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.

Auth0 Social Connections are defined at the Tenant level. Typically, only one Social Connection is configured per social provider per Auth0 Tenant, which represents a definition to the Auth0 Tenant overall. Thus, any consent provided by a user will apply across all Auth0 Organizations defined in an Auth0 Tenant and not to any one organization in particular.

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.