Add documentation for licensing and group sync

- Improve directions and clarity for enabling group sync - Introduce new licensing guide for setting up premium features Changes: - Detailed steps and examples added for configuring OIDC claims - New `licensing.md` guide presents ways to add a license via UI and CLI - Introduced new enterprise SVG icon for better visual representation These updates aim to enhance the user experience and provide clear, actionable instructions.
coder · stirby · Oct 1, 2024 · Sep 24, 2024 · Sep 24, 2024 · Sep 24, 2024
commit 13f0a0ed94f1bf229f9bd9d0fb811068d480340e
diff --git a/docs/admin/auth.md b/docs/admin/auth.md
@@ -1,7 +1,5 @@
 # Authentication
 
-![OIDC with Coder Sequence Diagram](../images/oidc-sequence-diagram.svg).
-
 By default, Coder is accessible via password authentication. Coder does not
 recommend using password authentication in production, and recommends using an
 authentication provider with properly configured multi-factor authentication
@@ -252,33 +250,47 @@ CODER_TLS_CLIENT_KEY_FILE=/path/to/key.pem
 ## Group Sync (enterprise) (premium)
 
 If your OpenID Connect provider supports group claims, you can configure Coder
-to synchronize groups in your auth provider to groups within Coder.
+to synchronize groups in your auth provider to groups within Coder. To enable
+group sync, ensure that the `groups` claim is being sent by your OpenID
+provider. This may involve requesting an additional
+[scope](../reference/cli/server.md#--oidc-scopes) or additional configuration on
+the OpenID provider side.
 
-To enable group sync, ensure that the `groups` claim is set by adding the
-correct scope to request. If group sync is enabled, the user's groups will be
-controlled by the OIDC provider. This means manual group additions/removals will
-be overwritten on the next login.
+If group sync is enabled, the user's groups will be controlled by the OIDC
+provider. This means manual group additions/removals will be overwritten on the
+next user login.
 
-```env
-# as an environment variable
-CODER_OIDC_SCOPES=openid,profile,email,groups
-```
+There are two ways you can configure group sync:
 
-```shell
-# as a flag
---oidc-scopes openid,profile,email,groups
+<div class="tabs">
+
+## Server Flags
+
+First, confirm that your OIDC provider is sending the `groups` claim by logging
+in with OIDC and visiting the following URL:
+
+```text
+https://[coder.example.com]/api/v2/debug/[your-username]/debug-link
 ```
 
-With the `groups` scope requested, we also need to map the `groups` claim name.
-Coder recommends using `groups` for the claim name. This step is necessary if
-your **scope's name** is something other than `groups`.
+You should see a field, followed by a list of the user's OIDC groups in the
+response. This is the
+[claim](https://openid.net/specs/openid-connect-core-1_0.html#Claims) sent by
+the OIDC provider. See [Troubleshooting](#troubleshooting-grouprole-sync) to
+debug this.
 
-```env
+> Depending on the OIDC provider, this claim may be named differently. Common
+> ones include `groups`, `memberOf`, and `roles`.
+
+Next configure the Coder server to read groups from the claim name with the
+[OIDC group field](../reference/cli/server.md#--oidc-group-field) server flag:
+
+```sh
 # as an environment variable
 CODER_OIDC_GROUP_FIELD=groups
 ```
 
-```shell
+```sh
 # as a flag
 --oidc-group-field groups
 ```
@@ -288,14 +300,16 @@ names in Coder and removed from groups that the user no longer belongs to.
 
 For cases when an OIDC provider only returns group IDs ([Azure AD][azure-gids])
 or you want to have different group names in Coder than in your OIDC provider,
-you can configure mapping between the two.
+you can configure mapping between the two with the
+[OIDC group mapping](../reference/cli/server.md#--oidc-group-mapping) server
+flag.
 
-```env
+```sh
 # as an environment variable
 CODER_OIDC_GROUP_MAPPING='{"myOIDCGroupID": "myCoderGroupName"}'
 ```
 
-```shell
+```sh
 # as a flag
 --oidc-group-mapping '{"myOIDCGroupID": "myCoderGroupName"}'
 ```
@@ -313,11 +327,17 @@ coder:
 From the example above, users that belong to the `myOIDCGroupID` group in your
 OIDC provider will be added to the `myCoderGroupName` group in Coder.
 
-> **Note:** Groups are only updated on login.
-
 [azure-gids]:
 	https://github.com/MicrosoftDocs/azure-docs/issues/59766#issuecomment-664387195
 
+## Runtime (Organizations)
+
+For deployments with multiple [organizations](./organizations.md), you can must
+configure group sync at the organization level. In future Coder versions, you
+will be able to configure this in the UI. For now, you can use CLI commands.
+
+</div>
+
 ### Group allowlist
 
 You can limit which groups from your identity provider can log in to Coder with

diff --git a/docs/images/add-license-ui.png b/docs/images/add-license-ui.png
diff --git a/docs/images/icons/enterprise.svg b/docs/images/icons/enterprise.svg
diff --git a/docs/licensing.md b/docs/licensing.md
@@ -0,0 +1,42 @@
+# Licensing
+
+Coder is free to use and includes some features that are only accessible with a
+paid license. See our [pricing page](https://coder.com/pricing) for a
+distinction.
+
+To try Premium features, you can [request a trial](https://coder.com/trial) or
+[contact sales](https://coder.com/contact).
+
+## Adding your license key
+
+There are two ways to add an enterprise license to a Coder deployment:
+
+<div class="tabs">
+
+### Coder UI
+
+First, ensure you have a license key
+([request a trial](https://coder.com/trial)).
+
+With an `Owner` account, navigate to `Deployment -> Licenses`, `Add a license`
+then drag or select the license file with the `jwt` extension.
+
+![Add License UI](./images/add-license-ui.png)
+
+### Coder CLI
+
+First, ensure you have a license key
+([request a trial](https://coder.com/trial)) and the
+[Coder CLI](./install/index.md) installed.
+
+1. Save your license key to disk and make note of the path
+2. Open a terminal
+3. Ensure you are logged into your Coder deployment
+
+   `coder login <access url>`
+
+4. Run
+
+   `coder licenses add -f <path to your license key>`
+
+</div>
diff --git a/docs/manifest.json b/docs/manifest.json
@@ -562,6 +562,12 @@
 				}
 			]
 		},
+		{
+			"title": "Licensing",
+			"description": "Learn how to enable Premium features",
+			"path": "./licensing.md",
+			"icon_path": "./images/icons/enterprise.svg"
+		},
 		{
 			"title": "Contributing",
 			"description": "Learn how to contribute to Coder",