Skip to content
Tutorials Center
My learning

Topics

Lesson 8 of 37 ยท Concepts and Setup

Your First Realm, User and Client in Keycloak

Create a realm, a user with a password and a client, then request a token with curl and read the discovery document. Includes runnable token-request stand-ins.

Time to build something. In this lesson you create a realm named demo, a user, and two clients, then ask Keycloak for a real token from the command line. Each step names the exact menu entries and fields. If you have not started a server yet, do that first with Running Keycloak with Docker.

The steps are for your own Keycloak server. On this site the matching runnable blocks are stand-ins: they build the same HTTP requests and decode the same kind of response, but nothing is sent anywhere.

Step 1: create a realm

  1. Sign in at http://localhost:8080/admin/ as the bootstrap admin.
  2. Open the realm selector (top left) and choose Create realm.
  3. Realm name: demo. Leave Enabled on. Click Create.

You are now inside demo. Its URL base is http://localhost:8080/realms/demo. Check it by opening the discovery document:

Terminal
curl http://localhost:8080/realms/demo/.well-known/openid-configuration

You get JSON listing issuer, authorization_endpoint, token_endpoint, userinfo_endpoint, jwks_uri, end_session_endpoint and the supported grant types, scopes and claims. Client libraries read this single URL and configure themselves.

Step 2: create a user

  1. Users > Create new user.
  2. Username: alice. Email: [email protected], first name Alice, last name Example. Turn Email verified on so no mail server is needed. Click Create.
  3. Open the Credentials tab > Set password. Enter a password, turn Temporary off (otherwise Keycloak asks Alice to change it at first login), and save.

Alice can now log in at the Account Console: http://localhost:8080/realms/demo/account.

Step 3: a client for the command line

For this exercise we use the direct access grant (password grant). It is legacy and disallowed by the OAuth 2.1 draft, so use it only here to see a token quickly; real apps use the code flow in the next chapter.

  1. Clients > Create client.
  2. Client type OpenID Connect, Client ID demo-cli. Next.
  3. Turn Client authentication off (public client) and tick Direct access grants. Untick Standard flow for now. Save.

Now request a token:

Terminal
curl -s -X POST http://localhost:8080/realms/demo/protocol/openid-connect/token \
  -d grant_type=password \
  -d client_id=demo-cli \
  -d username=alice \
  -d password='the-password-you-set' \
  -d scope=openid

The response is JSON with access_token, expires_in, refresh_token, refresh_expires_in, token_type (Bearer), id_token (because of openid), session_state and scope. Treat tokens like passwords: do not paste real ones into chat or tickets.

Call the userinfo endpoint with the access token:

Terminal
curl -s http://localhost:8080/realms/demo/protocol/openid-connect/userinfo \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Errors you may see: invalid_grant ("Invalid user credentials", or "Account is not fully set up" when a required action such as Update Password is still pending), unauthorized_client (the grant type is not enabled on the client) and invalid_client.

Step 4: a client for a web application

A real web app uses a client with the standard flow:

  1. Clients > Create client, OpenID Connect, Client ID demo-web.
  2. Turn Client authentication on if the app has a server side that can keep a secret; keep Standard flow on.
  3. Valid redirect URIs: http://localhost:3000/callback. Web origins: http://localhost:3000 (used for CORS).
  4. Save. In Credentials, copy the client secret (store it in a secret manager, not in source code).

The redirect URI check is exact for non-wildcard values. If your app sends a different redirect_uri, Keycloak shows "Invalid parameter: redirect_uri" and refuses to continue. That strictness protects users from stolen authorization codes.

sequenceDiagram
  participant App as demo-web
  participant KC as Keycloak (realm demo)
  App->>KC: GET /auth?client_id=demo-web&redirect_uri=...&scope=openid
  KC-->>App: login page, then redirect with code
  App->>KC: POST /token (code + secret)
  KC-->>App: access, ID and refresh tokens

Build the token request (stand-in)

It is easy to forget a parameter. This runnable stand-in assembles the form body and checks required fields, the same way a library would, and prints the equivalent curl command. It performs no network call.

Node.js Stand-in: build a token request

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Read the discovery document (stand-in)

Apps use the discovery JSON to find endpoints instead of hard-coding them. This stand-in works on a sample document shaped like a real one (abbreviated) and builds an endpoint table.

Node.js Stand-in: use a discovery document

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Tidy up and what to remember

  • Delete demo-cli when you finish experimenting, or switch off Direct access grants. Leaving legacy grants enabled is a common finding in security reviews.
  • Use http://localhost only on your own machine. Any other host needs HTTPS.
  • Note the pattern for every endpoint: /realms/{realm}/protocol/openid-connect/{auth|token|userinfo|certs|logout}.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Where do client libraries find all the endpoints of a realm?

    The discovery document lists issuer, endpoints, supported grants and claims.
  2. 2. You get invalid_grant 'Account is not fully set up'. What is a likely cause?

    Required actions must be completed before a direct token request can succeed. Setting the password as non-temporary and verifying email avoids it.
  3. 3. Why is the direct access grant used only for a quick test here?

    The password grant breaks the delegation principle and is removed in OAuth 2.1.
  4. 4. What happens if the app sends a redirect_uri that is not in Valid redirect URIs?

    Exact redirect matching protects authorization codes from being sent to an attacker's URL.

Summary

  • Create a realm (demo), then a user with a non-temporary password and verified email.
  • Clients define how an app gets tokens: public (no secret) or confidential (secret), with the right capability switches.
  • Direct access grant lets you curl a token for testing; real apps use the standard flow.
  • Valid redirect URIs and Web origins must match exactly what the app uses.
  • All endpoints follow /realms/{realm}/protocol/openid-connect/... and are listed in the discovery document.

Next: Realms in Depth