Keycloak OpenID connect authentication allows users to log in to Forgejo using their Keycloak credentials. This HowTo explains how to set up Keycloak as an authentication provider in Forgejo.

Authentication

First usecase to integrate is authentication. Authentication tells the integrated Forgejo who the user is. Under the hood this will login existing users and in addition register unknown ones.

Keycloak configuration

1. login as realm admin (for keycloak newbies https://[your.keycloak.server]/admin/[your-realm]/console is a good guess)
2. create forgejo-client
   1. Client authentication: on
   2. Root URL: [https://your.forgejo.server]
   3. Home URL: [https://your.forgejo.server]
   4. Valid Redirect URLs: [https://your.forgejo.server]*
3. create a testuser to test keycloak integration

Forgejo configuration

1. login as Forgejo admin
2. navigate to Site administration -> Identity & access -> Authentication sources
3. Add authentication source
4. choose OpenID connect
5. copy Client secret from keycloak to Forgejo
6. enter the OpenID Connect Auto Discovery URL: https://[your.keycloak.server]/realms/[your-realm]/.well-known/openid-configuration
7. Skip local 2FA: on

Authorization or role, org & team sync

Authorization in Forgejo happens based on some predefined roles and on organization & team membership. If we maintain groups in keycloak the mapping of groups to Forgejo (organization x team) combinations is supported.

Keycloak configuration

1. Create a client scope
   1. Set Name to e.g. forgejo-groups
   2. Leave Type at None
   3. Save
2. Click Mappers
   1. Click Configure a new mapper
   2. Click Group Membership
   3. Set Name to e.g. forgejo-groups
   4. Set Token Claim Name to e.g. forgejo-groups. This is a value, that needs to be set in Forgejo.
   5. Unset Full group path. For our example we use the plain group names.
   6. Make Sure Add to ID token, Add to access token, Add to userinfo are set.
   7. Save
3. Go to Groups
   1. Create groups and respective sub-groups. The group names need to be set in Forgejo
   2. Add users to their respective group/sub-groups. The users will be added to teams of the same name in existing organizations in Forgejo.
4. Go to Clients
   1. Select the client created above.
   2. Select Client scopes
      1. Click Add client scope
      2. Select the client scope you created e.g. forgejo-groups
      3. Click Add & select Default. Default will add the mapped information in the default token.

Forgejo configuration

1. navigate to Authentication source created above.
   1. Set Claim name providing group names for this source. (Optional). Must be the same as Token Claim Name
   2. Set Group claim value for administrator users. if desired. Must be the name of the keycloak group you defined to be administrator group.
   3. Set Group claim value for restricted users if desired. Must be the name you chose for the restricted access in keycloak.
   4. Add the mapping in Map claimed groups to organization teams.. The mapping might look like

              {"staff": {"internal-org": ["Staff"],
                         "public-org": ["Staff"]},
               "external": {"internal-org": ["Contributor"],
                            "public-org": ["Contributor"]},
               "your-customer1": {"customer-org": ["Staff"]}}
              

   5. Optional: Check the Remove users from synchronized teams if user does not belong to corresponding group. box for synchronized teams. This will remove users from a role / team if they are removed on keycloak side. Be careful! If you screw up your mapping, the role- and team-membership will also be removed.

The sync is done on next user login or session renew.

Logout Integration

At the moment there is

• no Single Logout. That means if a loged in user presses logout in forgejo, forgejo will not inform keycloak about the logout happened.
• no Logout Hook in Forgejo. That means keycloak can not active log out a user which is logged / deactivated out in keycloak. To reduce the impact you may configure a short session timeout:

     [session]
     SESSION_LIFE_TIME = 3600