From cff36cfb54b2d8ec45c8599135228178f0fe28b8 Mon Sep 17 00:00:00 2001
From: Eric Paulsen <ericpaulsen@coder.com>
Date: Mon, 30 Jan 2023 15:08:46 -0500
Subject: [PATCH] docs: add GitLab auth docs

---
 docs/admin/auth.md | 65 ++++++++++++++++++++++++++++++++++++++--------
 1 file changed, 54 insertions(+), 11 deletions(-)

diff --git a/docs/admin/auth.md b/docs/admin/auth.md
index 99a0f0b57b08c..73d7bdd062801 100644
--- a/docs/admin/auth.md
+++ b/docs/admin/auth.md
@@ -46,13 +46,52 @@ CODER_OAUTH2_GITHUB_ALLOW_EVERYONE=true
 
 Once complete, run `sudo service coder restart` to reboot Coder.
 
-## OpenID Connect with Google
+## GitLab
+
+### Step 1: Configure the OAuth application in your GitLab instance
+
+First, [register a GitLab OAuth application](https://docs.gitlab.com/ee/integration/oauth_provider.html). GitLab will ask you for the following parameter:
+
+- **Redirect URI**: Set to `https://coder.domain.com/api/v2/users/oidc/callback`
+
+### Step 2: Configure Coder with the OpenID Connect credentials
+
+Navigate to your Coder host and run the following command to start up the Coder
+server:
+
+```console
+coder server --oidc-issuer-url="https://gitlab.com" --oidc-email-domain="your-domain-1,your-domain-2" --oidc-client-id="533...des" --oidc-client-secret="G0CSP...7qSM"
+```
+
+Alternatively, if you are running Coder as a system service, you can achieve the
+same result as the command above by adding the following environment variables
+to the `/etc/coder.d/coder.env` file:
+
+```console
+CODER_OIDC_ISSUER_URL="https://gitlab.com"
+CODER_OIDC_EMAIL_DOMAIN="your-domain-1,your-domain-2"
+CODER_OIDC_CLIENT_ID="533...des"
+CODER_OIDC_CLIENT_SECRET="G0CSP...7qSM"
+```
+
+Once complete, run `sudo service coder restart` to reboot Coder.
 
-> We describe how to set up the most popular OIDC provider, Google, but any (Okta, Azure Active Directory, GitLab, Auth0, etc.) may be used.
+### Additional Notes
+
+GitLab maintains configuration settings for OIDC applications at the following URL:
+
+```console
+https://gitlab.com/.well-known/openid-configuration
+```
+
+If you are using a self-hosted GitLab instance, replace `gitlab.com` in the above URL
+with your internal domain. The same will apply for the `OIDC_ISSUER_URL` variable.
+
+## OpenID Connect with Google
 
 ### Step 1: Configure the OAuth application on Google Cloud
 
-First, [register a Google OAuth app](https://support.google.com/cloud/answer/6158849?hl=en). Google will ask you for the following Coder parameters:
+First, [register a Google OAuth application](https://support.google.com/cloud/answer/6158849?hl=en). Google will ask you for the following Coder parameters:
 
 - **Authorized JavaScript origins**: Set to your Coder domain (e.g. `https://coder.domain.com`)
 - **Redirect URIs**: Set to `https://coder.domain.com/api/v2/users/oidc/callback`
@@ -79,14 +118,7 @@ CODER_OIDC_CLIENT_SECRET="G0CSP...7qSM"
 
 Once complete, run `sudo service coder restart` to reboot Coder.
 
-> When a new user is created, the `preferred_username` claim becomes the username. If this claim is empty, the email address will be stripped of the domain, and become the username (e.g. `example@coder.com` becomes `example`).
-
-If your OpenID Connect provider requires client TLS certificates for authentication, you can configure them like so:
-
-```console
-CODER_TLS_CLIENT_CERT_FILE=/path/to/cert.pem
-CODER_TLS_CLIENT_KEY_FILE=/path/to/key.pem
-```
+## OIDC Claims
 
 Coder requires all OIDC email addresses to be verified by default. If the `email_verified` claim is present in the token response from the identity provider, Coder will validate that its value is `true`.
 If needed, you can disable this behavior with the following setting:
@@ -97,6 +129,8 @@ CODER_OIDC_IGNORE_EMAIL_VERIFIED=true
 
 > **Note:** This will cause Coder to implicitly treat all OIDC emails as "verified".
 
+When a new user is created, the `preferred_username` claim becomes the username. If this claim is empty, the email address will be stripped of the domain, and become the username (e.g. `example@coder.com` becomes `example`).
+
 ## SCIM (enterprise)
 
 Coder supports user provisioning and deprovisioning via SCIM 2.0 with header
@@ -107,3 +141,12 @@ auth key and supply it the Coder server.
 ```console
 CODER_SCIM_API_KEY="your-api-key"
 ```
+
+## TLS
+
+If your OpenID Connect provider requires client TLS certificates for authentication, you can configure them like so:
+
+```console
+CODER_TLS_CLIENT_CERT_FILE=/path/to/cert.pem
+CODER_TLS_CLIENT_KEY_FILE=/path/to/key.pem
+```