OAuth Client Credentials for Service Accounts

This guide demonstrates how developers can leverage Client Credential authentication to secure communication between service accounts and client applications within ZITADEL.

In ZITADEL, the Client Credentials Flow can be used for this non-interactive authentication as alternative to the JWT profile authentication.

Steps to authenticate a Service Account with client credentials

1. Create a Service Account with a client secret

1. Navigate to Service Accounts
2. Click on New
3. Enter a username and a display name
4. Click on Create
5. Open Actions in the top right corner and click on Generate Client Secret
6. Copy the ClientID and ClientSecret from the dialog

2. Authenticating a service account and request a token

In this step, we will authenticate a service account and receive an access_token to use against the ZITADEL API.

You will need to craft a POST request to ZITADEL's token endpoint:

curl --request POST \
  --url https://${CUSTOM_DOMAIN}/oauth/v2/token \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data grant_type=client_credentials \
  --data scope='openid profile' \
  --user "$CLIENT_ID:$CLIENT_SECRET"

• CUSTOM_DOMAIN should be set to your Custom Domain
• grant_type should be set to client_credentials
• scope should contain any Scopes you want to include, but must include openid. For this example, please include profile
• CLIENT_ID and CLIENT_SECRET should be set with the values shown in Management Console when generating a new secret to enable basic authentication

If you want to access ZITADEL APIs, make sure to include the required scopes urn:zitadel:iam:org:project:id:zitadel:aud. Read our guide how to access ZITADEL APIs to learn more.

Important Note: If the service account token needs to be validated using token introspection, ensure you include the urn:zitadel:iam:org:project:id:{projectid}:aud scope in your token request. Without this, token introspection will fail.

You should receive a successful response with access_token, token_type and time to expiry in seconds as expires_in.

HTTP/1.1 200 OK
Content-Type: application/json

{
  "access_token": "MtjHodGy4zxKylDOhg6kW90WeEQs2q...",
  "token_type": "Bearer",
  "expires_in": 43199
}

Per default a service account will get an opaque access token. If you want to get a JSON Web Token (JWT) as an access token for your user, you can change the token type in the general settings of your service account. To learn more about opaque and JWT tokens read our Opaque Tokens in ZITADEL: Enhancing Application Security Guide

3. Include the access token in the authorization header

When making API requests on behalf of the service account, include the generated token in the "Authorization" header with the "Bearer" prefix.

curl --request POST \
  --url $YOUR_API_ENDOINT \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --header 'Authorization: Bearer MtjHodGy4zxKylDOhg6kW90WeEQs2q...'

Accessing ZITADEL APIs

You might want to access ZITADEL APIs to manage resources, such as users, or to validate tokens sent to your backend service. Follow our guides on how to access ZITADEL API to use the ZITADEL APIs with your service account using client credentials.

Token introspection

Your API endpoint might receive tokens from users and need to validate the token with ZITADEL. In this case, your API needs to authenticate with ZITADEL and then do a token introspection. Follow our guide on token introspection with client credentials to learn more.

Security considerations

• Store private keys securely: Never share or embed the private key in your code or application. Consider using secure key management solutions.
• Set appropriate expiration times: Limit the validity period of tokens to minimize the impact of potential compromise.

By following these steps and adhering to security best practices, you can effectively secure service account and client application communication within ZITADEL using client credential authentication.

Notes

• Read about the different methods to authenticate service accounts
• Service Account API reference
• OIDC client secret basic authentication method reference
• Access ZITADEL APIs
• Validate access tokens with token introspection with basic auth