Self-Service Single Sign-On

Self-Service Single Sign-On (SSO) provides business-to-business (B2B) customers with the tools needed to delegate SSO setup to their enterprise customers. By delegating this task, you can streamline your onboarding process and grant customers more autonomy over their sign-on experience. You can also reduce the time and costs associated with managing SSO across your customer base. 

Self-Service SSO requires minimal configuration in your Auth0 tenant and provides your customers with a setup 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.

Supported Providers

Self-Service SSO currently supports the following identity providers:

• Okta Workforce Identity Cloud (using OIDC)

• Entra ID

• Google Workspace (using OIDC)

• Keycloak

• Microsoft Active Directory Federation Services (ADFS)

• PingFederate

• Generic OIDC

• Generic SAML

Self-Service SSO uses the following components to delegate setup to your customers:

• Self-service profile: Defines key elements of customer SSO implementations, such as the identity providers they can use for SSO and which user attributes they must capture, such as email.

• Self-service access ticket: Grants customer admins access to the SSO setup assistant and sets specific details for their resulting SSO integration.

• SSO setup assistant: Guides customer admins through the SSO setup process.

At a high level, the Self-Service SSO workflow includes the following tasks: 

1. You (the Auth0 customer) create a self-service profile in your tenant using the Auth0 Dashboard or the Management API. 

2. Using the Management API, you next create a self-service access ticket that allows customer admins to configure SSO. 

3. You retrieve the ticket URL from the asset created in Step 2 and send this link to your customer admin.

4. Your customer admin launches the SSO setup assistant and follows the steps provided to create an application with their identity provider. 

5. A new Enterprise connection pointing to the customer’s application is added to your Auth0 tenant.

Select the diagram for an expanded view.

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

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 SSO setup assistant.

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

{
  "name": "Example Profile",
  "description": "An example profile for all customers",
  "allowed_strategies": ["okta","adfs","google-apps"],
  "user_attributes": [
    {
      "name": "email",
      "description": "User's email",
      "is_optional": false,
    }
  ],
  "branding": {
     "logo_url": "https://example.com/logo.png",
     "colors": {
       "primary": "#334455"
     }
  }
}

PUT /api/v2/self-service-profiles/ssp_1234567890/custom-text/en/get-started

{
  introduction: "Welcome! With <b>only a few steps</b>, you'll be able to setup your new connection. For assistance, contact <a href="https://www.examplesupportsite.com"> our support team </a>." 
}

{
  introduction: "Welcome! With <b>only a few steps</b>, you'll be able to setup your new connection. For assistance, contact <a href="https://www.examplesupportsite.com"> our support team </a>." 
}

After creating at least one self-service profile, you can generate self-service access tickets using the Management API. Self-service access tickets serve two primary purposes:

• Granting customer admins access to the SSO setup assistant, through which 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.

To generate a self-service access ticket:

1. Retrieve the ID of the self-service profile you want to associate with the access ticket through the Retrieve Self-Service Profiles endpoint.

2. Call the SSO Access Ticket endpoint using the ID of the appropriate self-service profile:

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

In the request body, specify the parameters described in the table below.

Example Request Body

{
    "connection_config": {
        "name": "string",
        "display_name": "string",
        "is_domain_connection": true,
        "show_as_button": true,
        "metadata": {
            "key1": "value1",
            "key2": "value2"
        },
        "options": {
            "icon_url": "string",
            "domain_aliases": [
                "acme.corp",
                "okta.com"
            ]
        }
    },
    "enabled_clients": [
        "string"
    ],
    "enabled_organizations": [
        {
            "organization_id": "string",
            "assign_membership_on_login": true,
            "show_as_button": true
        }
    ],
    "ttl_sec": 0
}

In response, you receive a URL to the self-service access ticket:

{
  "ticket": "https://{domain}/self-service/connections-flow?ticket={id}"
}

After you receive the ticket URL, share the link with your customer admin to grant them access to the SSO setup assistant. The setup assistant will then guide them through configuring the SSO connection.

You can wrap access ticket generation in your own self-service portal or send ticket URLs directly to customer admins through email, chat, or other communication channels.

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 SSO setup assistant.

When an access ticket is revoked, its URL immediately becomes invalid, and any associated sessions are terminated. Customer admins with the URL will no longer be able to access the SSO setup assistant. A new access ticket can then be generated and shared 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.

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

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