Gerrit migration from LDAP to OIDC using Keycloak

This is a rather cumbersome guide because lots of moving parts must be aligned perfectly together to make this work. At the company I work at we are 12 people that uses Gerrit. I needed to have these 12 people, and some of them were from different departments, to sit in a virtual meeting at the same time. Thankfully this was done over the internet, but it did take some time to find 30 minutes in their busy schedules to run through a guide on migrating their users from LDAP to OIDC. This is what this guide will be about: How to migrate your users. Rest assured that if anything goes wrong, you will hopefully be able to revert back to LDAP. This is what we did in order to migrate them. Please read the guide carefully and remember that this is what we did. These steps might not be suitable or workable on your installation. Be aware of this before writing to me to complain about it :)

  1. Users must log into Gerrit using their LDAP username and password. Keep them signed in and let them stay there for the duration of the guide. They should not close down this browser/window.
  2. They must now go into their settings and they must add a new email address such as initials+gerrit@companyname.com. Why is this step necessary? Usually when people use OIDC/SAML/whatever the same email cannot be used twice if it matches the email from LDAP. The error message ‘Forbidden’ will show up when the user tries to access Gerrit using OIDC. If you look in the logs when they try to log on with OIDC, it will say that the email address already exists.
  3. Now that their new email has been verified, you tell the users to remove their old email address (the one that is not initials+gerrit@companyname.com).
  4. Now modify the Gerrit configuration to use OIDC. Restart the service afterwards.
  5. Users must now start a new browser/private browser/container etc. and log in using OIDC. They must also enter settings and input a new username. The old username cannot be used. This is an issue - albeit it is a small one.
  6. The administrators who have signed in previously with LDAP, can still modify OIDC users and such to assign them to appropriate groups and roles for accessing repositories.
  7. Done.

Can you consider this a migration? Well, not exactly. You’re actually creating new users, but you cannot create these new users if their old email from LDAP matches the new one in OIDC.