Support handling usernames and DNs being changed in the directory

[Adambean]

I had looked into an almost identical issue on an unrelated project, in that what should happen if a vital attribute (such as "cn" or "uid") or a record DN entirely should alter. I outline this slightly in the Potential features section of the readme:

1. Specifying an attribute on the LDAP user in which this script could write back a user ID for each Gitlab instance.
   • This would mean user name (UID) changes in LDAP could be detected and synchronised automatically without user duplication happening.
   • It would likely be a string attribute in the form of instanceName:userId, for example athena:3 and demeter:15.
   • It could either be a multi-value attribute to handle multiple Gitlab instances, or a single-value attribute split by a semi-colon, for example athena:3;demeter:15.
2. Likely the same as the above but for groups too. (Group renaming.)

This can be evaded with manual intervention by an administrator whereby their Gitlab account would have its LDAP DN link adjusted prior to the user's next sign-in. I accept his is far from ideal as instances scale, particularly if an entire OU were to have all its users moved, thus changing all their DNs.

I can think of two ways to handle this without manual intervention, and welcome your thoughts to the debate.

Option 1: Add attribute to directory to record Gitlab user IDs in the directory

This tool will need an attribute within the LDAP to mark user objects with an ID number of their user entity in each Gitlab instance they're a part of.

This would be a fully portable solution however it would require a directory administrator to amend their schema, which is a huge ask for larger directories. (Particularly in the case of Active Directory whereby once an attribute is added to a schema it's there as good as permanently.)

There is also an inherent security risk because suddenly this tool would need write access to user objects the directory, even if it were just a specific attribute, where as it currently only requires read-only access.

Option 2: Track against a unique ID attribute in the LDAP user

Another approach would be to read a unique identifier in the LDAP user object and record this within the Gitlab user, possibly in the "extern_uid" or "note" field. This attribute would need to be somewhat permanent to the user such as a Unix user ID, GUID/UUID, or similar. Although this changes for each directory backend it could easily be a configurable option to this tool. Such attributes could be:

• "objectGUID" or "objectSid" for Active Directory, though using the SID wouldn't be useful if the user moved to a different domain in the forest.
• "nsUniqueID" for 389-DS/FreeIPA, though not all circumstances permit external applications to read this.
• "entryUUID" for OpenLDAP.
• "uidNumber" for any directory implementing the "posixAccount" object class on their users.

A potential problem would be storing it somewhere safe within the Gitlab user account. For example the "note" property can be arbitrarily adjusted by any Gitlab administrator so care/tagging would need to be used to warn administrators not to tamper with it. (Though if for some really rare reason a user's UUID or similar did change an administrator could come here to update it.)

It does however have an advantage in that the directory schema won't need changing, and this tool would not need write access to the directory's users.