OIDC Device Code Flow
The oidc device code flow lets users log in on devices without browsers. The client app shows a short code that the user enters on another device. Platform teams set up this flow for command-line tools and remote servers. It removes the need to copy long passwords into a terminal window. Yet many teams link this login to broad cloud or database roles. Once the token arrives, the user gets wide rights across the target system. How the oidc device code flow works step by step A headless tool st
Infrastructure as Code Security Scanning + IoT Device Identity Management: the complete guide
Architecture patterns, implementation strategies, and security best practices. Delivered to your inbox.
The oidc device code flow lets users log in on devices without browsers. The client app shows a short code that the user enters on another device. Platform teams set up this flow for command-line tools and remote servers. It removes the need to copy long passwords into a terminal window. Yet many teams link this login to broad cloud or database roles. Once the token arrives, the user gets wide rights across the target system.
How the oidc device code flow works step by step
A headless tool starts the process by calling the identity provider endpoint. It sends its client identifier and asks for a new login session. The identity provider returns a device code, a short user code, and a web address. The tool prints the web address and the short user code on the screen. It then waits and checks the identity provider at a set pace.
Next, the user opens the web address on a phone or laptop browser. The user logs in with standard single sign-on and multi-factor checks. Then the user types the short code shown in the terminal window. They review the requested scopes and approve the login request in the browser.
Meanwhile, the command-line tool keeps polling the token endpoint in the background. While the user types the code, the server returns a pending status. Once the user approves the prompt, the next poll gets a valid token. The tool stores this token and uses it to call backend systems. The identity provider stops the code from working after one use or a short timer.
Where token polling helps and where it falls short
This login pattern solves a real problem for engineers on remote servers. Users never type raw passwords or MFA codes into an untrusted terminal. The identity provider enforces central login rules and multi-factor checks in a real browser. Security teams also avoid storing static keys on engineer laptops.
Still, the oidc device code flow only solves the initial login step. After the client gets an identity token, the login flow is done. The token maps the engineer to a static role in the target database or cluster. That role stays active for the full life of the token.
Infrastructure as Code Security Scanning + IoT Device Identity Management: architecture patterns and best practices
Continue reading? Get the full guide.
Free. No spam. Unsubscribe anytime.
Static roles decide who can enter, not what commands they run inside. An engineer with a valid token can still run a bad delete query. They can also pull tables full of emails, phone numbers, or card numbers. The identity provider cannot see or block risky commands during the session. It also cannot ask a teammate to approve one specific write command. Teams still need controls that inspect requests and rewrite sensitive fields in results.
Managing token life and phishing risks in headless tools
Attackers sometimes abuse this flow by tricking users into entering a code. An attacker starts a session and sends the user code in a chat message. If the victim enters that code, the attacker's tool gets the token. Teams should train users to only enter codes they requested on their own screen.
Admins should also set short timeouts for pending user codes. If a user does not finish the login fast, the code must expire. Teams should limit refresh tokens so sessions do not last for weeks. Short token lives force a fresh browser check before starting new work. Even with short tokens, teams must watch what queries run after login.
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 the oidc device code flow?
Use this flow for command-line tools, headless servers, or devices without a web browser. If the app runs on a laptop with a browser, use the standard redirect flow instead.
How does the client tool know when the user finishes logging in?
The client tool polls the identity provider token endpoint every few seconds. Once the user approves the request in their browser, the next poll returns the tokens.
Does the oidc device code flow control what queries a user can run?
No, the flow only checks identity and issues a token at login time. It does not inspect SQL queries, block dangerous commands, or mask emails and card numbers in results.