## Summary **Batch B of Phase 3** of the H1 → front-matter migration (`DOCS-484`; parent `DOCS-477`), the editorial follow-up to Batch A (#28030). For the **124** hand-authored pages whose leading body H1 differed from the manifest nav label, this promotes the richer body H1 to the front-matter **page title** and drops the duplicate H1, while keeping the short manifest **label** as the sidebar entry. Policy agreed with the docs owner: - Short sidebar labels win. Duplicate sidebar labels are acceptable. - Identical **page titles** across two pages are not. On a collision, rename the non-generated page's title. ## Page-title collisions resolved Promoting the H1 created 4 page-title collisions; each is disambiguated by renaming the non-generated / secondary page (sidebar labels left unchanged): | page | sidebar label | body H1 | → page title | |------|---------------|---------|--------------| | `install/index.md` | Install | Installing Coder | **Install Coder in your infrastructure** | | `install/cli.md` | Coder CLI | Installing Coder | **Install the Coder CLI** | | `ai-gateway/clients/jetbrains.md` | JetBrains | JetBrains IDEs | **JetBrains** | | `workspace-access/web-ides.md` | Web IDEs and Coder Apps | Web IDEs | Web IDEs *(kept — primary user guide)* | | `extending-templates/web-ides.md` | Web IDEs and Coder Apps | Web IDEs | **Web IDEs in templates** | | `workspace-management.md` | Workspace Management | Workspaces | **Manage workspaces** *(vs generated `api/workspaces.md`)* | These titles are the only non-mechanical editorial calls in this PR. ## Deliberately excluded: generated pages `admin/security/audit-logs.md` and `admin/setup/configuration-reference.md` are `make gen` outputs (`auditdocgen` / `configdocgen`) that Phase 2 did **not** update, so a hand-added title would be reverted on the next generation. They're excluded here and need their generators taught to emit front matter first (Phase 2 pattern), tracked as `DOCS-631`. Batch A (#28030) had the same issue for three other generated pages; it has been corrected there too. ## Verification AI was the primary author of this PR (see disclosure below); per the [AI Contribution Guidelines](https://coder.com/docs/about/contributing/AI_CONTRIBUTING) here is the manual verification. - Promote = set front-matter `title` to the body H1 (or the disambiguated title above) and remove that one duplicate H1. No other body prose is reflowed. - Every added front-matter block parses as YAML; all files pass `pnpm check-docs` (markdownlint-cli2 + table formatter): `Summary: 0 error(s)`. - Removing the H1 orphaned one in-page fragment (`[MCP](#mcp)` in `ai-gateway/mcp.md`), now repointed. A cross-file fragment audit into the retitled pages found no real breakage. Anchor-change note Unlike Batch A (title unchanged, a rendered no-op), Batch B changes each page's effective title from the manifest label to the body H1, so the rendered H1 **anchor slug changes**. An audit of cross-file `.md#fragment` links into these pages surfaced no links that break as a result (the only hits were false positives against a still-present `## TLS & Reverse Proxy` heading). Same-file fragments are enforced by markdownlint MD051, which is green. ## Title casing (follow-up, DOCS-742) A follow-up commit puts the promoted titles into sentence case and removes leading gerunds (for example, `Managing workspace schedules` → `Manage workspace schedules`): 57 of the 120 titles changed, the other 63 were already compliant. Proper nouns and branded names (Coder Validated Architecture, JetBrains, File Browser, Dev Containers, Island), acronyms (API, CLI, IDE, MCP, OIDC, URL, UI, CI/CD), the Premium license tier, and maturity labels (Beta, Experimental) are preserved. The four `Nk-users` pages become `Reference architecture: up to N users` (lowercase, matching the CVA landing page's own usage); the CVA landing page keeps its branded title. `pnpm check-docs`: `Summary: 0 error(s)`. Linear: DOCS-484, DOCS-742 > This PR was created with AI assistance (Coder Agents).
6.9 KiB
title
| title |
|---|
| 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
Set the following environment variables on your Coder deployment and restart Coder:
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"
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_LOG_FILTER=".*got oidc claims.*" 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
usernameas 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:
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.combecomesexample). 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:
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 settings.
Configure Refresh Tokens
By default, OIDC access tokens typically expire after a short period. This is typically after one hour, but varies by provider.
Without refresh tokens, users will be automatically logged out when their access token expires.
Follow Configure OIDC Refresh Tokens for provider-specific steps.
The general steps to configure persistent user sessions are:
-
Configure your Coder OIDC settings:
For most providers, add the
offline_accessscope:CODER_OIDC_SCOPES=openid,profile,email,offline_accessFor Google, add auth URL parameters (
CODER_OIDC_AUTH_URL_PARAMS) too:CODER_OIDC_SCOPES=openid,profile,email CODER_OIDC_AUTH_URL_PARAMS='{"access_type": "offline", "prompt": "consent"}' -
Configure your identity provider to issue refresh tokens.
-
After configuration, have users log out and back in once to obtain refresh tokens
Important
Misconfigured refresh tokens can lead to frequent user authentication prompts.
Disable Built-in Authentication
To remove email and password login, set the following environment variable on your Coder deployment:
CODER_DISABLE_PASSWORD_AUTH=true
SCIM
Important
SCIM is a Premium feature (learn more).
Coder's SCIM 2.0 implementation is not a fully certified or guaranteed implementation of the SCIM 2.0 specification. It is intended to cover common user provisioning and deprovisioning flows with the major identity providers (Okta, Microsoft Entra ID, etc.). Specific attributes, endpoints, or behaviors required by your IdP may not be supported, and compatibility may change between releases. If you depend on a specific SCIM behavior, contact us before rolling it out broadly. See coder/coder#15830 for tracked gaps and ongoing work.
Coder supports user provisioning and deprovisioning via SCIM 2.0 with header authentication. Upon deactivation, users are suspended and are not deleted. Configure your SCIM application with an auth key and supply it the Coder server.
CODER_SCIM_AUTH_HEADER="your-api-key"
SCIM 2.0 handler
Coder includes an opt-in SCIM 2.0 handler that follows RFC 7644 and has been verified against an external SCIM 2.0 compliance suite. It supports the following:
- User provisioning and deprovisioning
- User listing
To opt in, set:
CODER_SCIM_USE_LEGACY=false
This is also available as the --scim-use-legacy server flag and the scimUseLegacy YAML option.
Changing it requires a restart of the Coder server.
Behavior notes:
- Coder never hard-deletes users.
DELETE /scim/v2/Users/{id}and deactivation (active: false) both suspend the user. - Re-activating or re-creating a previously suspended user places them in the dormant state, and they become active again on their next login.
- Usernames are immutable. Attempts to change
userNameviaPUTorPATCHreturn amutabilityerror.
The SCIM 2.0 handler will eventually become the default behavior.
TLS
If your OpenID Connect provider requires client TLS certificates for authentication, you can configure them like so:
CODER_TLS_CLIENT_CERT_FILE=/path/to/cert.pem
CODER_TLS_CLIENT_KEY_FILE=/path/to/key.pem