rebase on main

coder · matifali · May 22, 2024 · May 23, 2024 · May 23, 2024 · May 23, 2024
commit 56ef29ed0471e61866edb50ff0876b0797576dea
diff --git a/docs/admin-old/auth.md b/docs/admin-old/auth.md
@@ -0,0 +1,250 @@
+# 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
+(MFA). It is your responsibility to ensure the auth provider enforces MFA
+correctly.
+
+The following steps explain how to set up GitHub OAuth or OpenID Connect.
+
+## GitHub
+
+### Step 1: Configure the OAuth application in GitHub
+
+First,
+[register a GitHub OAuth app](https://developer.github.com/apps/building-oauth-apps/creating-an-oauth-app/).
+GitHub will ask you for the following Coder parameters:
+
+- **Homepage URL**: Set to your Coder deployments
+  [`CODER_ACCESS_URL`](../cli/server.md#--access-url) (e.g.
+  `https://coder.domain.com`)
+- **User Authorization Callback URL**: Set to `https://coder.domain.com`
+
+> Note: If you want to allow multiple coder deployments hosted on subdomains
+> e.g. coder1.domain.com, coder2.domain.com, to be able to authenticate with the
+> same GitHub OAuth app, then you can set **User Authorization Callback URL** to
+> the `https://domain.com`
+
+Note the Client ID and Client Secret generated by GitHub. You will use these
+values in the next step.
+
+Coder will need permission to access user email addresses. Find the "Account
+Permissions" settings for your app and select "read-only" for "Email addresses".
+
+### Step 2: Configure Coder with the OAuth credentials
+
+Navigate to your Coder host and run the following command to start up the Coder
+server:
+
+```shell
+coder server --oauth2-github-allow-signups=true --oauth2-github-allowed-orgs="your-org" --oauth2-github-client-id="8d1...e05" --oauth2-github-client-secret="57ebc9...02c24c"
+```
+
+> For GitHub Enterprise support, specify the
+> `--oauth2-github-enterprise-base-url` flag.
+
+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:
+
+```env
+CODER_OAUTH2_GITHUB_ALLOW_SIGNUPS=true
+CODER_OAUTH2_GITHUB_ALLOWED_ORGS="your-org"
+CODER_OAUTH2_GITHUB_CLIENT_ID="8d1...e05"
+CODER_OAUTH2_GITHUB_CLIENT_SECRET="57ebc9...02c24c"
+```
+
+**Note:** To allow everyone to signup using GitHub, set:
+
+```env
+CODER_OAUTH2_GITHUB_ALLOW_EVERYONE=true
+```
+
+Once complete, run `sudo service coder restart` to reboot Coder.
+
+If deploying Coder via Helm, you can set the above environment variables in the
+`values.yaml` file as such:
+
+```yaml
+coder:
+  env:
+    - name: CODER_OAUTH2_GITHUB_ALLOW_SIGNUPS
+      value: "true"
+    - name: CODER_OAUTH2_GITHUB_CLIENT_ID
+      value: "533...des"
+    - name: CODER_OAUTH2_GITHUB_CLIENT_SECRET
+      value: "G0CSP...7qSM"
+    # If setting allowed orgs, comment out CODER_OAUTH2_GITHUB_ALLOW_EVERYONE and its value
+    - name: CODER_OAUTH2_GITHUB_ALLOWED_ORGS
+      value: "your-org"
+    # If allowing everyone, comment out CODER_OAUTH2_GITHUB_ALLOWED_ORGS and it's value
+    #- name: CODER_OAUTH2_GITHUB_ALLOW_EVERYONE
+    #  value: "true"
+```
+
+To upgrade Coder, run:
+
+```shell
+helm upgrade <release-name> coder-v2/coder -n <namespace> -f values.yaml
+```
+
+> We recommend requiring and auditing MFA usage for all users in your GitHub
+> organizations. This can be enforced from the organization settings page in the
+> "Authentication security" sidebar tab.
+
+## OpenID Connect
+
+The following steps through how to integrate any OpenID Connect provider (Okta,
+Active Directory, etc.) to Coder.
+
+### Step 1: Set Redirect URI with your OIDC provider
+
+Your OIDC provider 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:
+
+```shell
+coder server --oidc-issuer-url="https://issuer.corp.com" --oidc-email-domain="your-domain-1,your-domain-2" --oidc-client-id="533...des" --oidc-client-secret="G0CSP...7qSM"
+```
+
+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:
+
+```env
+CODER_OIDC_ISSUER_URL="https://issuer.corp.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.
+
+If deploying Coder via Helm, you can set the above environment variables in the
+`values.yaml` file as such:
+
+```yaml
+coder:
+  env:
+    - name: CODER_OIDC_ISSUER_URL
+      value: "https://issuer.corp.com"
+    - name: CODER_OIDC_EMAIL_DOMAIN
+      value: "your-domain-1,your-domain-2"
+    - name: CODER_OIDC_CLIENT_ID
+      value: "533...des"
+    - name: CODER_OIDC_CLIENT_SECRET
+      value: "G0CSP...7qSM"
+```
+
+To upgrade Coder, run:
+
+```shell
+helm upgrade <release-name> coder-v2/coder -n <namespace> -f values.yaml
+```
+
+## OIDC Claims
+
+When a user logs in for the first time via OIDC, Coder will merge both the
+claims from the ID token and the claims obtained from hitting the upstream
+provider's `userinfo` endpoint, and use the resulting data as a basis for
+creating a new user or looking up an existing user.
+
+To troubleshoot claims, set `CODER_VERBOSE=true` and follow the logs while
+signing in via OIDC as a new user. Coder will log the claim fields returned by
+the upstream identity provider in a message containing the string
+`got oidc claims`, as well as the user info returned.
+
+> **Note:** If you need to ensure that Coder only uses information from the ID
+> token and does not hit the UserInfo endpoint, you can set the configuration
+> option `CODER_OIDC_IGNORE_USERINFO=true`.
+
+### Email Addresses
+
+By default, Coder will look for the OIDC claim named `email` and use that value
+for the newly created user's email address.
+
+If your upstream identity provider users a different claim, you can set
+`CODER_OIDC_EMAIL_FIELD` to the desired claim.
+
+> **Note** If this field is not present, Coder will attempt to use the claim
+> field configured for `username` as an email address. If this field is not a
+> valid email address, OIDC logins will fail.
+
+### Email Address Verification
+
+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:
+
+```env
+CODER_OIDC_IGNORE_EMAIL_VERIFIED=true
+```
+
+> **Note:** This will cause Coder to implicitly treat all OIDC emails as
+> "verified", regardless of what the upstream identity provider says.
+
+### Usernames
+
+When a new user logs in via OIDC, Coder will by default use the value of the
+claim field named `preferred_username` as the the username.
+
+If your upstream identity provider uses a different claim, you can set
+`CODER_OIDC_USERNAME_FIELD` to the desired claim.
+
+> **Note:** 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`).
+> To avoid conflicts, Coder may also append a random word to the resulting
+> username.
+
+## OIDC Login Customization
+
+If you'd like to change the OpenID Connect button text and/or icon, you can
+configure them like so:
+
+```env
+CODER_OIDC_SIGN_IN_TEXT="Sign in with Gitea"
+CODER_OIDC_ICON_URL=https://gitea.io/images/gitea.png
+```
+
+To change the icon and text above the OpenID Connect button, see application
+name and logo url in [appearance](./appearance.md) settings.
+
+## Disable Built-in Authentication
+
+To remove email and password login, set the following environment variable on
+your Coder deployment:
+
+```env
+CODER_DISABLE_PASSWORD_AUTH=true
+```
+
+## SCIM (enterprise)
+
+Coder supports user provisioning and deprovisioning via SCIM 2.0 with header
+authentication. Upon deactivation, users are
+[suspended](./users.md#suspend-a-user) and are not deleted.
+[Configure](./configure.md) your SCIM application with an auth key and supply it
+the Coder server.
+
+```env
+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:
+
+```env
+CODER_TLS_CLIENT_CERT_FILE=/path/to/cert.pem
+CODER_TLS_CLIENT_KEY_FILE=/path/to/key.pem
+```
diff --git a/docs/admin-old/healthcheck.md b/docs/admin-old/healthcheck.md
diff --git a/docs/admin-old/users.md b/docs/admin-old/users.md
@@ -0,0 +1,72 @@
+# Users
+
+This article walks you through the user roles available in Coder and creating
+and managing users.
+
+## Roles
+
+Coder offers these user roles in the community edition:
+
+|                                                       | Auditor | User Admin | Template Admin | Owner |
+| ----------------------------------------------------- | ------- | ---------- | -------------- | ----- |
+| Add and remove Users                                  |         | ✅         |                | ✅    |
+| Manage groups (enterprise)                            |         | ✅         |                | ✅    |
+| Change User roles                                     |         |            |                | ✅    |
+| Manage **ALL** Templates                              |         |            | ✅             | ✅    |
+| View **ALL** Workspaces                               |         |            | ✅             | ✅    |
+| Update and delete **ALL** Workspaces                  |         |            |                | ✅    |
+| Run [external provisioners](./provisioners.md)        |         |            | ✅             | ✅    |
+| Execute and use **ALL** Workspaces                    |         |            |                | ✅    |
+| View all user operation [Audit Logs](./audit-logs.md) | ✅      |            |                | ✅    |
+
+A user may have one or more roles. All users have an implicit Member role that
+may use personal workspaces.
+
+## Security notes
+
+A malicious Template Admin could write a template that executes commands on the
+host (or `coder server` container), which potentially escalates their privileges
+or shuts down the Coder server. To avoid this, run
+[external provisioners](./provisioners.md).
+
+In low-trust environments, we do not recommend giving users direct access to
+edit templates. Instead, use
+[CI/CD pipelines to update templates](../templates/change-management.md) with
+proper security scans and code reviews in place.
+
+## User status
+
+Coder user accounts can have different status types: active, dormant, and
+suspended.
+
+### Active user
+
+An _active_ user account in Coder is the default and desired state for all
+users. When a user's account is marked as _active_, they have complete access to
+the Coder platform and can utilize all of its features and functionalities
+without any limitations. Active users can access workspaces, templates, and
+interact with Coder using CLI.
+
+### Dormant user
+
+A user account is set to _dormant_ status when they have not yet logged in, or
+have not logged into the Coder platform for the past 90 days. Once the user logs
+in to the platform, the account status will switch to _active_.
+
+Dormant accounts do not count towards the total number of licensed seats in a
+Coder subscription, allowing organizations to optimize their license usage.
+
+### Suspended user
+
+When a user's account is marked as _suspended_ in Coder, it means that the
+account has been temporarily deactivated, and the user is unable to access the
+platform.
+
+Only user administrators or owners have the necessary permissions to manage
+suspended accounts and decide whether to lift the suspension and allow the user
+back into the Coder environment. This level of control ensures that
+administrators can enforce security measures and handle any compliance-related
+issues promptly.
+
+Similar to dormant users, suspended users do not count towards the total number
+of licensed seats.
diff --git a/docs/admin/infrastructure/README.md b/docs/admin/infrastructure/README.md
@@ -4,10 +4,13 @@ Guides for setting up and scaling Coder infrastructure.
 
 ## Architecture
 
-Coder is a self-hosted platform that runs on your own infrastructure. For large deployments, we recommend running the control plane on Kubernetes. Workspaces can be run as VMs or Kubernetes pods. The control plane (`coderd`) runs in a single region. However, workspace proxies, provisioners, and workspaces can run across regions or even cloud providers.
+Coder is a self-hosted platform that runs on your own infrastructure. For large deployments, we recommend running the control plane on Kubernetes. Workspaces can be run as VMs or Kubernetes pods. The control plane (`coderd`) runs in a single region. However, workspace proxies, provisioners, and workspaces can run across regions or even cloud providers for the optimal developer experience.
+
+Learn more about Coder's architecture and concepts: [Concepts](./architecture.md)
 
 ### Kubernetes
 
+- [Kubernetes Best Practices](#)
 - [Multi-region architecture](#)
 - Reference Architectures
 -