Before we can talk about Direct Access Grants, we need to understand the system it lives inside.

The problem: every app needs to know who you are

Almost every piece of software you use — a banking app, an online store, an internal company dashboard — needs to answer one question before it does anything else: “who is this person, and what are they allowed to do?” This is called authentication (proving who you are) and authorization (deciding what you’re allowed to do). If every single application had to build its own username/password database, its own password reset flow, its own multi-factor authentication, and its own session management, we would end up with hundreds of slightly different, slightly insecure login systems scattered across a company.

What Keycloak actually is

Keycloak is an open-source Identity and Access Management (IAM) system, originally built by Red Hat and now part of the Cloud Native Computing Foundation ecosystem. It centralizes login, user storage, password policies, multi-factor authentication, and token issuance in one place, so individual applications don’t have to reinvent any of it. Instead of writing your own login form and password database, your application simply asks Keycloak, “has this person logged in, and here is proof” — and Keycloak hands back a signed, verifiable token.

Why “flows” exist at all

OAuth 2.0, the protocol Keycloak implements, doesn’t define just one way to get a token — it defines several, called grant types or flows. Each flow is designed for a different situation: a flow suitable for a website with a browser is very different from one suitable for a smart TV with no keyboard, which is again different from one suitable for a backend job with no human user at all. Direct Access Grants is one of these flows, purpose-built for a specific, narrower situation than the others — and understanding that situation is the whole point of this tutorial.

Now that we know Keycloak’s role, let’s define the flow itself in plain terms.

In Keycloak’s admin console, “Direct Access Grants” is the friendly name for what the OAuth 2.0 specification calls the Resource Owner Password Credentials (ROPC) grant. Stripped of jargon, it means this: the application itself collects the user’s username and password (usually through its own login form) and sends those credentials directly to Keycloak’s token endpoint. Keycloak checks them and, if they’re correct, returns tokens immediately in the same response — no redirects, no separate Keycloak-hosted login page, no browser pop-up.

The core idea in one sentence

Instead of Keycloak showing the login screen, your own application shows the login screen, collects the password, and forwards it to Keycloak on the user’s behalf in a single, direct HTTP request.

Where it lives in the Keycloak admin console

For any client registered in Keycloak, under the client’s Settings tab there is a toggle called “Direct Access Grants Enabled.” When this is switched on, that client is permitted to use this flow. By default, many client templates leave it enabled, which is one reason it’s important to consciously decide whether your client actually needs it, rather than leaving it on by accident.

We are deliberately not including raw request/response code samples in this tutorial — the goal here is to build a strong mental model of what happens and why, not to hand you copy-paste snippets. Once the concepts below are clear, reading Keycloak’s official request/response reference will make immediate sense.

Context matters — seeing the whole family of flows helps you understand why this one is shaped the way it is.

OAuth 2.0 defines a small family of flows, and Keycloak implements all of the common ones. Each is optimized for a different combination of “who is present” (a human with a browser? a backend service? a device with no screen?) and “how much do we trust the application?”

The key differentiator: who touches the password

The single most important distinction between these flows is who ever sees the user’s raw password. In the Authorization Code flow, only Keycloak’s own login page ever sees it — the client application never does. In Direct Access Grants, the client application’s own form is what the user types their password into, meaning the application code has a brief window where it is directly handling raw credentials.

A quick map of the request flow difference

The diagram below shows, at a high level, how a browser-redirect flow (like Authorization Code) differs structurally from Direct Access Grants. Notice that in the redirect-based flow, the browser is sent away to Keycloak’s own domain to enter the password, whereas in Direct Access Grants, the password never leaves the application’s own form.

flowchart LR
    subgraph Redirect["Authorization Code Flow"]
        A1[User] -->|clicks Login| A2[App]
        A2 -->|redirect| A3[Keycloak Login Page]
        A3 -->|user types password here| A3
        A3 -->|redirect back with code| A2
    end
    subgraph Direct["Direct Access Grants Flow"]
        B1[User] -->|types password into| B2[App's own form]
        B2 -->|sends username+password| B3[Keycloak Token Endpoint]
        B3 -->|returns tokens| B2
    end
        

This single structural difference — where the password gets typed — is the reason the two flows have such different security postures, and it’s why OAuth 2.0’s later security guidance treats them so differently, as we’ll cover in the security chapter.

Let’s walk through the full lifecycle of a single login using Direct Access Grants, from the moment a user types their password to the moment the app has a usable token.

What makes this flow feel so simple is precisely what makes it risky: everything happens in one round trip, with no opportunity for Keycloak to add extra verification steps mid-flow, such as showing a CAPTCHA, redirecting to a third-party identity provider, or prompting for an additional multi-factor authentication step through its own UI.

sequenceDiagram
    participant U as User
    participant A as Application
    participant K as Keycloak

    U->>A: Enters username & password
    A->>K: POST /token (grant_type=password, client_id, credentials)
    K->>K: Authenticate client
    K->>K: Authenticate user against user store
    K->>K: Resolve roles, scopes, mappers
    K-->>A: access_token, refresh_token, id_token
    A->>A: Discard raw password
    A-->>U: Logged in
        

A successful Direct Access Grants request doesn’t just return “a token” — it typically returns up to three distinct tokens, each with a different job.

Why tokens are short-lived on purpose

Access tokens in Keycloak typically expire quickly — often within a few minutes — by design. This is a deliberate security trade-off: if a token is ever leaked or stolen, the window during which it can be misused is small. The refresh token, in turn, allows the application to quietly obtain a new access token in the background, so the user experience stays seamless even though the underlying tokens are rotating constantly.

What’s inside a JWT, conceptually

Every token Keycloak issues is (by default) a JSON Web Token, or JWT. Without diving into code, the important idea is this: a JWT is made of three parts — a header describing how it’s signed, a payload containing claims (facts like the user’s ID, roles, and expiry time), and a signature that lets any system verify the token hasn’t been tampered with, without needing to call Keycloak every single time. This is what makes tokens so efficient: verification can happen locally, using Keycloak’s published public key.

Every design decision is a trade-off. Here’s an honest look at both sides of Direct Access Grants.

None of this means the flow is “bad” — it means it is situational. A flow that is a poor fit for a public consumer-facing mobile app might be exactly the right fit for an internal automation script running inside a company’s own trusted infrastructure.

This is the most important chapter in the whole tutorial — read it carefully before enabling this flow anywhere.

Why the OAuth 2.0 community moved away from this flow

The IETF’s OAuth 2.0 Security Best Current Practice document explicitly recommends against using the Resource Owner Password Credentials grant, and states that it should be avoided for new applications. The core reasoning is simple: any flow where an application handles raw passwords creates more places where things can go wrong — logging, memory dumps, malicious dependencies, compromised client code, or a poorly secured mobile app can all potentially expose credentials that would never have existed in the application’s process in a redirect-based flow.

When it can still be a reasonable, controlled choice

Despite the general guidance against it, there are narrower situations where Direct Access Grants remains a pragmatic, acceptable choice — precisely because the application is fully trusted and tightly controlled.

Concrete hardening steps

Enabling a flow is only half the job — knowing what “healthy” and “suspicious” usage looks like is the other half.

What to watch in Keycloak’s own logs and events

Keycloak can be configured to emit login events, and these are especially valuable for a password-based flow because there’s no browser session to inspect afterward — the event log becomes your primary window into what happened.

Metrics worth putting on a dashboard

Beyond raw logs, exposing Keycloak’s metrics endpoint to your monitoring system lets you track trends over time rather than just individual events: authentication success/failure ratios per client, average token issuance latency, and the proportion of traffic coming through this particular grant type relative to others. If Direct Access Grants traffic starts creeping up unexpectedly as a share of total logins, that’s worth a conversation about whether it’s being used where it shouldn’t be.

Some usage patterns are sound engineering; others quietly introduce risk. Here’s how to tell them apart.

A condensed, practical checklist for teams actually implementing this flow.

Seeing where organizations actually apply this flow helps ground the theory in practice.

Across these examples, notice the common thread: in every legitimate real-world use, the organization fully controls both the client application and the environment it runs in. None of them involve handing the flow to a third-party developer or shipping it inside a public app store binary — and that consistency is exactly what the security guidance in Chapter 7 recommends.

A side-by-side view makes the trade-offs concrete.

Reading this table, a clear pattern emerges: Direct Access Grants is the only flow among the common ones where the requesting application itself directly handles the raw password. Every other flow either removes the password entirely from the picture (Client Credentials) or keeps it confined strictly to Keycloak’s own trusted login surface (Authorization Code, Device Authorization).

Yes. “Direct Access Grants” is simply Keycloak’s user-friendly label for the OAuth 2.0 Resource Owner Password Credentials (ROPC) grant type — they refer to the exact same mechanism.

Keycloak still supports and implements it, but the broader OAuth 2.0 security best practices guidance recommends against using it for new applications, especially public or third-party clients, in favor of the Authorization Code flow with PKCE.

Not in the same rich way the Authorization Code flow can, because it bypasses Keycloak’s own hosted login page where interactive MFA challenges are typically presented. Some limited, non-interactive additional factors can be layered on, but the flow’s single-round-trip nature makes rich adaptive MFA difficult.

If the client is configured as confidential (the recommended setup for this flow), yes, a client secret must be sent along with the request. Public clients technically can use this flow too, but doing so is strongly discouraged since they cannot keep a secret confidential.

Not naturally. Because there’s no browser session or redirect involved, Keycloak’s usual browser-based SSO cookie mechanism doesn’t come into play the same way it does with the Authorization Code flow, where a single Keycloak session can silently authenticate the user into multiple applications.

Generally, no. Mobile apps distributed to end users are considered public clients, and the recommended approach is Authorization Code flow with PKCE, using an embedded browser or system browser to show Keycloak’s own login page.

Yes — once issued, a refresh token behaves the same regardless of which flow originally produced it, and can be used to obtain new access tokens until it expires or is revoked.

Direct Access Grants is Keycloak’s implementation of the OAuth 2.0 Resource Owner Password Credentials grant: a flow where an application collects a user’s username and password itself and exchanges them directly for tokens in a single request to Keycloak’s token endpoint, with no browser redirect involved. It’s simple, fast, and well-suited to trusted, tightly-controlled environments like internal automation, command-line tools, and legacy migration bridges — but it also means the requesting application becomes part of the security boundary around the user’s raw password, which is why broader OAuth guidance steers public and third-party applications toward the redirect-based Authorization Code flow instead. Used deliberately, on the right clients, with strong hardening (TLS, short-lived tokens, brute-force protection, and careful monitoring), it remains a legitimate and useful tool in Keycloak’s toolbox rather than something to avoid outright.