Manage Self-Service SSO

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.

To create a self-service profile, first call the Self-Service Profiles endpoint to create the profile. Then, use a PUT call to optionally modify its introduction text.

Create a self-service profile:

1. Make a POST call to the Self-Service Profiles endpoint.

2. Specify the following parameters in the request body, as needed:

Example Request Body

{
  "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"
     }
  }
}

Customize your introduction text

When a customer admin accesses the self-service assistant, they first land on an introduction page that welcomes them to the experience. By default, the following message is provided:

"You are a few simple steps away from setting up SSO. This setup process involves making some changes to your identity provider. Before you begin, open your identity provider in a separate browser tab or window."

You can modify this text by making a PUT call to the Custom Text for Self-Service Profiles endpoint.

1. Call PUT /api/v2/self-service-profiles/{id}/custom-text/{language}/{page}, where

   • id is the profile ID of the self-service profile

   • language is set to en

   • page is set to get-started

2. In the request body, specify the following:

   Property

   Description

   introduction

   String. Maximum length is 2000. Full introduction text to display on the landing page of the self-service assistant. Text can include basic formatting options, such as bolding or hyperlinks. Custom text provided through this parameter completely overwrites any previous messaging. For best results, ensure you provide the full message you wish to display to customer admins. Sending an empty body {} resets any customized messaging to the default text.

3. In response, the created entity is returned.

Example Call

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>." 
}

Example Response

{
  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>." 
}

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.

To generate an access ticket through the Management API.

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"
         ],
         "idpinitiated": { 
            "enabled": true, 
            "client_id": "string", 
            "client_protocol": "string", 
            "client_authorizequery": "string" 
        }
      }
   },
   "enabled_clients":[
      "string"
   ],
   "enabled_organizations":[
      {
         "organization_id":"string",
         "assign_membership_on_login":true,
         "show_as_button":true
      }
   ],
   "ttl_sec":0,
   "domain_aliases_config": {
       "domain_verification": "string"
    }
}

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

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.

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.

To generate an access ticket through the Management API, follow the steps below.

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 following parameters:

Example Request Body

{
  "connection_id": "string",
   "ttl_sec":0,
   "domain_aliases_config": {
       "domain_verification": "string"
    }
}

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

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.