Using Keycloak as identity provider for Gitea
Last modified by Christian Reiber on 2020/04/08 18:57
What is it
Gitea (like many other PI tools) requires users to authenticate. To avoid setting up similar user accounts in various applications you can provide your own central user database in Keycloak. Overmore, this allows to do user federation with external sources like Active Directory or to use Social Media providers as identity providers.
Prerequisites
- install the vcs-gitea and iam-keycloak stacks and make sure they are running
- in case you want to do user federation you need credentials for their access
How to achieve it
How to setup Keycloak to cooperate with Gitea is laid out in its stack documentation
For Gitea proceed as follows:
- edit Gitea's central configuration file
- On your ProjectServer enter docker exec -it vcs-gitea-app bash
- Fire up the editor on the config file: vi /data/gitea/runtime-conf/gitea.ini
- Locate the [service] section and make sure that the following settings apply:
DISABLE_REGISTRATION = false
ALLOW_ONLY_EXTERNAL_REGISTRATION = true
REQUIRE_EXTERNAL_REGISTRATION_CAPTCHA = false - Save the file with :x.
- Exit from the docker container with exit.
- To make the changes effective restart Gitea: docker restart vcs-gitea-app.
- Enter the Gitea Web-UI, log into the administrator account, open the user menu on the top left, select Site Administration, then select tab Authentication Sources.
- Press Add Authentication Source.
- Set the following fields:
| Authentication Type | OAuth2 |
| Authentication Name | keycloak |
| OAuth2 Provider | OpenID Connect |
| Client Id (Key) | vcs-gitea this is what you chose as "Client ID" when you created the client in the Keycloak Admin-UI |
| Client Secret | Enter the Keycloak Web-GUI and login as administrator. Then go to "Clients" and click on "vcs-gitea". Switch to the "Credentials" tab. In field "Secret" you find a long string consisting of hex numbers and hyphens. This is the "password" Gitea will use to authenticate with Keycloak. Copy it into your clipboard and paste it into the Gitea fields. |
| OpenID Connect Auto Discovery URL | Be sure that you replace the two variables "YOUR-PS4-HOSTNAME" and "REALM" in the following URL: https://YOUR-PS4-HOSTNAME/iam-keycloak/auth/realms/REALM/.well-known/openid-configuration |
- Press the green button Add Authentication Source. (Note: Should you receive a HTTP 500 error something is wrong with your Auto Discovery URL. Nevertheless your authentication source has been created. Enter the Authentication Source configuration for keycloak again and check. When pressing _Update Authentication Source_ connectivity to Keycloak will be checked again.
How to use it
Login to Gitea
- When logging in to Gitea at there is a button Sign in with OpenID connect at the bottom of the login screen. Press this button. (Note: Do not use the tab OpenId at the top of the screen.)
- You are now forwarded to Keycloak where you enter your credentials.
- You then are returned to Gitea.
- On your very first login you have to confirm auto-creating your account in Gitea. For that you just have to press Conform Login (if you want to use a different username and/or e-mail address as the one displayed you may change them before pressing the button). You are then returned to the Gitea login screen. If you now just press the Sign in with OpenID connect button you are immediately logged into Gitea without the need to enter username and password.
Connecting a local Git to Gitea
To establish a connection between a local git and Gitea without having to hardcode a password proceed as follows:
- In Gitea go to Settings -> Applications -> Manage Access Tokens -> Generate Token