How to setup roles in Keycloak

A) Create / prepare your Realm

1. Sign in to Keycloak Admin Console.
2. Top-left realm selector → Create realm (e.g., acme).

B) Define your roles (admin / manager / user)

You can use Realm Roles (recommended for app-wide roles) or Client Roles (scoped to a single client). We’ll use Realm Roles.

1. In left nav, Roles → Add role:
   • Create admin, manager, user.
2. (Optional but tidy) Groups → Add groups admins, managers, users.
   • Inside each group → Role mappings → Assign role → add the matching realm role.
   • Later, just put users in groups; they’ll inherit the role.

Result: your tokens can include these realm roles under realm_access.roles.

C) Create the OIDC Client for Laravel

You have two safe choices. Pick one:

Option 1 — Public client + PKCE (no secret)

• Good when you don’t want to store a secret or might ever do a browser-based flow.

Option 2 — Confidential client (has a secret)

• Also fine for server-side Laravel Socialite (secret stays on your server).

Steps (common; I’ll note the one-line difference for each option):

1. Left nav Clients → Create client
   • Client type: OpenID Connect
   • Client ID: laravel-app (must match KEYCLOAK_CLIENT_ID in .env)
   • Name: (anything)
   • Always display in UI: your choice
   • Click Next
2. Capability config:
   • Client authentication:
     • OFF for Public + PKCE (Option 1)
     • ON for Confidential (Option 2)
   • Authorization: OFF (not needed)
   • Click Next
3. Login settings:
   • Valid redirect URIs: add your Laravel callback(s)
     • http://localhost:8000/auth/callback
     • https://yourapp.example.com/auth/callback
   • Web origins: add exact origins you’ll use (e.g., http://localhost:8000, https://yourapp.example.com). Avoid * in prod.
   • Root URL (optional but nice): your site’s base URL.
   • Save.
4. If you chose Option 1 (Public + PKCE):
   • Client → Advanced (or Settings, depending on version) → ensure PKCE is Required, Method = S256.
5. If you chose Option 2 (Confidential):
   • Client → Credentials tab → copy the Client Secret to your Laravel .env (KEYCLOAK_CLIENT_SECRET).

Make sure Standard Flow (Authorization Code) is enabled; it is enabled by default for new OIDC clients. We’re not using Implicit or Direct Access Grants.

D) Ensure roles are sent in tokens

Keycloak includes claims based on Client Scopes.

1. Client scopes (left nav) → confirm a built-in scope named roles exists (it normally does).
   • Inside it there’s a mapper for realm roles (go to “Mappers” and see “realm roles” / “roles”).
2. Go to your Client → Client scopes:
   • Under Assigned default client scopes, ensure roles is present.
   • If not, Add client scope → pick roles.
3. Keep profile and email in default scopes as well (usually already there).

Result: your ID token and Access token will include roles.

• Realm roles → realm_access.roles
• If you ever use client roles → resource_access[clientId].roles

Your Laravel callback code (from earlier) merges both; you’re covered either way.

E) Create users and assign roles

1. Users → Add user → fill username, email, etc. Save.
2. Credentials tab → set password (toggle temporary off if you want).
3. Assign role:
   • Either Role mappings → Assign role → pick admin/manager/user, Add.
   • Or put the user in a Group that already has the role.

Logins via social providers (Google/Apple) configured in Keycloak can also be mapped to these roles—see Section G.

F) Double-check client settings against Laravel .env

In Laravel you set:

KEYCLOAK_BASE_URL=http://localhost:8080      # or https://kc.yourdomain.com
KEYCLOAK_REALM=acme
KEYCLOAK_CLIENT_ID=laravel-app
KEYCLOAK_CLIENT_SECRET=   # only for confidential clients
KEYCLOAK_REDIRECT_URI=http://localhost:8000/auth/callback

In Keycloak client:

• Client ID = laravel-app
• Redirect URI includes /auth/callback
• Web origins include your app’s origins
• If Public client: PKCE required (S256)
• If Confidential: Client secret matches .env

G) (Optional) Add Google/Apple login to Keycloak (federated IdP)

If you want users to log in with Google/Apple into Keycloak (and still get your Laravel roles):

1. Identity Providers → Add provider → choose Google (or Apple).
2. Enter Google/Apple Client ID/Secret (from their developer consoles).
3. Save. Try login from the Keycloak login page → you’ll see a Google/Apple button.
4. Map to roles:
   • Use User Attribute → Role approach or Group Mapper:
     • Create a Group (e.g., admins) with role admin attached.
     • In Identity Providers → Mappers, add a mapper that puts users into that group based on an IdP attribute (e.g., email domain).
     • Alternatively, run a small post-login admin action to assign roles manually.

This keeps all SSO sources behind Keycloak; Laravel just sees a standard OIDC login.

H) (Optional) Single Logout (SLO)

If you want to log users out of Keycloak too (not just Laravel session):

• Use Keycloak’s end-session endpoint: {KEYCLOAK_BASE_URL}/realms/{REALM}/protocol/openid-connect/logout ?post_logout_redirect_uri={APP_URL_ENCODED} &id_token_hint={ID_TOKEN}
• You already capture id_token in the callback; you can stash it in session and call this on logout.
• If you skip SLO, your app will log out locally, but the Keycloak session remains until it expires.

I) Quick test flow

1. Start Keycloak (dev example): docker run -p 8080:8080 \ -e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=admin \ quay.io/keycloak/keycloak:25.0.6 start-dev
2. Create realm, roles, client, user (as above).
3. Run Laravel: php artisan serve
4. Visit http://localhost:8000/login → you should be redirected to Keycloak.
5. Log in with the test user (e.g., role manager) → you should land on /dashboard and only routes allowed by role:manager should work.

J) Troubleshooting

• Redirect URI mismatch → Ensure the exact URI (including scheme, host, port, path) is in “Valid redirect URIs.”
• 403 on protected routes → Token didn’t include roles:
  • Confirm roles client scope is assigned to the client.
  • Confirm the user actually has admin/manager/user (Role mappings or via Group).
  • Confirm you request the roles scope in Laravel (->scopes(['openid','profile','email','roles'])).
• CORS errors → Add your site origin(s) under Web origins.
• Time/clock skew → If tokens seem “not yet valid,” ensure Keycloak and server time are in sync (NTP).
• Confidential client → If code exchange fails, re-check the Client Secret in your .env.

That’s it

Once these steps are done, your Laravel app’s Socialite flow will receive an ID token containing realm_access.roles (and client roles if you ever use them), and your middleware will gate /admin, /manager, /user accordingly.

If you want, I can also give you a minimal Keycloak realm export (JSON) with the roles, a demo client pre-configured for http://localhost:8000/auth/callback, and a sample user—ready to import.