This guide outlines architecture and flows for an OAuth2 based connected app ecosystem using Auth0. This flow is useful when an app is installed by an individual user. This authentication flow described here is known as the client credentials flow. For more information about Auth0 machine-to-machine communication see: https://auth0.com/blog/using-m2m-authorization/.

In order to understand the flow we’ll guide you through the following steps:

  1. Register your API
  2. Create a new application
  3. Grant the application access to your user’s API data
  4. Revoke the application’s access to your user’s API data

Register your API

Before an application can be created it will need to access your API. In order to set up a new API with Auth0 follow the following steps:

  1. Log into Auth0 dashboard
  2. Create a new API by clicking APIs in the left navigation
  3. For the new API click the Permissions tab and add some permission scopes that apply to this API
  4. Create a new Application by clicking Applications in the left navigation. Choose the “Machine to Machine Applications” type. Then, select the API that you just created.
  5. Setup authorization and access controls for your API. See: https://auth0.com/docs/authorization.

For more information, please see: https://auth0.com/docs/get-started/set-up-apis.

Create a new application

Manual

A new application can be created manually for testing purposes. If you would like to create an app for testing purposes then please follow the instructions for creating machine-to-machine applications here: https://auth0.com/docs/applications/set-up-an-application/register-machine-to-machine-applications

Automated: Development API

Before an application is approved and the developer may need to test their application against your development or sandbox environment. The steps below describe how an app’s client credentials are set up for your development API.

  1. When receiving an appVersion.created event from OpenChannel, if the app.version value is 1 then call the Auth0 endpoint to create a new client using POST /api/v2/clients with body like:
  2. Note: If you set is_first_party to true then the user will not need to explicitly authorize access for the app in the User Application Consent step. Instead, the application will automatically become authorized after calling the GET /authorize endpoint.
  1. When receiving an appVersion.removed event from OpenChannel then call the OpenChannel API GET /v2/apps/versions?query={“appId”:”…the appId from the event”}&limit=1. If the value of “count” is 0 then delete the client from Auth0 using DELETE /api/v2/clients/{id}
  2. As part of the app creation/update form, display a required field “Webhook URL” that the developer can use to receive event notifications when users grant and revoke access to their application.
  3. Retrieve the client_id and client_secret for the app using the GET /api/v2/clients/{id} call. These are the app credentials. Show these credentials to the developer in the Partner Portal so that the developer can set up their app to communicate with your API.
  4. When receiving an appVersion.updated or appVersion.created event from OpenChannel, if isLatestVersion is true then check to see if name or logo_uri is different in OpenChannel (GET /apps/{appId}) vs Auth0 (GET /api/v2/clients/{id}) and update in Auth0 (PATCH /api/v2/clients/{id}) if it is.

Automated: Production API

After an application is approved, the developer will need to set up their application to connect to your production environment. The steps below describe how an app’s client credentials are set up for the production API.

When receiving an appVersion.created event from OpenChannel, if the app.version value is 1 then call the Auth0 endpoint to create a new client using POST /api/v2/clients with body like:

{
  "name": "... the name of the app",
  "is_first_party": false,
  "token_endpoint_auth_method": "client_secret_post",
  "app_type": "non_interactive",
  "grant_types": [
    "client_credentials"
  ]
}

Note: If you set is_first_party to true then the user will not need to explicitly authorize access for the app in the User Application Consent step. Instead, the application will automatically become authorized after calling the GET /authorize endpoint.

When receiving an appVersion.removed event from OpenChannel then call the OpenChannel API GET /v2/apps/versions?query={“appId”:”…the appId from the event”}&limit=1. If the value of “count” is 0 then delete the client using DELETE /api/v2/clients/{id}

As part of the app creation/update form, display a required field “Webhook URL” that the developer can use to receive event notifications when users grant and revoke access to their application.

Retrieve the client_id and client_secret for the app using the GET /api/v2/clients/{id} call. These are the app credentials. Show these credentials to the developer in the Partner Portal so that the developer can set up their app to communicate with your API.

When receiving an app.updated event from OpenChannel then check to see if name or logo_uri is different in OpenChannel (GET /apps/{appId}) vs Auth0 (GET /api/v2/clients/{id}) and update in Auth0 (PATCH /api/v2/clients/{id}) if it is.

Grant Application Access

When a user wants to install a third party app they must first provide consent to allow the app to access your API on behalf of the user. For more information see https://auth0.com/docs/authorization/user-consent-and-third-party-applications.

Call the following in order to produce the consent dialog

{
  "name": "... the name of the app",
  "is_first_party": false,
  "logo_uri": "... the URI of the app logo",
  "token_endpoint_auth_method": "client_secret_post",
  "app_type": "non_interactive",
  "grant_types": [
    "client_credentials"
  ]
}

Note: First-party applications can skip the consent dialog, but only if the API they are trying to access on behalf of the user has the Allow Skipping User Consent option enabled.

If access is rejected then #error=access_denied will be appended to the redirect URL

If access is accepted then call the OpenChannel POST /ownership/install API to mark the app as installed. The app now shows up in the user’s list of installed apps (GET /apps?isOwner=true).

Call the app’s Webhook URL to notify it that access has been granted for this user.

Revoke Application Access

When a user wants to uninstall a third party app, the app will also need to have it’s API access revoked. An app can be uninstalled and access revoked using the following steps:

Call the OpenChannel POST /ownership/uninstall/{ownershipId} endpoint.

When receiving an app.uninstalled event, call the Auth0 DELETE /api/v2/client-grants/{id} to revoke the app’s access

Call the app’s Webhook URL to notify it that access has been revoked for this user.