Express Configuration with Okta

The Okta Integration Network (OIN) is a catalog of SaaS applications for which Okta provides an express setup experience for enabling single sign-in with OpenID Connect, automated user provisioning with SCIM, and Universal Logout. Okta administrators use the Okta Admin Console to configure these integrations within their Okta tenant:

Express Configuration enables enterprise customers to securely configure identity integrations with SaaS applications without the need to copy and paste protocol-specific configuration values. Express Configuration provides these benefits to Okta administrators and SaaS application developers:

Reduces the time required to set up an application instance by automating the exchange of configuration information between Okta and Auth0.
Utilizes OAuth 2.0 consent flows for the secure and authorized sharing of sensitive configuration data, reducing potential errors related to credentials and configuration settings.
Simplifies and standardizes the integration deployment process. Automated workflow enables consistent and repeatable deployments of application integrations across multiple customers or environments, supporting a scalable application ecosystem with less opportunity for human error.
Eliminates the complexity of manual setup, enabling Okta customer admins to quickly add instances of Auth0-enabled OIN integrations.

How it works

The Express Configuration API allows Auth0 applications published to the OIN for customers to use Express Configuration on an Okta connection. Express Configuration supports OpenID Connect, SCIM, and Universal Logout within an Auth0 Organization. Review the Express Configuration workflow for an Auth0 app in the OIN:

express configuration workflow for an Auth0 app in the OIN.

An Okta administrator signs in to the Okta portal and selects the Express Configuration-enabled application from the OIN.
The Okta administrator navigates to the Sign On section and select Express Configure SSO & UL. This redirects them to an Auth0 Universal Login screen.

Okta administrator console > Sign On > Express Configuration

The Okta administrator enters the credentials of an application user who is permitted to perform Express Configuration. In Auth0, this refers to a user who is a member of an organization and is authorized to perform Express Configuration using an organizational role or other authorization method.

After authenticating, Auth0 prompts the Okta administrator for consent.

After consenting, Okta uses the Express Configuration API to automatically configure an Okta connection within the Auth0 organization to which the Okta administrator belongs.
The Okta administrator may then assign users to the application instance and see single sign-on working immediately.

Auth0 developers can also configure their OIN integration to allow Express Configuration of SCIM and Universal Logout, both of which are recommended:

When SCIM is enabled, Okta administrators can configure SCIM by navigating to the Provisioning section of the application details and selecting Express Configure SCIM.
When Universal Logout is enabled, it will be automatically configured as part of the OpenID Connect integration.

Prerequisites

To publish an application to the OIN with Express Configuration enabled, you must have the following:

An Okta Integrator Free Plan org, with access to either the Super Admin role or the App and Org Admin roles.
An Auth0 subscription that enables the use of the Okta connection type and the Organizations feature for as many customers as you need.
A SaaS application that has been integrated with Auth0 using a Multi-Organization Architecture.
- This includes registering your application as a Regular Web Application or Single-Page Application in Auth0, and enabling each of your customers to sign into that application using their own distinct identity providers.
An Auth0 Organization is deployed, or can be deployed, for each customer using Express Configuration. Organizations and organizational roles are used to authorize specific users to perform express configuration and create Okta connections only within the organizations to which they belong.
Your Auth0 tenant should have the Enable Application Connections tenant setting disabled.

Tip: To view a sample application that implements a multi-tenant architecture including Auth0 Organizations and organizational roles, refer to the SaaStart reference application.

Configure your application for Express Configuration

The Auth0 Dashboard guides an Auth0 developer through enabling Express Configuration for their application and publishing it to the OIN. An Auth0 Admin role in a production Auth0 tenant is required to complete the end-to-end setup and publishing process.

Configure the following Auth0 components to set up Express Configuration in your tenant:

A registered application with Initiate Login URI Template
A Connection Profile
A User Attribute Profile
Organization login settings
Administrator login and consent settings

Register your application as a Regular Web Application or Single-Page Application in Auth0 Dashboard.
Once registered, select the application you created and navigate to the Okta Integration Network tab to begin the Express Configuration setup wizard.
Select Get Started.
Review the Prerequisites and select Continue.
Register an Initiate Login URI Template. This template implements an endpoint on your application to automatically redirect end-users to Auth0’s /authorize endpoint for authentication. To review an example of a login endpoint, review the /login route in the Express SDK Quickstart.
- After Express Configuration initiates for an application instance, Okta uses the Initiate Login URI Template to launch the application from the end-user dashboard.
- (Optional) Set the organization_name, organization_id, and connection_name for Auth0’s /authorize endpoint to identify the organization or connection to use. Okta dynamically replaces these variables when the URL is launched from the end-user dashboard. Example: https://{organization_name}.your-app.com?connection={connection_name}.

Initiate Login URI Examples: https://your-app.com/login
https://your-app.com/login?connection={connection_name}
https://{organization_name}.your-app.com?connection={connection_name}

Connection Profile

In the Initiate Login URI Template, you have the option to add a Connection Profile. The Connection Profile (CP) enables Auth0 to specify how the private settings of your connections should be configured when created using Express Configuration, including settings that govern how the connection interacts with Auth0’s Universal Login and Organizations features:

Options for how the connection name should be created in Auth0
Options to use SCIM and/or Universal Logout with the connection (Recommended)
Options to allow end users of the connection to automatically become members of the consenting administrator’s organization
Options for the Show as button setting for the connection on Auth0’s Universal Login page

If you do not have a Connection Profile configured, Auth0 provides a default Connection Profile with common and recommended settings implemented for Express-configured connections.

To learn how to customize the default CP, read Connection Profile.

User Attribute Profile

In the Initiate Login URI Template, you have the option to add a User Attribute Profile. The User Attribute Profile (UAP) allows Auth0 developers to define, manage, and map user attributes consistently across the various protocols supported by Auth0. When used with Express Configuration, the User Attribute Profile allows developers to customize the OpenID Connect and SCIM attribute maps that will be written to the Okta connection generated by Express Configuration.

If you do not have a User Attribute Profile configured, Auth0 provides a default User Attribute Profile with common and recommended mappings for all protocols, including OpenID Connect and SCIM, which are used by the Okta connection type.

To learn how to customize the default UAP, read User Attribute Profile. Auth0 Organizations is required to authorize specific organizational users to create isolated connections but is not required to change your application’s existing login flow to support the organization-based login flow for business users.

If your application currently uses an Identifier-First login experience and home realm discovery with your applications, see the Enabling Home Realm Discovery section for information on how to enable home realm discovery.
If you wish to enable multiple applications in enabled_clients to be used with your Express Configuration connections, see Enabling Multiple Auth0 Applications Under a Single Integration.

If your application setup does not currently use an organization-based login flow, you can select the Enable this application for created connections setting. When enabled, each Express Configuration on an Okta connection is associated directly with your application. Use the required enabled_clients setting on the connection. When Express Configuration is enabled, Auth0 creates an additional client application ID that is used by the OIN during the administrator consent flow between Okta and Auth0. Okta creates one OIN client for each distinct application integration published to the OIN. Configure administrator login and consent settings in the application you want to publish to the OIN under Configure Integration Profile.

Navigate to Auth0 Dashboard > Applications.
Choose the application you want to publish to the OIN.
Select Okta Integration Network.
Verify you have the necessary prerequisites and select Continue.
In the Configure Integration Profile section, configure options in Admin Settings.

Admin Login Domain: Auth0 tenant domain Okta redirects to as part of the consent flow in a Web browser. Use the custom domain name if you have one configured in Auth0. To learn more, read Custom Domains.
Display Name of the OIN Express Configuration Application: Name of the OIN client application shown in the consent dialog.
Admin Login Flow: Defines the Organization login flow for the OIN client application and used when an Okta administrator runs Express Configuration from the Okta console. Select from:
- Prompt for Organization: Admins are first asked to select their Organization and are presented with the login experience for their Auth0 Organization. Admins can sign in using a pre-existing connection configured in that organization.
- Prompt for Credentials: Admins are first asked to provide their login credentials. When this option is selected, a button will appear that allows you to select the connections that contain the admin users. This can be a shared database connection, a passwordless email connection, or another connection that can be associated with all Auth0 Organizations.
Admin Role: In order to perform Express Configuration, the admin must be assigned the appropriate permissions. Read Assign express configuration permissions to users for instructions on how to authorize admins in the way that makes the most sense for your current Auth0 deployment.

For the best consent experience, set your tenant’s use_scope_descriptions_for_consent flag to true as described in Customize Consent Prompts. You will have the opportunity to view your consent prompt later in when you test and verify your integration.

Assign permissions to users

For Okta, administrators must have an application user account with required permissions to perform Express Configuration for an Auth0-powered SaaS application. For Auth0, any application user may be granted this permission, as long as the user is a member of an Auth0 Organization where the Express-configured connections is created, including:

A user in a dedicated database connection that has been created exclusively for a single Organization
A user in a shared database connection who is a member of one or more Organizations
A user with a passwordless email connection who is a member of one or more Organizations
A user in a social or existing enterprise connection who is a member of one or more Organizations

Once conditions are met, Auth0 provides flexible ways to asign Express Configuration permissions and allow developers to choose the method most appropriate for their curret Auth0 deployment:

Method	Recommended for…
Assign Express Configuration permissions to an existing user role	Customers wih existing application user role in their Auth0 tenant.
Assign a new role to application users requiring Express Configuration permissions as exemplified in the SaaStart reference application.	Customers who want to use Auth0’s role feature to grant Express Configuration permissions to individual users. This can be done withAuth0 Dashboard or the Management API.
Use a Post-Login Action to dynamically assign permissions using attribute-based access control	Customers not currently using Auth0’s role feature and prefer using a Post-Login Action to dynamically assign permissions based on user attributes instead of using the Auth0 Dashboard or making Management API calls to assign roles.

Assign permissions to a pre-existing application user role

Use this method of assigning Express Configuration permissions if you use Auth0’s RBAC feature for application roles and API permissions and already have one or more roles that represent an administrative user that would be assigned to an IT administrator deploying the application. Required API permissions:

Permission Name	API (Resource Server) Identifier
`express_configure:sso`	`urn:auth0:express-configure`
`express_configure:scim`	`urn:auth0:express-configure`

To learn more about assigning roles in Auth0 Dashboard and Management API, read Add permissions to roles.

Assign a new role to application users

Use this method of assigning Express Configuration permissions if you use Auth0’s RBAC feature for application roles and API permissions, but do not have a role that represents an administrative user, such as an IT administrator, who would be assigned to deploy the application. This method is also suitable for Auth0 developers who aren’t currently using Auth0’s RBAC feature but want to utilize it to gain granular control over which users are allowed access, using either the Auth0 Dashboard or the Management API.

Create a role

Use Auth0 Dashboard, Management API, or Auth0 CLI to create roles. This example uses Auth0 CLI:

auth0 roles create \
  --name "EXPRESS_CONFIGURE_ADMIN_ROLE" \
  --description "Administrator role for Express Configuration"

Assign permissions to the role

Assign the express_configuration:sso and express_configuration:scim permissions to the specified role. Replace $ROLE_ID with the role ID that you want to grant permission.

When using this method, you will need to update your customer onboarding process to assign this role to any new organizational users who require Express Configuration permissions.

auth0 roles permissions add "$ROLE_ID" \
  --api-id "urn:auth0:express-configure" \
  --permissions "express_configure:sso"

auth0 roles permissions add "$ROLE_ID" \
  --api-id "urn:auth0:express-configure" \
  --permissions "express_configure:scim"

To learn more on assigning roles to existing organization users, read Add member roles. Use this method of assigning Express Configuration permissions if you are using an Auth0 post-login Action to dynamically assign permissions based on user attributes instead of Role-Based Access Control (RBAC), Management API, or Auth0 Dashboard to assign user roles. This is appropriate for Auth0 customers who have deployed Auth0 using an attribute-based authorization model using custom permissions in Auth0 metadata. Example
The following example uses a post-login Action to assign permissions based on the value of an existing custom user attribute, user.app_metadata.is_admin.

/**
* Assigns Express Configuration permissions based on custom logic instead of role assignment
*/
exports.onExecutePostLogin = async (event, api) => {


 //check if request is for EC API access token
 if (event.resource_server && event.resource_server.identifier === "urn:auth0:express-configure") {


   //add permissions based on a custom condition
   if (event.user.app_metadata && event.user.app_metadata.is_admin === true) {
     api.accessToken.addScope("express_configure:sso");
     api.accessToken.addScope("express_configure:scim");
   }
   //else deny access if EC access token is requested
   else {
     api.access.deny('Access denied');
   }
 }
};

Enable home realm discovery

Before you run Express Configuration, you must collect and verify customer email addresses as part of the customer onboarding process to enable HRD.

You can use Express Configuration with Auth0 Actions if your application relies on Identifier-First login experience and uses home realm discovery (HRD) to match users with their identity providers (IdP) based on the email address. Email addresses should be stored in a location accessible by post-login Actions during the Express Configuration workflow, including:

One or more email domains can be stored in organization metadata on the customer’s Auth0 Organization.
Your post-login action can make an API call to retrieve verified domains from any system in your environment that stores them.

When the administrative user initiates express configuration in the Okta portal and authenticates, these actions add the email domains to the token that Okta receives, which it extracts and uses to set up the Okta connection with the correct HRD configuration. Example 1
In this example, verified domains are stored in connection metadata in the Auth0 Organization, which requires a comma-delimited string of one or more email domains stored in the organization metadata under a key named domains. Example values: test.com,test2.com

exports.onExecutePostLogin = async (event, api) => {
if (event.request.query.audience === "urn:auth0:express-configure") {
  if (event.organization && event.organization.metadata && event.organization.metadata.domains)
  {
    var domain_aliases = event.organization.metadata.domains.replace(/ /g,'').split(',');
    var express_configuration = {
      "domain_aliases": domain_aliases
     };
     api.accessToken.setCustomClaim("express_configuration", express_configuration);
  }
}
};

Example 2
In this example, the post-login Action makes an API call to retrieve verified domains from a storage system in your environment.

/**
*/
exports.onExecutePostLogin = async (event, api) => {
 if (event.request.query.audience === "urn:auth0:express-configure") {
    const axios = require("axios");
    // configure your custom API call here 
    const domains = await axios.get("https://example.org/endpoint");
     var express_configuration = {
     "domain_aliases": domains
      };
      api.accessToken.setCustomClaim("express_configuration", express_configuration);
  
 }
};

Enable multiple applications under a single integration

If you want end-users of a single Express Configuration on an Okta connection to access multiple applications in your tenant, you can set a linked_clients property on your registered web application. To modify this setting, use the Auth0 Management API to retrieve your registered web application. Replace {yourAppId} with the Client ID of your registered application, and {yourAccessToken} with a Management APIv2 access token. To learn how to get an access token to use the Management API, read Management API Access Tokens.

curl --request GET \
  --url 'https://{yourDomain}/api/v2/clients/{yourAppId}' \
  --header 'authorization: Bearer {yourAccessToken}'

Extract the express_configuration property from the response, add an array of additional application IDs to a linked_clients property, and update your registered web application:

curl --request PATCH \
  --url 'https://{yourDomain}/api/v2/clients/{yourAppId}' \
  --data '{"express_configuration": 
  {"admin_login_domain":"TENANT.auth0.com",
    "connection_profile_id":"cop_xxxxxxxxxxxxxxx",
    "enable_client":true,
    "enable_organization":true,
    "initiate_login_uri_template":"https://example.org",
    "okta_oin_client_id":"LDiGbUeiAYjRB5a4yOGfBvxxxxxxxxxxx",
    "user_attribute_profile_id":"uap_1ctMVQUg8jxxxxxxxxxxxx",   

     "linked_clients": [ 
        { "client_id": "KJM86F2susguvsasSeAsIxxxxxxxxxxx" }, 
	  { "client_id": "FIXwZCf5iUElvqy6eidlfxxxxxxxxxxx" }
      ] 
     }
  }' \
  --header 'cache-control: no-cache' \
  --header 'content-type: application/json' \
  --header 'authorization: Bearer {yourAccessToken}'

When Express Configuration is run, all of these application IDs in the linked_clients property will be added to the enabled_clients property of the Okta connection.

Publish your integration to the OIN

After you create a base configuration, you are ready to start the submission process to the OIN. As part of this process, you will be able to fully test Express Configuration end-to-end prior to going live:

Register your application in the OIN
Request an Express Configuration integration
Configure your OIN public key
Test and verify your Express Configuration integration
Finalize your OIN submission

Register your application in the OIN

To add Express Configuration to a new or pre-existing application in the OIN, you need:

An instance of your Auth0-enabled web application to use for testing
An Okta Integrator Free Plan org, with access to either the Super Admin role or the App and Org Admin roles.
- Your Okta Integrator Free Plan org must be configured as an Okta connection in your Auth0 tenant and enabled for use with your Auth0-enabled web application in order to complete basic tests
Google Chrome browser with the Okta Browser Plugin installed (review OIN Wizard requirements)

Sign in to your Okta Integrator Free Plan org with the user account you used to sign up with, or with an account that has been assigned the SUPER_ADMIN role, or the APP_ADMIN and ORG_ADMIN admin roles in Okta.
Navigate to Applications > Your OIN Integrations in the Admin Console.
If this is a new application, select Build new OIN integration. Otherwise, select your existing OIN Integration. The OIN Wizard appears:

Under Add integration capabilities, select OpenID Connect (OIDC) as the SSO protocol.
You may optionally select Universal Logout and SCIM 2.0, both of which are highly recommended for all Okta integrations and supported with Express Configuration.
Select Configure your integration.
Complete the OIN Catalog Properties section as desired. For reference, read OIN Catalog Properties.
Under OIDC Properties, set the following fields:
A. Redirect URIs should be the callback URI for your Auth0 tenant. This can use your tenant’s custom domain or your auth0.com domain.
Example: https://tenant.auth0.com/login/callback
B. (Optional) Set Initiate Login URI to the same value you configured for your application in Auth0, as described in Auth0 application and initiate login URI. Okta will use this URL to launch your application from the end-user dashboard.
Example: https://{organization_name}.your-app.com?connection={connection_name}
C. (Optional). Set Post-Logout URL to the sign-out redirect URIs for your app. This is the location where you want to send your end user after they sign out of your app. You can use integration variables if your sign-out URI varies per tenant.
D. Set Configuration guide URL to link to your customer-facing instructions on how to configure SSO between Okta and your app with Express Configuration. To learn more, read Customer configuration document guidelines.
If Universal Logout is selected, set the following fields under Universal logout properties:
A. Set Global token revocation endpoint to your Auth0 tenant name. This value will be dynamically replaced when Express Configuration runs.
B. Under Subject format, select issuer and Subject identifier.
C. Check Partial support if you do not use OIDC back-channel logout between Auth0 and your application but your application uses refresh tokens.
If SCIM 2.0 is selected, set the following fields under SCIM provisioning properties:
A. Set Base URL to your Auth0 tenant name. This value will be dynamically replaced when Express Configuration runs.
B. Under User Operations, select Create, Update, and Deactivate.
C. Set the link to your customer-facing instructions on how to configure SSO between Okta and your app with Express Configuration. Read Customer configuration document guidelines.
Select Get started with testing.
Proceed to the Request an express configuration integration section.

Request an Express Configuration integration

To enable Express Configuration capabilities for your registered OIN Integration, you send an email to the Okta Express Configuration team at expressconfig@okta.com with information copied from both the Okta and Auth0 portal. To request an express configuration integration:

Open your email application of choice and compose a new email.
Add the recipient: expressconfig@okta.com.
Add the subject: Express configuration integration request.
Navigate to the Auth0 Dashboard > Applications > Okta Integration Network > Request Integration section of Auth0 Dashboard and copy the following information into the email body.

Dashboard > Applications > OIN > Request Integrations

Add the name of your Okta Free Integrator Org, ex: trial-7513274, as well as the Okta Display name of your OIN Integration in the email.
Send the email.

After receiving the email, the Okta Express Configuration team enables Express Configuration for your registered OIN Integration and responds with a public key you need to upload to the Auth0 Dashboard.

Configure your OIN public key

After receiving the public key from the Okta Express Configuration team in the previous step, upload it to the Auth0 Dashboard > Applications > Okta Integration Network > Request Integration section of the Auth0 Dashboard. Select Save.

Test and verify your integration

After the public key is uploaded, you can test Express Configuration using your Okta Free Integrator organization:

Create an Auth0 Organization and username/password account you can share with the Okta OIN Operations team.
- Follow the instructions in the Example customer enablement flow to create an Auth0 Organization and username/password account for this purpose.
- If needed, perform additional work required in your application to allow the test Organization to log in, such as creating a new application tenant.
Once you create a test account, sign in to your Okta Integrator Free organization as a user with either the super admin (SUPER_ADMIN) role, or the app (APP_ADMIN) and organization (ORG_ADMIN) admin roles.
Navigate to Applications > Your OIN Integrations in the Okta admin console. Select the name of your OIN integration.
Choose Configure your integration. Then choose Get started with testing.
Set Account URL to the login page of your application. An Okta OIN operations engineer navigates to this URL and use the account credentials you provide in the subsequent fields to sign in to your app.
Set Username and Password to be the username and password of a test Organization administrator account you configured for testing Express Configuration.
Set Support Contact to be the email for Okta to contact your company about your integration. This email isn’t exposed in the OIN catalog or to your customers. It is only visible to the internal Okta team.
Under OIDC Tests, select No for Just-In Time Provisioning to skip this test, and set SP Initiate URL to the initiate login URL of your application instance.
Select Test your integration.
Select Generate Instance, then Done.
Navigate to the Sign On tab.
To test Express Configuration of Single Sign-On and Universal Logout and select Express Configure SSO & UL.
Once you are redirected to Auth0’s Universal Login page, sign in with your Organization admin account and consent to data sharing.
To test SCIM: select Provisioning, and then Express Configure SCIM. When redirected to Auth0’s Universal Login, continue through the consent prompt. Once complete, the SCIM integration is configured.
Next, select the Assignments tab and assign a user from your Okta Free Integrator organization for which you have credemtials. If a suitable user doesn’t exist, then follow instructions to Add users manually. If SCIM is enabled, the user should be provisioned to your Auth0 tenant. Confirm using the Auth0 Dashboard.
To test SSO: Use the user account you just assigned and the test instance. Log in with the user account credential.
To test Universal Logout: follow the instructions on Test Universal Logout.

Finalize your submission

Basic testing is complete with the previous section. To finalize your submission, your configuration must pass some automated tests:

On your application instance, select Begin Testing to finalize your submission.
Next to the name of the instance you just tested with Express Configuration, select Add to Tester.
To complete the automated SSO tests, select Run test for the IDP flow and/or SP flow tests. These tests require the Okta Browser Plugin. To learn more, read OIN Wizard Requirements.
A. Sign in with the Okta Free Integration Organization user you assigned to the application instance. The tests passes as soon as the plugin detects you are able to successfully sign in to your application. For more information on these tests, read Test your integration.
B. If you receive the error message invalid_request (no connections enabled for the client) during the login test, wait a few minutes and then try again. Newly-created connections can take a few minutes to work with features like HRD.
To complete the required Runscope testing for SCIM, follow the instructions on Test your SCIM API using Okta SCIM 2.0 Spec Tests.
A. For a second SCIM token, use the Authentication > Enterprise > Okta > [your-express-configred-connection] > Provisioning > Sync user profiles using SCIM > Setup section.
B. Once complete, enter the shareable Runscope test URL in the Link to Runscope spec test results and Link to Runscope CRUD test results fields in the OIN Wizard.
When complete, select Submit Integration.

Customer enablement

When your application publishes in the OIN, you can update your product documentation to indicate you support Express Configuration with Okta. Your product documentation should indicate the user roles or user types have permission to perform Express Configuration. If your application already utilizes Auth0 Organizations with Organization administrator roles as exemplified in the SaaStart reference application, you can add the Express Configuration permissions to that role. If you have not yet deployed Auth0 Organizations for your customers, or don’t implement administrative users in your application, refer to the example customer onboarding flow.

Example customer enablement flow

In your customer onboarding process, you should collect:

The name of the customer’s organization
Email address of the customer administator who should have permissions to perform Express Configuration
Verfied email domains the customer’s IdP issues for users, including the domains for the administrator

Collect this information manually or using the sign up or onboarding experience for your customers. Use the information to create an Auth0 Organization and admin user account for this customer:

Create an Auth0 Organization
Create the admin user account in an Auth0 connection, such as database or email passwordless.
Associate the connection with the Auth0 Organization. Disable Membership On Authentication.
Add the admin user account as a member of the Auth0 Organization.
Assign an organizational role to the admin user with permissions to perform Express Configuration.

Auth0 CLI example

Initialize Auth0 CLI and authenticate Authenticate with Auth0 with Auth0 CLI.

auth0 login --scopes "create:users,create:organizations,create:organization_members,create:organization_member_roles,create:organization_connections"

Create an Auth0 Organization Input the name of the Organization and a short name without spaces. If you collected multiple email suffixes, add them as Organizational metadata.

auth0 orgs create --json \
--display "organization_display_name" \
--name "organization_short_name" \
--metadata 'domains=["domain1.com", "domain2.com"]'

Collect the returned org_id. Create the Organization admin account In this example, you create a user in an email passwordless connection, requiring the email connection type. The command requires inputting the email address of the user you authorize to perform Express Configuration.

auth0 api users \
--data '{"email":"user@example.com","connection":"email", "email_verified":true}'

Tip

If you are creating this Organization to provide a username and password test account to the Okta OIN operations team, create the test account in either a shared or dedicated database connection:

auth0 api users \
--data '{"email":"user@example.com","connection":"db_connection_name_here", "password": "add_a_long_password_here"}'

Collect the returned user_id. Associate the connection with the Organization Retrieve the connection ID:

auth0 api get "connections" -q "name=connection_name_here"

Associate the connection ID with the Organization ID, org_id.

auth0 api post "organizations/org_id_here/enabled_connections" \
--data '{ "connection_id": "connection_id_here" };

Add the admin user as a member of the Organization You need the org_id and user_id.

auth0 api post "organizations/org_id_here/members" \
--data '{ "members": ["user_id__here"] }'

Assign the Organization role with Express Configuration permissions Retrieve the role ID with Express Configuration permissions as configured in Assign express configuration permissions to users.

auth0 api get "roles" -q "name_filter=role_name_here"

Assign the role ID to the user_id and org_id.

auth0 api post "organizations/org_id_here/members/user_id_here/roles" --data '{ "roles": ["role_id_here"] }'

Once complete, your customer can use the Organization administrator account to perform Express Configuration in their Okta organization with your OIN integration.

Provision admin accounts

Whether you are using existing user accounts or deploying new ones to enable Express Configuration, review the following best practices to ensure the non-federated admin account can be deprovisioned effectively when the administrative user leaves their organization.

Use work email

Whether the non-federated admin account is a database, passwordless email, or social user account, it is best to have the value of the email attribute match the user’s work email address that will be provisioned with their Okta Enterprise user account (example: john@mycompany.com). When using the passwordless email connection with work email addresses, the admin user will no longer be able to log in after they leave their organization. This provides a convenient way to grant access to new users without setting an extra password. When using a database or social accounts, requiring work email addresses will make it easier to prevent backdoor access using email 2FA.

Use multi-factor authentication

If an admin user is using a Database or Social connection to authenticate only a password, this may lead to backdoor access when the admin leaves their organization and their account is not deprovisioned in a timely manner. An additional layer of protection can be requiring email 2FA at each login. When the email address is the admin’s work email, they will no longer be able to authenticate after they leave their organization. After enabling the email factor in your Auth0 tenant and selecting the Customize MFA Factors using Actions option, you can prompt for email verification on each run of express configuration using a Post-Login action like the one below:

exports.onExecutePostLogin = async (event, api) => {


//check if request is for EC API access token
if (event.resource_server && event.resource_server.identifier === "urn:auth0:express-configure") {
    api.multifactor.enable('any');
    api.authentication.challengeWith({ type: 'email' });
 }
}

Limitations

Only one Auth0 tenant can be used in a single OIN integration. If the same application is deployed in multiple Auth0 regions, each region requires its own OIN integration
One OIN integration in one Okta organization can create one unique Okta connection in one corresponding Auth0 organization. Express configuration is not supported for more than one instance of an OIN application within an Okta organization
Each unique integration listed in the OIN creates an independent Okta connection. If you have multiple applications that require an Identifier-First login experience with home realm discovery, we recommend publishing multiple applications under a single integration.
When enabling multiple applications under a single integration, Okta only shows the main OIN application in its end-user dashboard.

Management API reference

To use Management API instead of Auth0 Dashboard to enable Express Configuration for a given application, use the examples below.

Create the Okta OIN Express Configuration System API

Registers the resource server which will be used to authenticate Organization Admins. This is only required if the dashboard was never used to set up Express Configuration for apps in a tenant.

POST /api/v2/resource-servers
{
    "name": "Okta OIN Express Configuration API",
    "identifier": "urn:auth0:express-configure"
  }

Endpoint reference

Create User Attribute Profile

Creates a User Attribute Profile. This step is only required if there are no existing profiles, or the developer wishes to use a custom profile. To start from a set of defaults for the User Attribute profile, call the GET /api/v2/user-attribute-profiles/templates endpoint first and use the response in the body of the call to create the User Attribute Profile. Example:

GET /api/v2/user-attribute-profiles/templates

Endpoint reference

POST /api/v2/user-attribute-profiles
{
    "name": "Okta OIN Express Configuration API",
    "identifier": "urn:auth0:express-configure"
}

Endpoint reference

Create Connection Profile

Create a Connection Profile. This step is only required if there are no existing profiles or the developer wants to use a custom profile. To start from a set of defaults for the Connection profile, call the GET /api/v2/connection-profiles/templates endpoint and use the response in the body of the call to create the Connection Profile.

GET /api/v2/connection-profiles/templates

Endpoint reference

POST /api/v2/connection-profile
{
    "name": "Okta OIN Express Configuration API",
    "identifier": "urn:auth0:express-configure"
}

Endpoint reference

Create OIN Express Configuration Client

Create the service application that Okta will use during Express Configuration for a given application. This client must be created with the properties shown in the example below. The organization_require_behavior attribute may be customized with one of the values below, which are also explained in Administrator login and consent settings.

pre_login_prompt: Prompts for the admin’s organization prior to prompting for credentials.
post_login_prompt: Prompts for the admin’s credentials. For this option, use the PATCH /api/v2/connections/{id} endpoint to add the Client ID of the OIN client to the enabled_clients property of the connection(s) containing the admin accounts.

Example:

POST /api/v2/clients
{
    "name": "Okta OIN Express Configuration",
    "app_type": "express_configuration",
    "organization_require_behavior": "pre_login_prompt",
    "client_authentication_methods": {
      "private_key_jwt": {
        "credentials": []
      }
    }
}

Endpoint reference

Configure SaaS Application Properties

Set the configuration values for the express_configuration property on the registered application that will be published to the OIN. Replace the values in the examples with a value connection profile ID, user attribute profile ID, OIN client application ID, initiate login URI, and Auth0 tenant domain to use for this integration. The enable_client attribute corresponds to the setting for enabled_clients described in Organization login settings. The enable_organization attribute should always be set to true, unless you want to disassociate created connections from their organizations. Example:

PATCH /api/v2/clients/{id}
{
  "express_configuration": {
      "admin_login_domain": "yourAuth0TenantDomain",
      "connection_profile_id": "yourConnectionProfileId",
      "enable_client": true,
      "enable_organization": true,
      "initiate_login_uri_template": "yourInitiateLoginUriTemplate",
      "okta_oin_client_id": "yourOinClientId",
      "user_attribute_profile_id": "yourConnectionProfileId"
    }
}

Endpoint reference

Upload Public Key

Upload the public key provided by the Okta team as a credential of the OIN client application. Example:

POST /api/v2/clients/{oin_client_id}/credentials
{
  "credential_type": "public_key",
  "pem": "-----BEGIN PUBLIC KEY-----\nMIGf..."
}

Endpoint reference

Assign keys to OIN client application

Assign the uploaded public keys from Okta to the OIN service client. Replace yourCredentialId with the credential ID received in the previous step. Example:

PATCH /api/v2/clients/{oin_client_id}
{
 "client_authentication_methods": {
    "private_key_jwt": {
      "credentials": [
        {
          "id": "yourCredentialId",
        }
      ]
    }
  }
}

Endpoint reference Update tenant settings to display the scope details on the consent page. These settings improve the user experience by providing information about the permissions being granted. This is not required but recommended. Example:

PATCH /api/v2/tenants/settings
{ 
  "flags": { "use_scope_descriptions_for_consent": true } 
}

Endpoint reference

Add Login

Provision Users

Express Configuration with Okta

How it works

Prerequisites

Configure your application for Express Configuration

Connection Profile

User Attribute Profile

Assign permissions to users

Assign permissions to a pre-existing application user role

Assign a new role to application users

Create a role

Assign permissions to the role

Enable home realm discovery

Enable multiple applications under a single integration

Publish your integration to the OIN

Register your application in the OIN

Request an Express Configuration integration

Configure your OIN public key

Test and verify your integration

Finalize your submission

Customer enablement

Example customer enablement flow

Auth0 CLI example

Tip

Provision admin accounts

Use work email

Use multi-factor authentication

Limitations

Management API reference

Create the Okta OIN Express Configuration System API

Create User Attribute Profile

Create Connection Profile

Create OIN Express Configuration Client

Configure SaaS Application Properties

Upload Public Key

Assign keys to OIN client application

Add Login

Provision Users

​How it works

​Prerequisites

​Configure your application for Express Configuration

​Register an application with Initiate Login URI Template

​Connection Profile

​User Attribute Profile

​Organization login settings

​Administrator login and consent settings

​Assign permissions to users

​Assign permissions to a pre-existing application user role

​Assign a new role to application users

​Create a role

​Assign permissions to the role

​Assign permissions based on user attributes using a post-login Action

​Enable home realm discovery

​Enable multiple applications under a single integration

​Publish your integration to the OIN

​Register your application in the OIN

​Request an Express Configuration integration

​Configure your OIN public key

​Test and verify your integration

​Finalize your submission

​Customer enablement

​Example customer enablement flow

​Auth0 CLI example

Tip

​Provision admin accounts

​Use work email

​Use multi-factor authentication

​Limitations

​Management API reference

​Create the Okta OIN Express Configuration System API

​Create User Attribute Profile

​Create Connection Profile

​Create OIN Express Configuration Client

​Configure SaaS Application Properties

​Upload Public Key

​Assign keys to OIN client application

​Customize your tenants consent prompt

How it works

Prerequisites

Configure your application for Express Configuration

Register an application with Initiate Login URI Template

Connection Profile

User Attribute Profile

Organization login settings

Administrator login and consent settings

Assign permissions to users

Assign permissions to a pre-existing application user role

Assign a new role to application users

Create a role

Assign permissions to the role

Assign permissions based on user attributes using a post-login Action

Enable home realm discovery

Enable multiple applications under a single integration

Publish your integration to the OIN

Register your application in the OIN

Request an Express Configuration integration

Configure your OIN public key

Test and verify your integration

Finalize your submission

Customer enablement

Example customer enablement flow

Auth0 CLI example

Provision admin accounts

Use work email

Use multi-factor authentication

Limitations

Management API reference

Create the Okta OIN Express Configuration System API

Create User Attribute Profile

Create Connection Profile

Create OIN Express Configuration Client

Configure SaaS Application Properties

Upload Public Key

Assign keys to OIN client application

Customize your tenants consent prompt