Skip to content

Commit 5c16079

Browse files
EdwardAngertEdwardAngert
authored
docs: add more specific steps and information about oidc refresh tokens (#18336)
closes #18307 relates to #18318 preview: - [refresh-tokens](https://coder.com/docs/@18307-refresh-tokens/admin/users/oidc-auth/refresh-tokens) - [configuring-okta](https://coder.com/docs/@18307-refresh-tokens/tutorials/configuring-okta) ~(not sure why @Emyrk 's photo is so huge there though)~ ✔️ - [x] removed from [idp-sync](https://coder.com/docs/@18307-refresh-tokens/admin/users/idp-sync) to do: - move keycloak - add ping federate and azure - edit text (possibly placeholders for now - I want to see how it all relates and edit it again. right now, there's a note about the same thing in every section in way that's not super helpful/necessary) - ~convert some paragraphs to OL~ calling this out of scope for now --------- Co-authored-by: EdwardAngert <17991901+EdwardAngert@users.noreply.github.com>
1 parent 0950077 commit 5c16079

File tree

19 files changed

+362
-117
lines changed

19 files changed

+362
-117
lines changed

‎docs/README.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -49,7 +49,7 @@ Remote development offers several benefits for users and administrators, includi
4949
- **Increased security**
5050

5151
- Centralize source code and other data onto private servers or cloud services instead of local developers' machines.
52-
- Manage users and groups with [SSO](./admin/users/oidc-auth.md) and [Role-based access controlled (RBAC)](./admin/users/groups-roles.md#roles).
52+
- Manage users and groups with [SSO](./admin/users/oidc-auth/index.md) and [Role-based access controlled (RBAC)](./admin/users/groups-roles.md#roles).
5353

5454
- **Improved compatibility**
5555

‎docs/admin/external-auth.md renamed to ‎docs/admin/external-auth/index.md

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -65,7 +65,7 @@ Reference the documentation for your chosen provider for more information on how
6565

6666
### Workspace CLI
6767

68-
Use [`external-auth`](../reference/cli/external-auth.md) in the Coder CLI to access a token within the workspace:
68+
Use [`external-auth`](../../reference/cli/external-auth.md) in the Coder CLI to access a token within the workspace:
6969

7070
```shell
7171
coder external-auth access-token <USER_DEFINED_ID>
@@ -255,7 +255,7 @@ Note that the redirect URI must include the value of `CODER_EXTERNAL_AUTH_0_ID`
255255

256256
### JFrog Artifactory
257257

258-
Visit the [JFrog Artifactory](../admin/integrations/jfrog-artifactory.md) guide for instructions on how to set up for JFrog Artifactory.
258+
Visit the [JFrog Artifactory](../../admin/integrations/jfrog-artifactory.md) guide for instructions on how to set up for JFrog Artifactory.
259259

260260
## Self-managed Git providers
261261

@@ -293,13 +293,13 @@ CODER_EXTERNAL_AUTH_0_SCOPES="repo:read repo:write write:gpg_key"
293293
- Enable fine-grained access to specific repositories or a subset of
294294
permissions for security.
295295

296-
![Register GitHub App](../images/admin/github-app-register.png)
296+
![Register GitHub App](../../images/admin/github-app-register.png)
297297

298298
1. Adjust the GitHub app permissions. You can use more or fewer permissions than
299299
are listed here, this example allows users to clone
300300
repositories:
301301

302-
![Adjust GitHub App Permissions](../images/admin/github-app-permissions.png)
302+
![Adjust GitHub App Permissions](../../images/admin/github-app-permissions.png)
303303

304304
| Name | Permission | Description |
305305
|---------------|--------------|--------------------------------------------------------|
@@ -312,7 +312,7 @@ CODER_EXTERNAL_AUTH_0_SCOPES="repo:read repo:write write:gpg_key"
312312
1. Install the App for your organization. You may select a subset of
313313
repositories to grant access to.
314314

315-
![Install GitHub App](../images/admin/github-app-install.png)
315+
![Install GitHub App](../../images/admin/github-app-install.png)
316316

317317
## Multiple External Providers (Premium)
318318

‎docs/admin/infrastructure/architecture.md

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -108,10 +108,10 @@ Users will likely need to pull source code and other artifacts from a git
108108
provider. The Coder control plane and workspaces will need network connectivity
109109
to the git provider.
110110

111-
- [GitHub Enterprise](../external-auth.md#github-enterprise)
112-
- [GitLab](../external-auth.md#gitlab-self-managed)
113-
- [BitBucket](../external-auth.md#bitbucket-server)
114-
- [Other Providers](../external-auth.md#self-managed-git-providers)
111+
- [GitHub Enterprise](../external-auth/index.md#github-enterprise)
112+
- [GitLab](../external-auth/index.md#gitlab-self-managed)
113+
- [BitBucket](../external-auth/index.md#bitbucket-server)
114+
- [Other Providers](../external-auth/index.md#self-managed-git-providers)
115115

116116
### Artifact Manager (Optional)
117117

‎docs/admin/integrations/jfrog-artifactory.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,7 @@ two type of modules that automate the JFrog Artifactory and Coder integration.
2626
### JFrog-OAuth
2727

2828
This module is usable by JFrog self-hosted (on-premises) Artifactory as it
29-
requires configuring a custom integration. This integration benefits from Coder's [external-auth](../../admin/external-auth.md) feature allows each user to authenticate with Artifactory using an OAuth flow and issues user-scoped tokens to each user.
29+
requires configuring a custom integration. This integration benefits from Coder's [external-auth](../external-auth/index.md) feature allows each user to authenticate with Artifactory using an OAuth flow and issues user-scoped tokens to each user.
3030

3131
To set this up, follow these steps:
3232

@@ -53,7 +53,7 @@ To set this up, follow these steps:
5353
`https://JFROG_URL/ui/admin/configuration/integrations/app-integrations/new` and select the
5454
Application Type as the integration you created in step 1 or `Custom Integration` if you are using SaaS instance i.e. example.jfrog.io.
5555

56-
1. Add a new [external authentication](../../admin/external-auth.md) to Coder by setting these
56+
1. Add a new [external authentication](../external-auth/index.md) to Coder by setting these
5757
environment variables in a manner consistent with your Coder deployment. Replace `JFROG_URL` with your JFrog Artifactory base URL:
5858

5959
```env

‎docs/admin/integrations/vault.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@ will show you how to use these modules to integrate HashiCorp Vault with Coder.
1919

2020
The [`vault-github`](https://registry.coder.com/modules/vault-github) module is a Terraform module that allows you to
2121
authenticate with Vault using a GitHub token. This module uses the existing
22-
GitHub [external authentication](../external-auth.md) to get the token and authenticate with Vault.
22+
GitHub [external authentication](../external-auth/index.md) to get the token and authenticate with Vault.
2323

2424
To use this module, add the following code to your Terraform configuration.
2525

‎docs/admin/setup/appearance.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -41,7 +41,7 @@ users of which network their Coder deployment is on.
4141

4242
## OIDC Login Button Customization
4343

44-
[Use environment variables to customize](../users/oidc-auth.md#oidc-login-customization)
44+
[Use environment variables to customize](../users/oidc-auth/index.md#oidc-login-customization)
4545
the text and icon on the OIDC button on the Sign In page.
4646

4747
## Support Links

‎docs/admin/setup/index.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -148,7 +148,7 @@ integrations with Git providers, such as GitHub, GitLab, and Bitbucket.
148148
External authentication can also be used to integrate with external services
149149
like JFrog Artifactory and others.
150150

151-
Please refer to the [external authentication](../external-auth.md) section for
151+
Please refer to the [external authentication](../external-auth/index.md) section for
152152
more information.
153153

154154
## Up Next

‎docs/admin/templates/extending-templates/icons.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -32,7 +32,7 @@ come bundled with your Coder deployment.
3232
}
3333
```
3434

35-
- [**Authentication Providers**](https://coder.com/docs/admin/external-auth):
35+
- [**Authentication Providers**](../../external-auth/index.md):
3636

3737
- Use icons for external authentication providers to make them recognizable.
3838
You can set an icon for each provider by setting the

‎docs/admin/templates/open-in-coder.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ approach for "Open in Coder" flows.
1515

1616
### 1. Set up git authentication
1717

18-
See [External Authentication](../external-auth.md) to set up git authentication
18+
See [External Authentication](../external-auth/index.md) to set up Git authentication
1919
in your Coder deployment.
2020

2121
### 2. Modify your template to auto-clone repos

‎docs/admin/users/idp-sync.md

Lines changed: 6 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -304,7 +304,7 @@ Visit the Coder UI to confirm these changes:
304304

305305
```env
306306
# Depending on your identity provider configuration, you may need to explicitly request a "roles" scope
307-
CODER_OIDC_SCOPES=openid,profile,email,roles
307+
CODER_OIDC_SCOPES=openid,profile,email,offline_access,roles
308308
309309
# The following fields are required for role sync:
310310
CODER_OIDC_USER_ROLE_FIELD=roles
@@ -517,7 +517,7 @@ Steps to troubleshoot.
517517
518518
## Provider-Specific Guides
519519
520-
Below are some details specific to individual OIDC providers.
520+
<div class="tabs">
521521
522522
### Active Directory Federation Services (ADFS)
523523
@@ -577,33 +577,8 @@ Below are some details specific to individual OIDC providers.
577577
groups claim field.
578578
Use [this answer from Stack Overflow](https://stackoverflow.com/a/55570286) for an example.
579579
580-
### Keycloak
581-
582-
The `access_type` parameter has two possible values: `online` and `offline`.
583-
By default, the value is set to `offline`.
584-
585-
This means that when a user authenticates using OIDC, the application requests
586-
offline access to the user's resources, including the ability to refresh access
587-
tokens without requiring the user to reauthenticate.
588-
589-
To enable the `offline_access` scope which allows for the refresh token
590-
functionality, you need to add it to the list of requested scopes during the
591-
authentication flow.
592-
Including the `offline_access` scope in the requested scopes ensures that the
593-
user is granted the necessary permissions to obtain refresh tokens.
594-
595-
By combining the `{"access_type":"offline"}` parameter in the OIDC Auth URL with
596-
the `offline_access` scope, you can achieve the desired behavior of obtaining
597-
refresh tokens for offline access to the user's resources.
580+
## Next Steps
598581
599-
### Google
600-
601-
To ensure Coder receives a refresh token when users authenticate with Google
602-
directly, set the `prompt` to `consent` in the auth URL parameters. Without
603-
this, users will be logged out after 1 hour.
604-
605-
In your Coder configuration:
606-
607-
```shell
608-
CODER_OIDC_AUTH_URL_PARAMS='{"access_type": "offline", "prompt": "consent"}'
609-
```
582+
- [Configure OIDC Refresh Tokens](./oidc-auth/refresh-tokens.md)
583+
- [Organizations](./organizations.md)
584+
- [Groups & Roles](./groups-roles.md)

‎docs/admin/users/index.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ enforces MFA correctly.
77

88
## Configuring SSO
99

10-
- [OpenID Connect](./oidc-auth.md) (e.g. Okta, KeyCloak, PingFederate, Azure AD)
10+
- [OpenID Connect](./oidc-auth/index.md) (e.g. Okta, KeyCloak, PingFederate, Azure AD)
1111
- [GitHub](./github-auth.md) (or GitHub Enterprise)
1212

1313
## Groups

‎docs/admin/users/oidc-auth.md renamed to ‎docs/admin/users/oidc-auth/index.md

Lines changed: 40 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -90,7 +90,40 @@ CODER_OIDC_ICON_URL=https://gitea.io/images/gitea.png
9090
```
9191

9292
To change the icon and text above the OpenID Connect button, see application
93-
name and logo url in [appearance](../setup/appearance.md) settings.
93+
name and logo url in [appearance](../../setup/appearance.md) settings.
94+
95+
## Configure Refresh Tokens
96+
97+
By default, OIDC access tokens typically expire after a short period.
98+
This is typically after one hour, but varies by provider.
99+
100+
Without refresh tokens, users will be automatically logged out when their access token expires.
101+
102+
Follow [Configure OIDC Refresh Tokens](./refresh-tokens.md) for provider-specific steps.
103+
104+
The general steps to configure persistent user sessions are:
105+
106+
1. Configure your Coder OIDC settings:
107+
108+
For most providers, add the `offline_access` scope:
109+
110+
```env
111+
CODER_OIDC_SCOPES=openid,profile,email,offline_access
112+
```
113+
114+
For Google, add auth URL parameters (`CODER_OIDC_AUTH_URL_PARAMS`) too:
115+
116+
```env
117+
CODER_OIDC_SCOPES=openid,profile,email
118+
CODER_OIDC_AUTH_URL_PARAMS='{"access_type": "offline", "prompt": "consent"}'
119+
```
120+
121+
1. Configure your identity provider to issue refresh tokens.
122+
123+
1. After configuration, have users log out and back in once to obtain refresh tokens
124+
125+
> [!IMPORTANT]
126+
> Misconfigured refresh tokens can lead to frequent user authentication prompts.
94127
95128
## Disable Built-in Authentication
96129

@@ -109,8 +142,8 @@ CODER_DISABLE_PASSWORD_AUTH=true
109142
110143
Coder supports user provisioning and deprovisioning via SCIM 2.0 with header
111144
authentication. Upon deactivation, users are
112-
[suspended](./index.md#suspend-a-user) and are not deleted.
113-
[Configure](../setup/index.md) your SCIM application with an auth key and supply
145+
[suspended](../index.md#suspend-a-user) and are not deleted.
146+
[Configure](../../setup/index.md) your SCIM application with an auth key and supply
114147
it the Coder server.
115148

116149
```env
@@ -127,7 +160,8 @@ CODER_TLS_CLIENT_CERT_FILE=/path/to/cert.pem
127160
CODER_TLS_CLIENT_KEY_FILE=/path/to/key.pem
128161
```
129162

130-
### Next steps
163+
## Next steps
131164

132-
- [Group Sync](./idp-sync.md)
133-
- [Groups & Roles](./groups-roles.md)
165+
- [Group Sync](../idp-sync.md)
166+
- [Groups & Roles](../groups-roles.md)
167+
- [Configure OIDC Refresh Tokens](./refresh-tokens.md)

0 commit comments

Comments
 (0)