- keycloak

Minimal Keycloak Client Setup (oauth2-proxy + Nginx)

This checklist describes the simplest possible configuration to get a new Keycloak client working with:

• Keycloak
• oauth2-proxy
• Nginx
• a protected website (example: chess.public-risk.org)

The goal is only authentication, without roles, groups, or advanced configuration.

---

Goal

First get this working:

1. User opens a protected page.
2. User is redirected to Keycloak.
3. User logs in.
4. Keycloak redirects back to the site.
5. oauth2-proxy accepts the session.
6. Nginx allows access.

No authorization logic yet --- just login.

---

1. Create a new client in Keycloak

Navigate to:

Clients → Create Client

Example values:

Setting Value

---

Client type OpenID Connect Client ID chess-public-risk-org Name chess-public-risk-org

Save.

---

2. Capability configuration

Keep the configuration minimal.

Setting Value

---

Client authentication ON Authorization OFF Standard flow ON Direct access grants OFF Implicit flow OFF Service accounts roles OFF

This enables the standard OIDC browser login flow.

---

3. Login settings

Example for chess.public-risk.org.

Valid redirect URIs

https://chess.public-risk.org/oauth2/callback

Temporary debug option:

https://chess.public-risk.org/*

---

Valid post logout redirect URIs

https://chess.public-risk.org/

or

https://chess.public-risk.org/*

---

Root URL

https://chess.public-risk.org

---

Home URL

https://chess.public-risk.org/

---

Web origins

https://chess.public-risk.org

---

4. Obtain the client secret

After saving the client:

Clients → Credentials

Copy:

Client Secret

This value will be needed in oauth2-proxy.

---

5. Do NOT configure roles or groups yet

For the first working setup:

Do not create:

• client roles
• realm roles
• groups
• authorization policies

First get the login flow working.

---

6. Leave scopes mostly default

Typical minimal scope configuration:

openid profile email

Later you can add:

groups

but this is not needed for basic authentication.

---

7. Minimal oauth2-proxy configuration

Core settings required for Keycloak:

provider = "keycloak-oidc"

oidc_issuer_url = "https://dev.public-risk.org/keycloak/realms/master"

client_id = "chess-public-risk-org"
client_secret = "PASTE_CLIENT_SECRET_HERE"

redirect_url = "https://chess.public-risk.org/oauth2/callback"

scope = "openid profile email"

Additional cookie and proxy settings may also be present depending on your setup.

---

8. Minimal Nginx configuration

Example simplified authentication flow:

location /oauth2/ {
    proxy_pass http://127.0.0.1:4180;
}

location = /_auth {
    internal;
    proxy_pass http://127.0.0.1:4180/oauth2/auth;

    proxy_pass_request_body off;
    proxy_set_header Content-Length "";

    proxy_set_header X-Forwarded-Uri $request_uri;
    proxy_set_header X-Forwarded-Host $host;
    proxy_set_header X-Forwarded-Proto $scheme;
}

location / {
    auth_request /_auth;
    error_page 401 = /oauth2/start?rd=$request_uri;

    root /var/www/chess.public-risk.org/current;
    try_files $uri $uri/ /index.html;
}

No group checks yet.

---

9. First test procedure

1. Open

<!-- -->

https://chess.public-risk.org/

1. You should be redirected to Keycloak.

2. Log in.

3. Keycloak redirects to:

<!-- -->

/oauth2/callback

1. oauth2-proxy creates a session.

2. The website loads.

If this works, the authentication pipeline is functional.

---

10. Common early problems

Redirect URI mismatch

Ensure the exact same URI is used in:

• Keycloak client
• oauth2-proxy redirect_url

Example:

https://chess.public-risk.org/oauth2/callback

---

Wrong client secret

Copy the correct secret from:

Keycloak → Clients → Credentials

---

Wrong issuer URL

Verify the realm path:

https://dev.public-risk.org/keycloak/realms/master

---

Nginx not forwarding /oauth2/

The /oauth2/ location must go directly to oauth2-proxy.

---

11. Recommended development order

Phase 1

Get basic login working.

• client created
• redirect URI correct
• oauth2-proxy connected
• successful login

---

Phase 2

Implement logout flow.

---

Phase 3

Add groups, for example:

/chess-users

---

Phase 4

Add:

• roles
• application-level permissions
• custom claims
• theming

---

Minimal working configuration summary

Client ID:

chess-public-risk-org

Redirect URI:

https://chess.public-risk.org/oauth2/callback

Logout redirect:

https://chess.public-risk.org/

Scopes:

openid profile email

---

Principle:

One client, one redirect URI, one domain, one test user.