Keycloak Device Code Flow
You set up the keycloak device code flow by turning on the device grant for your client app. The user then enters a short code in a web browser to log in from a headless tool. Engineering teams often use this flow for command line tools and remote servers that lack a browser. Still, teams often map these logins to broad admin roles that grant far too much power. How the keycloak device code flow works in practice Many developer tools run in a terminal with no screen for a web login page. The
Keycloak + Infrastructure as Code Security Scanning: the complete guide
Architecture patterns, implementation strategies, and security best practices. Delivered to your inbox.
You set up the keycloak device code flow by turning on the device grant for your client app. The user then enters a short code in a web browser to log in from a headless tool. Engineering teams often use this flow for command line tools and remote servers that lack a browser. Still, teams often map these logins to broad admin roles that grant far too much power.
How the keycloak device code flow works in practice
Many developer tools run in a terminal with no screen for a web login page. The OAuth 2.0 device authorization grant solves this problem by splitting the login across two devices. First, the command line tool asks the identity server to start a new login session. The server sends back a unique device code, a short user code, and a web address.
Next, the terminal shows the short user code and the web link to the engineer. The engineer opens that link on a phone or laptop that has a full browser. While the engineer logs in, the terminal tool polls the identity server every few seconds. The server tells the tool to wait until the user finishes the browser steps.
In the browser, the engineer types in the short code and completes single sign-on. They also pass any multi-factor checks that the security team requires for that account. Once the user approves the request, the identity server marks the device code as valid. On the next poll, the server hands an access token back to the waiting terminal tool.
Setting up your client and managing token timers
To use this workflow, an admin must first enable the device grant on the client profile. Public clients like command line tools usually do not hold a client secret on the local machine. Keeping secrets out of local binaries stops attackers from stealing keys out of the tool files. Instead, the server relies on the user login and the short code to prove identity.
Admins also need to tune several timers to keep the login process safe and smooth. The device code lifespan sets how long the user has to type in the short code. If this window is too long, an old code left on a screen could create a risk. If it is too short, users will fail to finish their multi-factor step in time.
You must also watch the polling interval that the server sets for waiting clients. If thousands of scripts poll the server too fast, they can slow down the login service. The server will tell a rude client to slow down or drop the request right away. Good client tools respect this timer and wait the right number of seconds between checks.
Keycloak + Infrastructure as Code Security Scanning: architecture patterns and best practices
Continue reading? Get the full guide.
Free. No spam. Unsubscribe anytime.
What device login solves and what it leaves open
Using the device grant is much safer than storing static keys on developer laptops. It brings full single sign-on and multi-factor rules to simple terminal tools and scripts. When an engineer leaves the company, you can shut off their central account in one place. Their terminal tools will fail to refresh tokens as soon as the old session ends.
Yet this login flow only checks who the person is at the start of a session. Once the tool gets a token, the identity server steps out of the way completely. The token often maps to a static role on a database, cluster, or cloud account. If that role can drop tables or read secret rows, the login server cannot stop it.
In short, the identity server decides who logs in, not what commands run next. It cannot inspect a single query or block a risky action during an active session. It also cannot rewrite sensitive fields like emails, phone numbers, or card numbers in query results. Teams still need a way to control each action and mask sensitive data in flight.
Add runtime guardrails and masking beside your databases and APIs
Login rules, role grants, and CI checks govern who connects to your stack. Yet any allowed script, engineer, or AI agent still runs commands with the full scope of its role. For workloads on Postgres, MySQL, SQL Server, MongoDB, ClickHouse, Kubernetes, SSH, or internal HTTP services, hoop.dev sits beside the service as an open-source proxy, a sidecar for your database or API.
Before a query runs, hoop.dev guardrails check the statement against your rules. An AI Analyzer you configure can score intent or hold risky calls for human review. Next, hoop.dev data masking rewrites sensitive fields in responses, and each verdict is logged per listener. Explore the MIT-licensed project on GitHub.
Frequently asked questions
When should a team use the device code flow?
Use this flow when a tool runs on a machine without a local web browser. It works well for command line tools, remote servers, and containers that need user login. The user logs in on a separate phone or laptop while the tool waits for a token.
Does the device flow require a client secret on the user machine?
No, command line tools are usually set up as public clients without a shared secret. Any secret stored inside a downloaded binary is easy for an attacker to pull out. Security comes from the user logging in through a trusted browser with multi-factor checks.
Can the identity server limit which database queries a user runs after login?
No, the identity server only checks identity and hands out a token at login time. It does not see the traffic that flows between the client tool and the database. To filter commands or mask fields like national IDs, you need controls at the session layer.