docker-gitlab/docs/keycloak-idp.md

# Integrate Keycloak as a IDP with GitLab

In this document, we will explain how to set up Keycloak and integrate it into GitLab.

## Setting up Keycloak

First, you need a client in Keycloak to authenticate with GitLab. You can start Keycloak by running `docker-compose up -d keycloak`.

When Keycloak is running, log in using the `Administration console`. You can visit the Keycloak on the [local IP](http://localhost:10081) of your laptop.

![Keycloak Home](images/keycloak-home.png)

Next, create a client.

![Keycloak client](images/keycloak-client.png)

Fill in the following variables:

![Keycloak client creation](images/keycloak-client-creation.png)

Make access type confidential and enable service accounts and authorization.

![Keycloak client creation](images/keycloak-client-creation2.png)

Next, click save, get the client secret generated by Keycloak and start filling out the variables for GitLab in the docker-compose file.

![Keycloak client secret](images/keycloak-secret.png)

Set the following in the docker-compose file:

```yaml
    - OAUTH2_GENERIC_APP_SECRET=<your-client-secret>
    - OAUTH2_GENERIC_CLIENT_SITE=http://<your-ip-address>:10081
    - OAUTH2_GENERIC_CLIENT_USER_INFO_URL=http://<your-ip-address>:10081/auth/realms/master/protocol/openid-connect/userinfo
    - OAUTH2_GENERIC_CLIENT_AUTHORIZE_URL=http://<your-ip-address>:10081/auth/realms/master/protocol/openid-connect/auth
    - OAUTH2_GENERIC_CLIENT_TOKEN_URL=http://<your-ip-address>:10081/auth/realms/master/protocol/openid-connect/token
    - OAUTH2_GENERIC_CLIENT_END_SESSION_ENDPOINT=http://<your-ip-address>:10081/auth/realms/master/protocol/openid-connect/logout
```

`<your-ip-address>` is the IP address of your keycloak. For this example this would be your IP address, but if your Keycloak existed elsewhere for your deployment `<your-ip-address>` would be different as would the port and the realm. 

The following must also be configured:

```yaml
    - OAUTH2_GENERIC_USER_UID='preffered_usename'
    - OAUTH2_GENERIC_USER_NAME='name'
    - OAUTH2_GENERIC_USER_EMAIL='email'    
```

The values will be different for your deployment. Navigate Keycloak's UI, select `Clients`, click `[your client]`, then open the `Client Scopes` tab, then open `Evaluate` sub-tab, enter a username you know in the `User` field, select the match, then `Generate Access Token` to see the values you need to configure. 

Also, make sure the following variables are filled in the docker-compose file:

```yaml
    - GITLAB_HOST='<your-ip-address>'
    ...
    - OAUTH_ENABLED=true
    - OAUTH_AUTO_SIGN_IN_WITH_PROVIDER=Keycloak
    - OAUTH_ALLOW_SSO=Keycloak
    - OAUTH_BLOCK_AUTO_CREATED_USERS=false
    - OAUTH_AUTO_LINK_LDAP_USER=false
    - OAUTH_AUTO_LINK_SAML_USER=false
```

`<your-ip-address>` is the IP address of your GitLab for this example this would be the your IP address, but if your GitLab was to be proxied or deployed elsewhere `<your-ip-address>` would be another value appropriate for your deployment.

GitLab does not allow login from users in Keycloak with an empty email or name. To prevent this, you can create a new user in Keycloak or you can add email and name for the admin account.

Visit the `Users` tab and click on `View all users` to modify the Admin user.

![keycloak-users](images/keycloak-users.png)

Modify the `Email`, `First name` and `Last Name` fields.
![admin-account](images/keycloak-admin-acc.png)

Deploy GitLab, Reddis and PostgreSQL by running the following command: `docker-compose up -d gitlab redis postgresql`.

You can now login on the local GitLab instance with with Keycloak on your [local IP](http://localhost:10080).

![gitlab-login](images/keycloak-gitlab-login.png)