For the complete documentation index, see llms.txt. Markdown versions of all docs pages are available by appending .md to any docs URL.

Dynamically register OAuth clients in the portal frontend.

After you register an OAuth client, you receive a client ID and secret. No direct access to the backing OpenID Connect (OIDC) Identity Provider (IdP) is required. Use the client ID and secret to request an access token from the IdP and authenticate with your APIs.

The following restrictions apply:

• OAuth clients are connected to an app that is owned by a team.
• OAuth clients can be created by authorized Portal users only. Portal admins cannot create OAuth clients in the Portal frontend.
• After creating the OAuth client, a client ID and secret is shown to the user. The OAuth client secret value is shown only at creation time and can be retrieved only by an authorized user with access to the configured IdP.
• You use the OAuth client ID and secret to obtain a valid access token from your IdP. You obtain the access token outside of the portal frontend. The Portal admin must provide commands or tools to allow a user to generate an access token.
• Members of the team can delete OAuth clients.
• OAuth clients that are created via the frontend app are valid only if the Portal admin set up a corresponding AuthConfig that allows dynamic OAuth client registration for the selected API.
• You must have an approved subscription to access an API with a valid access token.

Before you begin

Portal admins must complete the following tasks:

1. Set up a portal web server.
2. Secure the login to the portal frontend.
3. Set up dynamic OAuth client registration via the portal frontend.
4. Approve any pending API subscriptions. Without a valid subscription, access to an API is not granted, even if you have a valid access token.

Portal users must complete the following tasks:

Create a team, an app, and a subscription to your app.

Register OAuth clients

1. In your browser, open the portal frontend app, such as http://portal.example.com:8080/ and log in as a Portal user.

2. From the menu bar, click Apps and find the app that you want to register an OAuth client for in the list of apps.

   

   

3. In the Authentication > OAuth Client section, click Create OAuth Client.

4. In the confirmation popup window, click Create an OAuth client.

   

   

5. When the client is created, copy both the Client ID and Client Secret that are shown. Note that the client secret is never stored in the backing database. Additionally, this secret is shown to you only once at creation time, so keep this secret to make future requests to the ApiProducts in the Portal.

   

   

6. Save the client ID and secret in OAUTH_CLIENT and OAUTH_SECRET environment variables.

   export OAUTH_CLIENT=<client_id>
   export OAUTH_SECRET=<client_secret>

7. Optional: Let your Portal admin know the client ID of the OAuth credentials that you created. The Portal admin can log in to the IdP and confirm that the client is created. The Portal admin can also view the client secret in the IdP, in case you forgot to copy or misplaced the secret.

Test access to APIs

1. Generate an access token by using the client ID and secret that you received from the portal, and save it in the ACCESS_TOKEN environment variable. Update the values in this command as needed for your own IdP details. You might need to ask your Portal admin to provide the command to request an access token from the IdP. The following example uses Keycloak.

   export ACCESS_TOKEN=$(curl -X POST -Ssm 10 --fail-with-body \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d "client_id=${OAUTH_CLIENT}" \
     -d "client_secret=${OAUTH_SECRET}" \
     -d "grant_type=client_credentials" \
     "$KEYCLOAK_URL/realms/portal/protocol/openid-connect/token" |
     jq -r .access_token)
   
   export ACCESS_TOKEN=${ACCESS_TOKEN}
   echo $ACCESS_TOKEN

2. Test access to your app by including the access token that you just created as part of the Authorization: Bearer <access_token> header. For example, this command sends a request to the httpbin sample app. Verify that you get back a 200 success status code.

   curl -vik ${INGRESS_GW_ADDRESS}:8080/httpbin/headers \
    -H "host: api.example.com" \
    -H "Authorization: Bearer $ACCESS_TOKEN"

   curl -vik localhost:8080/httpbin/headers \
    -H "host: api.example.com" \
    -H "Authorization: Bearer $ACCESS_TOKEN"

   Example output:

   HTTP/1.1 200 OK

Remove OAuth clients

1. In your browser, open the portal frontend app, such as http://portal.example.com:8080/ and log in as a Portal user.

2. In the frontend app, go to Apps.

3. Find the app that you created in the list of apps.

   

   

4. Click DETAILS.

5. In the Authentication > OAuth Client section, click Delete.

   

   

6. Optional: Let your Portal admin know that you deleted the OAuth client ID. The Portal admin can log in to the IdP and confirm that the client is deleted from the IdP.

Next