Keycloak Service Accounts Client Credentials Official Docs
You set up machine login in Keycloak by turning on the client credentials grant. The keycloak service accounts client credentials official docs show how apps get tokens without users. Teams use this flow so backend scripts can talk to internal APIs and databases. Still, teams often give these machine accounts broad roles just to make scripts work. When a script holds wide rights, one bad command can harm production data. How keycloak service accounts client credentials official docs work In t
Keycloak + Ephemeral Credentials: the complete guide
Architecture patterns, implementation strategies, and security best practices. Delivered to your inbox.
You set up machine login in Keycloak by turning on the client credentials grant. The keycloak service accounts client credentials official docs show how apps get tokens without users. Teams use this flow so backend scripts can talk to internal APIs and databases. Still, teams often give these machine accounts broad roles just to make scripts work. When a script holds wide rights, one bad command can harm production data.
How keycloak service accounts client credentials official docs work
In this setup, an app acts as its own user instead of a person. You start by creating a private client inside your Keycloak realm for that app. Next, you enable the service account feature so the client gets an internal identity. Keycloak then creates a special user record tied straight to that specific client ID.
Your app sends its client ID and secret or signed key to the token endpoint. Keycloak checks those credentials and returns a signed token to the calling app. That token holds the realm roles and client roles assigned to the service account. Downstream services read the token to check if the app can run a request.
Teams map specific roles to the service account so it only reaches certain systems. You can also add custom claims to the token using standard mapper rules. This lets backend apps check group membership or custom labels before they run code. Once the token expires, the app asks Keycloak for a fresh one and keeps working.
What native client credentials solve and what they miss
Native service accounts solve the problem of how machines prove who they are. You do not need to create fake human users or share personal passwords across scripts. Admins can rotate secrets in one place and turn off an app right away. Keycloak also logs every time an app asks for a new token.
Still, Keycloak only decides who logs in and which broad roles they carry. Once the app has a valid token, Keycloak steps out of the way. It cannot see the actual database queries or system commands the app runs next. If a script has write access, it can drop tables or read every row.
Keycloak + Ephemeral Credentials: architecture patterns and best practices
Continue reading? Get the full guide.
Free. No spam. Unsubscribe anytime.
A valid token also does not stop an app from pulling sensitive user data. When a script runs a broad query, results may include emails, phone numbers, or card numbers. Native identity tools do not rewrite those matched fields in results during the session. Teams still need a way to check each command and mask sensitive fields in flight.
Best practices for managing machine roles in production
Give each automated script or worker its own separate client inside your realm. When five scripts share one client secret, you cannot tell which script ran a task. Separate clients also let you turn off one broken app without stopping the others. Keep token life spans short so old tokens cannot be used for long.
Scope the roles on each service account to the smallest set of needed actions. Avoid giving admin roles to background jobs that only need to read a few tables. Review your machine accounts every few months and delete clients that teams no longer run. Store client secrets in a secure secret store instead of plain text files.
Govern statements and responses across databases and APIs
Good config and scoped roles are needed setup. They do not check single queries in flight or mask sensitive fields in returned rows. Across Postgres, MySQL, SQL Server, MongoDB, ClickHouse, Kubernetes APIs, SSH, and internal HTTP endpoints, hoop.dev runs beside each supported service as an open-source proxy, a sidecar for your database or API.
First, hoop.dev guardrails block banned queries before they run. Then hoop.dev data masking rewrites matched sensitive values in responses in memory. The audit trail records every statement and verdict per resource. Furthermore, hoop.dev holds SOC 2 Type II and is open source on GitHub.
Frequently asked questions
When should a team use a service account instead of a user flow?
Use a service account when a background job or microservice runs with no person present. If a human sits at a screen, use a standard interactive login flow instead.
Can a Keycloak service account hold both realm and client roles?
Yes, you can assign both realm roles and specific client roles to a service account. Those roles appear inside the access token so downstream apps can check them.
Do service account tokens include a refresh token by default?
Standard client credentials flows return an access token without needing a refresh token. When the access token expires, the app sends its credentials again to get a new one.