Guide- Keycloak and Gitea

forgiteasoup · July 16, 2024, 8:14pm

Purpose

Tell you how to configure Gitea and Keycloak so it works
Save you hours of troubleshooting getting 500 errors with “invalid token”

Guide

To start, I feel like this should be easier than it was and perhaps it could be if I had doublechecked a lot.

Make sure your Keycloak is discoverable at the right address, enforces https properly, has the proper hostname, etc. This is outside the scope here but that is vital to begin with. You can check this mainly by setting up OpenID connect via it to some other app (many have integrations so even spinning up as a test is fine.)

Gitea config

ROOT_URL needs to be set to the proper value - ie. https://gitea.yourdomain.com/

[openid]
ENABLE_OPENID_SIGNIN = false
ENABLE_OPENID_SIGNUP = true
# not needed but nice- WHITELISTED_URIS = keycloak.yourdomain.com

I did not need any oauth2_client fields. Maybe someone can chime in but that not being set works fine for me.

Gitea Authentication source UI

Actually pretty simple here. You need the:

name
oauth2 provider (openID connect)
client ID (from keycloak client settings)
client key (from keycloak client settings)
discovery URL (this can be pulled from your Realm Settings under the Endpoints portion in keycloak)
Turn off additional 2FA # optional (ie. if keycloak does 2FA and gitea also mandates it, you’d do it twice which seems pointless)

Keycloak UI

Create a client like normal (ie. give it an ID, name, description, set it to use Client Authentication)

Under Settings

Root URL is good to have
Valid redirect URI is good for security

Under Client Scopes these should be optional

acr, address, microprofile-jwt, phone

Under Client Scopes these should be set to Default

basic, email, offline_access, profile, roles, web-origins

offline_access

This is the big change from everything I tested. For some reason, turning offline_access from optional to Default made it work. I have made a couple clients and went back and forth (both going to same gitea instance). I tweaked a ton in advanced settings, etc. too and for whatever reason, offline_access seems to be the ticket. I am not sure if the goth golang package that gitea uses is responsible for this kind of behavior or needing it but there you go.

Note- I set up authentication with Authelia (also testing that) in a lot shorter time. That seemed to just work FYI.

forgiteasoup · July 20, 2024, 8:52pm

A plus-

Mapping your LDAP groups to gitea (for at least standard user and admins)

Keycloak side

Go to Client Scopes on left
Add new client scope called “groups”
On this same page, go to Mappers tab
Add a new mapper “by configuration” and call it groupsmapper (this is our claim)
UNCHECK full group path setting (so we can simply retrieve gitea-users and not /full/path/to/gitea-users)
Go to your Client and add a client scope to it and select the “groups” one we just made

Gitea side

Go to your authentication source
Request an additional scope called “groups”
The claim to determine access at all would be groupsmapper and the value to allow would be gitea-users (or similar)
To determine standard access or admin access, reuse the same groupsmapper claim name and the value respectively would be gitea-users and gitea-admins (or whatever you have called them)

This configuration will:

disallow access for someone without membership to the gitea-users group
set standard access to users with only the gitea-users group assigned
set admin access (ie. Site Administration) to users who have the gitea-admins group assigned

evgn · November 20, 2024, 2:12pm

Hi! Thanks for this post, it helped me a lot in setting up the Keycloak connection.
I encountered the fact that when registering a user during initial authentication through Keycloak, the Is Restricted and Administrator attributes are not set, but are set when the user logs in again. Described in more detail in issue Set restricted or admin is performed after the second user login via OIDC auth · Issue #32566 · go-gitea/gitea · GitHub. Have you experienced something similar?

forgiteasoup · November 22, 2024, 6:25pm

I’ve only set this all up in testing (not put in prod yet) so I couldn’t say. I don’t recall this but it’s very possible. If I get a chance to spin it up again soon I’ll go ahead and check and report back.