Use Confluent Security Token Service (STS) tokens with Confluent Cloud APIs

You can use the Confluent Security Token Service (Confluent STS) to provide trusted users or services with temporary security credentials that can access Confluent Cloud resources without requiring them to have a Confluent Cloud account. Use your external OAuth identity provider to authenticate users and generate Confluent Cloud access tokens, which are then used by the Confluent Security Token Service API to exchange Confluent STS access tokens that can access Confluent Cloud resources using the Confluent Cloud APIs.

Authenticate access to Confluent Cloud APIs using Confluent Security Token Service (STS) tokens

To authenticate users or services, exchange external access tokens for Confluent STS tokens, and access Confluent Cloud resources using Confluent Cloud APIs, follow the steps below.

Important

Ensure that your OAuth/OIDC identity provider and identity pools include the necessary scopes and permissions required to perform the desired actions on Confluent Cloud resources using the Confluent Cloud APIs.

Confluent STS validates users and services based on the scopes and permissions defined in the pool filter expressions associated with your identity pools. For details, see Use Identity Pools with Your OAuth/OIDC Identity Provider.

Confluent Cloud APIs that support Confluent STS access tokens

You can use Confluent STS tokens to authenticate to Confluent Cloud APIs that support the confluent-sts-access-token notation. If an API operation supports Confluent STS tokens, the AUTHORIZATIONS include confluent-sts-access-token.

For example, see List of Invitations.

Steps to authenticate access to Confluent Cloud APIs using Confluent STS tokens

Follow the steps below to authenticate access to Confluent Cloud APIs using Confluent STS tokens. After you exchange an external access token for a Confluent STS access token, you can use the Confluent STS access token to access Confluent Cloud APIs based on the permissions defined in the identity pool associated with the external access token.

Note: The examples included in the steps below use curl commands to make API requests, but you can use your automation tool of choice.

Step 1: Fetch an access token from your identity provider

Run the following curl command to fetch an external access token, substituting your values for the identity provider URL, the authorization header, and the scope (optional).

curl --request POST --url https://dev-531534.okta.com/oauth2/aus1z55evcaY3sQV74x7/v1/token \
  --header 'accept: application/json' \
  --header '<authorization-credentials>' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data 'grant_type=client_credentials&scope=<scope>'
  • <identity-provider-url>: The identity provider URL
  • <authorization-credentials>
    • Basic authorization: Include the Base64-encoded client ID and client secret of the identity provider (Basic <client-id>:<client-secret>).
    • Bearer authorization: Include the external access token (JWT) from the identity provider (Bearer <jwt-token>).
  • <scope>: (optional) The scope of the external access token.

Step 2: Exchange the external access token for a Confluent STS access token

Run the following curl command to exchange the external access token for a Confluent STS access token (JWT), substituting your values for the external access token (JWT) and the identity pool ID.

curl --request POST --url https://api.confluent.cloud/sts/v1/oauth2/token \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data grant_type=urn:ietf:params:oauth:grant-type:token-exchange \
  --data subject_token=<jwt-token> \
  --data identity_pool_id=<pool-id> \
  --data subject_token_type=urn:ietf:params:oauth:token-type:jwt \
  --data requested_token_type=urn:ietf:params:oauth:token-type:access_token \
  • <jwt-token>: The external access token (JWT) obtained from your identity provider.
  • <pool-id>: The identity pool ID. You can find the identity pool ID in the Confluent Cloud Console by clicking on the identity provider in the Accounts & access page at https://confluent.cloud/settings/org/identity_providers. You can also find the identity pool ID using the Confluent CLI command confluent iam provider describe (CLI reference).

For details and request samples, see Exchange an OAuth Token.

Step 3: Use the Confluent STS access token to access Confluent Cloud APIs

You can now use the Confluent STS access token (JWT) obtained from the Confluent Security Token Service API response to access the Confluent Cloud APIs. Add the Confluent STS access token as a bearer token in the Authorization header of subsequent API requests made to Confluent Cloud APIs. This token serves as proof of authentication and authorizes the user to access the requested resources.

For example, to list all invitations for the organization, you would run the following curl command, replacing <confluent-sts-access-token> with your Confluent STS access token.

curl -X GET 'https://api.confluent.cloud/iam/v2/invitations' \
  --header "Authorization: Bearer <confluent-sts-access-token>"

Verify that Confluent STS access tokens access Confluent Cloud APIs

You can use the Confluent Cloud audit log to verify that the Confluent STS access token is being used to access Confluent Cloud APIs.

  1. Open the Confluent Cloud Console and go to the Audit Logs page at https://confluent.cloud/settings/audit_log.

  2. Follow the steps on the Audit Logs page to use the Confluent CLI to consume audit log events.

  3. Run the confluent kafka topic consume command to start consuming audit log events.

    confluent kafka topic consume -b confluent-audit-log-events

  4. Verify that the audit log event records include the Confluent access token.

    For example, the following GetInvitation event method includes details about the identity pool resource_id, the identity of the user, and the result of the authentication request.

    "authentication_info": {
  "exposure": "CUSTOMER",
  "principal": {
          "identity_pool": {
                  "resource_id": "pool-1"
          }
  },
  "identity": "crn://confluent.cloud/organization=org-resource-id/identity-provider=op-1/identity=test@confluent.io",
  "result": "SUCCESS"
}