Single Identity Provider: Provisioning

By using the Auth0 Organizations feature, a single Auth0 Tenant can be provisioned for deployment to a production environment. For all but the most complex architectural scenarios, provisioning of a single Auth0 Tenant for use in a production environment is recommended because it provides ease of integration/use for Single Sign-On (SSO), user Profile Management, and so on. Depending on the implementation, you will need to address some additional items concerning setup of your Auth0 Tenant and your corresponding integration.

Branding associated with an organization is extremely valuable because using brand collateral provides users with an environment that they know and trust. Using recognized brand collateral also increases user confidence that the information they provide (for example, credentials) will be handled safely and securely. Default out-of-box Auth0 branding should therefore be replaced. To learn more, see Branding.

You should create an independent Auth0 Organization for each of the organizations you will support. In this case, we’ll create the hoekstra organization to represent Hoekstra & Associates in our example, and the metahexa organization to represent MetaHexa Bank. You can create organizations either manually via the Auth0 Dashboard or programmatically via the use of the Auth0 Management API.

Depending on how your Organization Tenant implementation is designed, you have different options when creating Application definitions within your Auth0 Tenant. Whichever option you choose, the Organization behavior is defined at the application level.

If you provision a separate Organization Tenant for each of your customers, then you will typically need an independent Application definition in Auth0 for each. This arrangement will also usually involve sending both the Application-specific client_id parameter and the organization parameter, which identifies which Auth0 Organization to use, as part of the call to the /authorize endpoint. To learn more, see Authentication.

Alternatively, the use of a single Application definition in Auth0 is supported. In this case, the user will be prompted to specify the required organization as part of first-factor authentication. This will typically require the use of a common Application client_id, but the organization parameter will be omitted on the call to the /authorize endpoint.

Next, define the Connections that will be used to authenticate users. In this case, we’ll define a Database Connection for users associated with Hoekstra & Associates and an Enterprise Connection for users associated with MetaHexa Bank.

Once the Connection has been defined, it can be provisioned to the appropriate Auth0 Organization using either the Auth0 Dashboard or Auth0 Management API. For more information, see Enable Organization Connections.

For users that are authenticated via Connections other than Database or Custom Database Connections, the user is provisioned to the external Identity Provider (IdP) independent of Auth0 and in the normal way. On the other hand, users that are authenticated via Database or Custom Database Connections can be provisioned in a number of different ways. The Auth0 Dashboard and Auth0 Management API can be used to create a user directly in your Auth0 Tenant. We also support Automatic Migration and Bulk Migration.

Users are then associated with an Auth0 Organization by assigning them memberships, and an Auth0 Organization can be configured to assign user Membership automatically or on a manual basis.

The Auth0 Organization feature also supports the use of Member Invitation. In the Member Invitation workflow, inviting a user to an application will result in the user being provisioned automatically and their user membership being generated automatically.

Using our Hoekstra & Associates example, let’s see how this implementation might flow where a Database Connection is used as part of user invitation; 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 receives an email sent from Travel0’s Auth0 Tenant on behalf of Hoekstra & Associates' instance of Travel0 Corporate Booking.

   1. The email was sent as described in Invite Organization Members and may have been triggered using either the Auth0 Dashboard or the Auth0 Management API.

2. Jennifer opens the email and clicks on its contained link. Doing so directs her browser to Hoekstra & Associates' instance of Travel0 Corporate Booking. The base URL used in the link is specified as the Application Login URI, which forms part of Hoekstra & Associates' instance of Travel0 Corporate Booking application definition in the Travel0 Auth0 Tenant. 

   1. The link contains organization and organization_name parameters. The organization parameter is set to the ID of the corresponding Auth0 Organization definition in your Auth0 Tenant. This will be forwarded to the Auth0 Tenant as part of step 3.

   2. The link also contains the invitation parameter, which will also be forwarded as part of step 3.

3. 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 similar to the following, 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: ID of the inviting organization typically obtained via the link in the email described in step 2. 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.

   8. invitation: Additional invitation parameter associated with the link in the email, as described in step 2.

4. The Travel0 Auth0 Tenant redirects to /signup/invitation to collect a password credential from the user.

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

      The invitation workflow associated with the Auth0 Organizations feature does not consider any SSO session held with Auth0. If a user is invited to sign up and they are already signed in, clicking the link in the email will always result in the display of the associated Universal Login Page.

5. The user enters their password (and any additional credentials, such as user name) and clicks continue. The user ID is set to the email address associated with the user and cannot be changed.

6. The Travel0 Auth0 Tenant checks credentials. If valid, the user is provisioned and Auth0 Organization Membership is set. The user is implicitly authenticated, and the Rules pipeline executes. Rules can be used to handle access control, as described in Authorization.

   1. If credentials for the user are invalid, then the user will be prompted to re-enter them.

7. Upon successful credential checking and Rules execution, the user is redirected to the redirect_uri (https://hoekstra.corp.travel0.net/login/callback) with the state passed in step 3, as well as a code.

8. 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.

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

Using our MetaHexa Bank example, let’s see how this implementation might flow where an Enterprise Connection is used as part of user invitation; 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 receives an email sent from Travel0’s Auth0 Tenant on behalf of MetaHexa Bank's instance of Travel0 Corporate Booking.

   1. The email was sent as described in Invite Organization Members and may have been triggered using either the Auth0 Dashboard or the Auth0 Management API.

2. Amintha opens the email and clicks on its contained link. Doing so directs her browser to MetaHexa Bank's instance of Travel0 Corporate Booking. The base URL used in the link is specified as the Application Login URI, which forms part of MetaHexa Bank's instance of Travel0 Corporate Booking application definition in the Travel0 Auth0 Tenant. 

   1. The link contains organization and organization_name parameters. The organization parameter is set to the ID of the corresponding Auth0 Organization definition in your Auth0 Tenant. This will be forwarded to the Auth0 Tenant as part of step 3.

   2. The link also contains the invitation parameter, which will also be forwarded as part of step 3.

3. 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 similar to the following, 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: ID of the inviting organization typically obtained via the link in the email described in step 2. 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.

   8. invitation: Additional invitation parameter associated with the link in the email, as described in step 2.

4. The Travel0 Auth0 Tenant redirects to /invitation, where Amintha is informed that she will be redirected to the MetaHexa IdP to authenticate first-factor credentials.

   1. The user confirms, and 

   2. Auth0 redirects to the MetaHexa Bank IdP instance, where

   3. The login page is displayed, and the user enters credentials and clicks login. 

5. If successful, the Auth0 Organization Membership is set, the user is implicitly authenticated, and the Rules pipeline executes. Rules can be used to handle access control as described in Authorization.

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.

Invitation via Social Connection follows a similar pattern to that associated with an Enterprise Connection, but the upstream IdP is associated with the social provider rather than any specific organization. For additional considerations with respect to using Social Connections, please see Authentication.