Manage Self-Service SSO

Self-Service Single Sign-On (SSO) provides business-to-business (B2B) customers with the tools needed to delegate SSO setup to their enterprise customers.

Self-Service SSO requires minimal configuration in your Auth0 tenant and provides your customers with a self-service assistant that guides them through the enablement process. After a customer completes their setup, the SSO integration is automatically added to your tenant as an Enterprise connection.

Self-Service SSO is only available to B2B customers on Professional or Enterprise plans.

Users with the following Dashboard roles can engage with this feature:

• Admin and Editor - Connections users can create and manage self-service profiles.
• Viewer - Config users can view self-service profiles only.

To facilitate Self-Service SSO, you will configure the following components using either the Management API or the Auth0 Dashboard:

• Self-service profile: Defines key elements of customer SSO implementations, including the identity providers (IdPs) they can use and which user attributes they must capture, such as email. You can create up to 20 profiles in your tenant for different customers or segments.
• Self-service access ticket: Grants customer admins access to the self-service assistant and sets specific details for their resulting Enterprise connection. Access tickets allow customer admins to either create new or modify existing connections.

The sections below provide expanded steps for configuring self-service profiles and generating self-service access tickets to share with customer admins.

Create self-service profiles

You can create self-service profiles using the Auth0 Dashboard or the Management API.

Self-service profiles are used to determine key elements of customer implementations, including:

• Which identity providers customer admins can use for SSO.
• Which user attributes they must capture through SSO, such as email or family name.
• Branding options that customize the look and feel of the self-service assistant.

You can create up to 20 profiles as needed to accommodate different customers or segments.

Auth0 Dashboard

To create a self-service profile on the Auth0 Dashboard:

1. Navigate to Authentication > Enterprise and open the Self-Service SSO section. Then, select Create Profile.

2. In the space provided, enter a name and optional description for the profile. Then, select Create.

3. On the Settings tab, complete the sections below. Then, select Save.

   • Identity Providers: Enable one or more identity providers. In the self-service assistant, customer admins can select their preferred option from the list of enabled providers.
   • Branding: Provide a logo and primary color for the self-service assistant.
   • Custom Introduction: Modify or replace the default message as needed. This introduction text displays to customer admins on the landing page of the self-service assistant. Your messaging can include basic formatting options, such as bolding or hyperlinks, and is limited to 2000 characters.

4. On the User Profile tab, add up to 20 user attributes that your customers should capture through SSO, such as email or family name. You can set each attribute as required or optional.

   • During the self-service assistant flow, customer admins will be prompted to map these defined user attributes to their identity provider to ensure the necessary values are passed to Auth0.

Manage self-service access tickets

After creating at least one self-service profile, you can generate self-service access tickets using either the Auth0 Dashboard or the Management API.

Self-service access tickets serve two primary purposes:

• Granting customer admins access to the self-service assistant where they can configure a new SSO connection or modify an existing connection.
• Predefining key details and behaviors of new SSO connections your customer admins will configure, such as which applications or organizations will be enabled for the new connection.

When generating access tickets, you can also enable certain features such as SAML IdP-initated SSO, home realm discovery, and domain verification.

SAML IdP-initiated SSO

SAML IdP-initiated SSO is a style of implementation that allows identity providers to initiate SSO and redirect users to the service provider for authentication.

When enabling this option for Self-Service SSO, you must provide your default application and response protocol. You can also provide an optional query string to further customize the connection’s behavior.

To learn more about these options, review Configure SAML Identity Provider-Initiated Single Sign-On.

Domain verification and home realm discovery

Self-service SSO supports two methods for ensuring customer admins associate verified domains with their connections: domain verification and home realm discovery.

While home realm discovery remains an available option, you can now use domain verification to allow your customers to manage this process themselves, reducing administrative overhead. Domain verification is currently available in Early Access.

Home realm discovery

Home realm discovery allows you to enter a list of known email domains for your customer. Domains specified in this list are automatically considered verified, and the customer admin does not need to complete manual verification.

You can provide a list of domains when generating self-service access tickets for your customer admins through either the Auth0 Dashboard or the Management API.

• Auth0 Dashboard: On the Generate Ticket page, use the Home Realm Discovery field to specify your list of domains.
• Management API: Use domain_aliases to specify your list of domains.

You can only specify domains for home realm discovery when generating access tickets for new connections; you cannot provide this information when using an access ticket to update an existing connection.

Domain verification

Domain verification is a tool for confirming your customers’ authenticity and ensuring they provide legitimate domains when setting up SSO. When enabled, customer admins are prompted to manually verify their domains through the self-service assistant. This feature is currently available in Early Access.

You can enable domain verification when generating self-service access tickets through either the Auth0 Dashboard or the Management API:

• Auth0 Dashboard: On the Generate Ticket page, use the Domain Verification field to set your level of requirement.
• Management API: Use domain_aliases_config.domain_verification to set your level of requirement.

Domain verification supports 3 levels of requirement:

• Off: When set to Off (or none via the API), the self-service assistant does not prompt a customer admin to verify their domain. Off is the default option for access tickets.

• Optional: When set to Optional, the self-service assistant prompts the customer admin to verify their domain. The customer admin can choose to either enter their domain for verification or skip the step. In both cases, the customer admin can continue the setup process and enable their connection regardless of its verification status.

• Required: When set to Required, the self-service assistant prompts the customer admin to verify their domains. In this case, the customer admin cannot skip this step and must complete domain verification in order to enable their connection.

  • In some cases, verification may take 24-48 hours to complete. If this occurs, you will need to generate a new access ticket that allows customer admins to modify their SSO connection, as access tickets expire five hours after they are first opened. For more information, review Generate an access ticket for existing connections.

You can enable domain verification when generating access tickets for both new and existing connections.

Generate access tickets for new connections

You can generate access tickets for new connections through either the Auth0 Dashboard or the Management API.

By default, access ticket URLs remain valid for five days after generation. After accessing the ticket URL, the customer admin has five hours to complete their setup. An access ticket URL can be accessed a maximum of 10 times; once this limit is reached, a new access ticket must be requested.

If needed, you can revoke an access ticket prior to its expiration to immediately cease access to the self-service assistant.

Auth0 Dashboard

To generate an access ticket through the Auth0 Dashboard:

1. Navigate to Authentication > Enterprise and access the Self-Service SSO section. Then, select the self-service profile with which you want to create an access ticket.

2. Select Generate Ticket to open the ticket form. Under Select ticket type, choose Create a new connection.

3. Under Ticket configuration, provide a required name for the connection your customer admin will configure.

4. In the Settings section, configure additional options as needed for the new connection:

   • Display Name: A user-friendly name for the connection that displays on Universal Login prompts.
   • Enabled Clients: A comma-separated list of client IDs to associate with the connection.
   • Enabled Organizations: A comma-separated list of organization IDs to associate with the connection.
   • Display connection a as button: Displays the connection as an authentication option on the login screen.
   • Display connection as a button for organizations: Displays the connection as an authentication option on the login screen for the specified organizations.
   • Assign membership on login for organizations: Automatically grant organization membership to users who authenticate with the connection.
   • Enable as a domain level connection: Allow 3rd-party applications to use the connection; requires Dynamic Client Registration.
   • Accept SAML IdP-initiated SSO: Enables SAML Identity Provider-initiated SSO.

5. Under Home Realm Discovery, optionally provide a comma-separated list of IdP domains to compare to users’ email domains. For customers to use Home Realm Discovery, you must set Domain Verification to either Optional or Required. For more information, review Home Realm Discovery.

6. Under Time to Live, set an expiration period for the access ticket in seconds. By default, time to live is set to 432000 seconds (which equals five days).

   • Time to Live determines how long an access ticket URL is active before a customer admin launches the self-service assistant. It does not determine how long the customer admin has access to the assistant after it’s been launched. The expiration of the self-service assistant itself is 5 hours and cannot be configured.

7. Under Domain Verification, choose your desired level of verification:

   • Off: When set to Off, customer admins are not prompted to verify their domain when setting up SSO. This option is selected by default for new access tickets.
   • Optional: When set to Optional, customer admins are prompted to verify their domain when setting up SSO. However, they can skip this step and enable their connection without completing verification.
   • Required: When set to Required, customer admins must verify their domain when setting up SSO. They will not be able to enable their connection until verification is complete.

8. Under Metadata, add up to 10 metadata associated with the connection.

9. Review your access ticket configuration for accuracy. Then, select Create Ticket.

A Ticket Information popup containing the access ticket URL then displays. Copy and save this URL somewhere safe, as you cannot retrieve this URL again after closing the popup.

You can share the access ticket URL with your customer admin through email, chat, or another communication channel to grant them access to the self-service assistant. The assistant will then guide them through configuring the SSO connection. To learn more about that experience, review Self-service assistant experience.

Generate access tickets for existing connections

You can generate access tickets for existing connections through either the Auth0 Dashboard or the Management API.

By default, access ticket URLs remain valid for five days after generation. After accessing the ticket URL, the customer admin has five hours to complete their setup. An access ticket URL can be accessed a maximum of 10 times; once this limit is reached, a new access ticket must be requested.

If needed, you can revoke an access ticket prior to its expiration to immediately cease access to the self-service assistant.

If a customer admin initiates domain verification through the self-service assistant, they may require an additional access ticket to complete the setup process.

Domain verification occurs as the final step of the self-service assistant. At this point in the workflow, the connection has been created but not enabled. If domain verification is required, the customer admin cannot enable their connection until verification is complete.

While verification typically occurs in a timely manner, it may take 24-48 hours in some cases. If this occurs, the customer admin will not be able to use their original access ticket to enable their connection, as tickets expire five hours after they are first accessed.

To complete this process, you can generate an access ticket that allows the customer admin to modify the connection they configured with their initial ticket. When creating this ticket, ensure you specify the Connection ID of the connection they configured with their first access ticket.

Auth0 Dashboard

To generate an access ticket through the Auth0 Dashboard:

1. Navigate to Authentication > Enterprise and access the Self-Service SSO section. Then, select the self-service profile with which you want to create an access ticket.

2. Select Generate Ticket to open the ticket form. Under Select ticket type, choose Edit an existing connection.

3. Under Ticket configuration, provide the ID of the existing connection you want the customer admin to modify.

4. Under Domain Verification, choose your desired level of verification:

   1. Off: Customer admins are not prompted to verify their domain when setting up SSO. This option is selected by default for new access tickets.
   2. Optional: Customer admins are prompted to verify their domain when setting up SSO. However, they can skip this step and enable their connection without completing verification.
   3. Required: Customer admins must verify their domain when setting up SSO. They will not be able to enable their connection until verification is complete.

5. Under Time to Live, set an expiration period for the access ticket in seconds. By default, time to live is set to 432000 seconds (which equals five days).

   1. Time to Live determines how long an access ticket URL is active before a customer admin launches the self-service assistant. It does not determine how long the customer admin has access to the assistant after it’s been launched. The expiration of the self-service assistant itself is 5 hours and cannot be configured.

6. Review your access ticket configuration for accuracy. Then, select Create Ticket.

A Ticket Information popup containing the access ticket URL then displays. Copy and save this URL somewhere safe as you cannot retrieve this URL again after closing the popup.

You can share the access ticket URL with your customer admin through email, chat, or another communication channel to grant them access to the self-service assistant. The assistant will then guide them through configuring the SSO connection. To learn more about that experience, review Self-service assistant experience.

Revoke an access ticket

By default, an access ticket URL remains valid for five days. Upon accessing the URL, a customer admin has five hours to complete their setup.

If needed, you can revoke an access ticket prior to its expiration. For example, if an access ticket is shared with the wrong audience, you can revoke the ticket to prevent unauthorized access to the self-service assistant.

When you revoke an access ticket, its URL immediately becomes invalid, and any associated sessions are terminated. Customer admins with the URL will no longer be able to access the self-service assistant. You can then generate and share new access tickets as needed.

To revoke an access ticket:

1. Retrieve the ID of the self-service profile associated with the access ticket using the Retrieve Self-Service Profiles endpoint.
2. Locate the ID of the access ticket you wish to revoke. IDs can be found at the end of the access ticket URL.
3. Call the Revoke SSO Access Ticket endpoint using the appropriate IDs:

POST  /api/v2/self-service-profiles/{id}/sso-ticket/{id}/revoke

In response, a 202 Accepted is returned.

References

APIs

To manage Self-Service SSO, the following Management API endpoints are available:

• Get self-service profiles
• Create a self-service profile
• Get a self-service profile by ID
• Delete a self-service profile by ID
• Update a self-service profile
• Get custom text for a self-service profile
• Set custom text for a self-service profile
• Create an SSO-access ticket to initiate the self-service SSO flow
• Revoke an SSO access ticket

Rate Limits

When using Self-Service SSO, the following rate limits apply:

Description	Endpoint	Limits
Manage SSO profiles	/api/v2/self-service-profiles	Review the Management API rate limits for your subscription type.
Create an access ticket	/api/v2/self-service-profiles//sso-ticket	Review the Management API rate limits for your subscription type.
Consume an access ticket	/self-service/connection-flows?ticket=	6 / min / IP
Load the webapp (including setup assistant) and webapp endpoints	/self-service/*	50 / min / IP 90 / min / tenant