Automatically create and manage Dev Portal applications in Auth0 with Dynamic Client Registration

To use dynamic client registration (DCR) with Auth0 as the identity provider (IdP), there are two important configurations to prepare in Auth0. First, you must authorize an Auth0 application so Konnect can use the Auth0 Management API on your behalf. Next, you will create an API audience that Konnect applications will be granted access to.

Konnect will use a client ID and secret from an Auth0 application that has been authorized to perform specific actions in the Auth0 Management API.

To get started configuring Auth0, log in to your Auth0 dashboard and complete the following:

1. From the sidebar, select Applications > Applications.

2. Click Create Application.

3. Give the application a memorable name, like “Konnect Portal DCR Admin”.

4. Select the application type Machine to Machine Applications and click create.

5. Authorize the application to access the Auth0 Management API by selecting it from the dropdown. Its URL will follow the pattern: https://AUTH0_TENANT_SUBDOMAIN.REGION.auth0.com/api/v2/.

6. In the Permissions section, select the following permissions to grant access, then click Authorize:
   • read:client_grants
   • create:client_grants
   • delete:client_grants
   • update:client_grants
   • read:clients
   • create:clients
   • delete:clients
   • update:clients
   • update:client_keys

   Note: If you’re using Developer Managed Scopes, add read:resource_servers to the permissions for your initial client application.

7. On the application’s Settings tab, locate the values for Client ID and Client Secret, then export them:

   export CLIENT_ID='YOUR-AUTH0-CLIENT-ID'
   export CLIENT_SECRET='YOUR-AUTH0-CLIENT-SECRET'

   Copied!

8. Under Settings > General, locate your tenant name and export the corresponding issuer URL:

   export ISSUER_URL='https://AUTH0_TENANT_NAME.us.auth0.com'

   Copied!

You can use an existing API entity if there is one already defined in Auth0 that represents the audience you are/will be serving with Konnect Dev Portal applications. In most cases, it is a good idea to create a new API that is specific to your Konnect Portal applications.

To create a new API audience in Auth0:

1. In the sidebar, navigate to Applications > APIs.

2. Click Create API.

3. Enter a Name, such as Konnect Portal Applications.

4. Set the Identifier to a value that represents the audience your API will serve.

5. Click Create.

6. Make a note of the Identifier value (also known as the Audience), then export it to your environment:

   export AUDIENCE='YOUR-AUTH0-API-IDENTIFIER'

   Copied!

After configuring Auth0, you can integrate it with the Dev Portal for Dynamic Client Registration (DCR). This process involves two main steps: first, creating the DCR provider, and second, establishing the authentication strategy. DCR providers are designed to be reusable configurations. This means once you’ve configured the Auth0 DCR provider, it can be used across multiple authentication strategies without needing to be set up again.

1. Create a DCR provider using the /v2/dcr-providers endpoint:

   curl -X POST "https://us.api.konghq.com/v2/dcr-providers" \
        --no-progress-meter --fail-with-body  \
        -H "Authorization: Bearer $KONNECT_TOKEN" \
        --json '{
          "name": "Auth0 DCR Provider",
          "provider_type": "auth0",
          "issuer": "'$ISSUER_URL'",
          "dcr_config": {
            "initial_client_id": "'$CLIENT_ID'",
            "initial_client_secret": "'$CLIENT_SECRET'"
          }
        }'

   Copied!

   Note: If you’re using a custom domain for Auth0, add initial_client_audience: "$AUDIENCE" to the dcr_config. If you’re using Developer Managed Scopes, add use_developer_managed_scopes: true to the dcr_config.

2. Export the DCR provider ID from the response:

   export DCR_PROVIDER_ID='YOUR-DCR-PROVIDER-ID'

   Copied!

3. Create an authentication strategy using the /v2/application-auth-strategies endpoint:

   curl -X POST "https://us.api.konghq.com/v2/application-auth-strategies" \
        --no-progress-meter --fail-with-body  \
        -H "Authorization: Bearer $KONNECT_TOKEN" \
        --json '{
          "name": "Auth0 DCR Auth Strategy",
          "display_name": "Auth0 DCR Auth Strategy",
          "strategy_type": "openid_connect",
          "configs": {
            "openid-connect": {
              "issuer": "'$ISSUER_URL'",
              "credential_claim": [
                "azp"
              ],
              "scopes": [
                "openid"
              ],
              "token_post_args_names": [
                "audience"
              ],
              "token_post_args_values": [
                "'$AUDIENCE'"
              ],
              "auth_methods": [
                "client_credentials",
                "bearer",
                "session"
              ]
            }
          },
          "dcr_provider_id": "'$DCR_PROVIDER_ID'"
        }'

   Copied!

   Note: The azp credential claim matches the client ID of each Auth0 application. Add any additional scopes your developers may need. If you’re using Developer Managed Scopes, these will be the scopes developers can select in the Dev Portal.

4. Export the auth strategy ID from the response:

   export AUTH_STRATEGY_ID='YOUR-AUTH-STRATEGY-ID'

   Copied!

Now that the application auth strategy is configured, you can apply it to an API using the /v3/apis/{apiId}/publications/{portalId} endpoint:

curl -X PUT "https://us.api.konghq.com/v3/apis/$API_ID/publications/$PORTAL_ID" \
     --no-progress-meter --fail-with-body  \
     -H "Authorization: Bearer $KONNECT_TOKEN" \
     --json '{
       "visibility": "public",
       "auth_strategy_ids": [
         "'$AUTH_STRATEGY_ID'"
       ]
     }'

Certificate verification depth: Kong Gateway verifies Auth0’s TLS certificate when it connects to the Auth0 issuer to validate tokens. Auth0 certificates issued by Let’s Encrypt present a certificate chain with multiple intermediate CAs, which is deeper than the default lua_ssl_verify_depth of 1. Combined with certificate verification being enabled by default in Kong Gateway 3.14 and later, this causes the TLS handshake to Auth0 to fail.

On self-managed data planes, where you control kong.conf, set lua_ssl_verify_depth high enough to cover Auth0’s chain. Auth0’s chain includes two intermediate CAs, so the value must be at least 2. Also ensure lua_ssl_trusted_certificate includes system so the root CA is trusted. After updating kong.conf, restart the data plane to apply the changes.

Now that DCR is configured, you can create an application with Dynamic Client Registration by using a developer account.

1. Navigate to your Dev Portal URL and log in with your developer account.

2. Select an API and click Use this API.

3. Complete the Create New Application modal with your application name, authentication strategy, and description.

4. After the application is created, the Client ID and Client Secret will be displayed.
   Make sure to store these values, as they will only be shown once.

5. After the application is created, it will appear in your IdP. From your IdP organization, select Applications from the sidebar. You will see the application created in the Dev Portal, along with its corresponding Client ID.

For developers to authorize requests, they must attach the client ID and secret pair obtained previously in the header. They can do this by using any API client, such as Insomnia, or directly using the command line:

curl "$KONNECT_PROXY_URL/$ROUTE_PATH" \
     --no-progress-meter --fail-with-body \
     -H "Authorization: Basic $CLIENT_ID:$CLIENT_SECRET" \
     -H "Content-Type: application/json"

Note: When using Auth0 DCR for Dev Portal, each application in Auth0 will have the following metadata. This can be viewed via the auth0 dashboard, or accessed from the Auth0 API.

• konnect_portal_id: ID of the Portal the application belongs to
• konnect_developer_id: ID of the developer in the Dev Portal that this application belongs to
• konnect_org_id: ID of the Konnect Organization the application belongs to
• konnect_application_id: ID of the application in the Dev Portal