Skip to content

Commit 566fe99

Browse files
EdwardAngertEdwardAngert
committed
md fixes and lots of offline_access notes
1 parent 56158b8 commit 566fe99

File tree

1 file changed

+78
-47
lines changed

1 file changed

+78
-47
lines changed

‎docs/tutorials/configuring-okta.md

Lines changed: 78 additions & 47 deletions
Original file line numberDiff line numberDiff line change
@@ -29,37 +29,38 @@ If the Coder roles & Coder groups can be inferred from
2929
Okta has a simple way to send over the groups as a `claim` in the `id_token`
3030
payload.
3131

32-
In Okta, go to the application “Sign On” settings page.
32+
In Okta, go to the application **Sign On** settings page.
3333

34-
Applications > Select Application > General > Sign On
34+
**Applications** > **Select Application** > **General** > **Sign On**
3535

36-
In the “OpenID Connect ID Token” section, turn on “Groups Claim Type” and set
37-
the “Claim name” to `groups`. Optionally configure a filter for which groups to
38-
be sent.
36+
In the **OpenID Connect ID Token** section, turn on **Groups Claim Type** and set
37+
the **Claim name** to `groups`.
38+
Optionally, configure a filter for which groups to be sent.
3939

4040
> [!IMPORTANT]
41-
> If the user does not belong to any groups, the claim will not be sent. Make
42-
> sure the user authenticating for testing is in at least one group. Defer to
43-
> [troubleshooting](../admin/users/index.md) with issues.
41+
> If the user does not belong to any groups, the claim will not be sent.
42+
> Make sure the user authenticating for testing is in at least one group.
4443
4544
![Okta OpenID Connect ID Token](../images/guides/okta/oidc_id_token.png)
4645

47-
Configure Coder to use these claims for group sync. These claims are present in
48-
the `id_token`. See all configuration options for group sync in the
49-
[docs](https://coder.com/docs/admin/auth#group-sync-enterprise).
46+
Configure Coder to use these claims for group sync.
47+
These claims are present in the `id_token`.
48+
For more group sync configuration options, consult the [IDP sync documentation](../admin/users/idp-sync.md#group-sync).
5049

5150
```bash
52-
# Add the 'groups' scope.
51+
# Add the 'groups' scope and include the 'offline_access' scope for refresh tokens
5352
CODER_OIDC_SCOPES=openid,profile,email,offline_access,groups
5453
# This name needs to match the "Claim name" in the configuration above.
5554
CODER_OIDC_GROUP_FIELD=groups
5655
```
5756

57+
> [!NOTE]
58+
> The `offline_access` scope is required in Coder v2.23.0+ to prevent hourly session timeouts.
59+
5860
These groups can also be used to configure role syncing based on group
59-
membership.
61+
membership:
6062

6163
```bash
62-
# Requires the "groups" scope
6364
CODER_OIDC_SCOPES=openid,profile,email,offline_access,groups
6465
# This name needs to match the "Claim name" in the configuration above.
6566
CODER_OIDC_USER_ROLE_FIELD=groups
@@ -70,31 +71,31 @@ CODER_OIDC_USER_ROLE_MAPPING='{"admin-group":["template-admin","user-admin"]}'
7071
## (Easy) Mapping Okta profile attributes
7172

7273
If roles or groups cannot be completely inferred from Okta group memberships,
73-
another option is to source them from a user’s attributes. The user attribute
74-
list can be found in “Directory > Profile Editor > User (default)”.
74+
another option is to source them from a user's attributes.
75+
The user attribute list can be found in **Directory** > **Profile Editor** > **User (default)**.
7576

76-
Coder can query an Okta profile for the application from the `/userinfo` OIDC
77-
endpoint. To pass attributes to Coder, create the attribute in your application,
77+
Coder can query an Okta profile for the application from the `/userinfo` OIDC endpoint.
78+
To pass attributes to Coder, create the attribute in your application,
7879
then add a mapping from the Okta profile to the application.
7980

80-
“Directory > Profile Editor > {Your Application} > Add Attribute”
81+
**Directory** > **Profile Editor** > {Your Application} > **Add Attribute**
8182

82-
Create the attribute for the roles, groups, or both. **Make sure the attribute
83-
is of type `string array`.**
83+
Create the attribute for the roles, groups, or both. Make sure the attribute
84+
is of type `string array`:
8485

8586
![Okta Add Attribute view](../images/guides/okta/add_attribute.png)
8687

87-
On the “Okta User to {Your Application}” tab, map a `roles` or `groups`
88-
attribute you have configured to the application.
88+
On the **Okta User to {Your Application}** tab, map a `roles` or `groups`
89+
attribute you have configured to the application:
8990

9091
![Okta Add Claim view](../images/guides/okta/add_claim.png)
9192

92-
Configure using these new attributes in Coder.
93+
Configure using these new attributes in Coder:
9394

9495
```bash
9596
# This must be set to false. Coder uses this endpoint to grab the attributes.
9697
CODER_OIDC_IGNORE_USERINFO=false
97-
# No custom scopes are required.
98+
# Include offline_access for refresh tokens
9899
CODER_OIDC_SCOPES=openid,profile,email,offline_access
99100
# Configure the group/role field using the attribute name in the application.
100101
CODER_OIDC_USER_ROLE_FIELD=approles
@@ -105,56 +106,86 @@ CODER_OIDC_USER_ROLE_MAPPING='{"admin-group":["template-admin","user-admin"]}'
105106
# CODER_OIDC_GROUP_FIELD=...
106107
```
107108

109+
> [!NOTE]
110+
> The `offline_access` scope is required in Coder v2.23.0+ to prevent hourly session timeouts.
111+
108112
## (Advanced) Custom scopes to retrieve custom claims
109113

110114
Okta does not support setting custom scopes and claims in the default
111-
authorization server used by your application. If you require this
112-
functionality, you must create (or modify) an authorization server.
115+
authorization server used by your application.
116+
If you require this functionality, you must create (or modify) an authorization server.
113117

114-
To see your custom authorization servers go to “Security > API”. Note the
115-
`default` authorization server **is not the authorization server your app is
116-
using.** You can configure this default authorization server, or create a new
117-
one specifically for your application.
118+
To see your custom authorization servers go to **Security** > **API**.
119+
Note the `default` authorization server is not the authorization server your app is using.
120+
You can configure this default authorization server, or create a new one specifically for your application.
118121

119-
Authorization servers also give more refined controls over things such as
120-
token/session lifetimes.
122+
Authorization servers also give more refined controls over things such as token/session lifetimes.
121123

122124
![Okta API view](../images/guides/okta/api_view.png)
123125

124-
To get custom claims working, we should map them to a custom scope. Click the
125-
authorization server you wish to use (likely just using the default).
126+
To get custom claims working, map them to a custom scope.
127+
Click the authorization server you wish to use (likely just using the default).
126128

127-
Go to “Scopes”, and “Add Scope”. Feel free to create one for roles, groups, or
128-
both.
129+
Go to **Scopes**, and **Add Scope**.
130+
Feel free to create one for roles, groups, or both:
129131

130132
![Okta Add Scope view](../images/guides/okta/add_scope.png)
131133

132-
Now create the claim to go with the said scope. Go to “Claims”, then “Add
133-
Claim”. Make sure to select **ID Token** for the token type. The **Value**
134-
expression is up to you based on where you are sourcing the role information.
135-
Lastly, configure it to only be a claim with the requested scope. This is so if
136-
other applications exist, we do not send them information they do not care
137-
about.
134+
Create the claim to go with the said scope.
135+
Go to **Claims**, then **Add Claim**.
136+
Make sure to select **ID Token** for the token type.
137+
The **Value** expression is up to you based on where you are sourcing the role information.
138+
Configure it to only be a claim with the requested scope.
139+
This is so if other applications exist, we do not send them information they do not care about:
138140

139141
![Okta Add Claim with Roles view](../images/guides/okta/add_claim_with_roles.png)
140142

141-
Now we have a custom scope + claim configured under an authorization server, we
142-
need to configure coder to use this.
143+
Now we have a custom scope and claim configured under an authorization server.
144+
Configure Coder to use this:
143145

144146
```bash
145147
# Grab this value from the Authorization Server > Settings > Issuer
146148
# DO NOT USE the application issuer URL. Make sure to use the newly configured
147149
# authorization server.
148150
CODER_OIDC_ISSUER_URL=https://dev-12222860.okta.com/oauth2/default
149-
# Add the new scope you just configured
151+
# Add the new scope you just configured and offline_access for refresh tokens
150152
CODER_OIDC_SCOPES=openid,profile,email,roles,offline_access
151153
# Use the claim you just configured
152154
CODER_OIDC_USER_ROLE_FIELD=roles
153155
# See our docs for mapping okta roles to coder roles.
154156
CODER_OIDC_USER_ROLE_MAPPING='{"admin-group":["template-admin","user-admin"]}'
155157
```
156158

157-
You can use the “Token Preview” page to verify it has been correctly configured
159+
> [!NOTE]
160+
> The `offline_access` scope is required in Coder v2.23.0+ to prevent hourly session timeouts.
161+
162+
You can use the "Token Preview" page to verify it has been correctly configured
158163
and verify the `roles` is in the payload.
159164

160165
![Okta Token Preview](../images/guides/okta/token_preview.png)
166+
167+
## Troubleshooting
168+
169+
### Users Are Logged Out Every Hour
170+
171+
**Symptoms**: Users experience session timeouts approximately every hour and must re-authenticate
172+
**Cause**: Missing `offline_access` scope in `CODER_OIDC_SCOPES`
173+
**Solution**:
174+
175+
1. Add `offline_access` to your `CODER_OIDC_SCOPES` configuration
176+
1. Restart your Coder deployment
177+
1. All existing users must logout and login once to receive refresh tokens
178+
179+
### Refresh Tokens Not Working After Configuration Change
180+
181+
**Symptoms**: Hourly timeouts, even after adding `offline_access`
182+
**Cause**: Existing user sessions don't have refresh tokens stored
183+
**Solution**: Users must logout and login again to get refresh tokens stored in the database
184+
185+
### Verify Refresh Token Configuration
186+
187+
To confirm that refresh tokens are working correctly:
188+
189+
1. Check that `offline_access` is included in your `CODER_OIDC_SCOPES`
190+
1. Verify users can stay logged in beyond Okta's access token lifetime (typically one hour)
191+
1. Monitor Coder logs for any OIDC refresh errors during token renewal

0 commit comments

Comments
 (0)