- Notifications
You must be signed in to change notification settings - Fork912
docs: add more specific steps and information about oidc refresh tokens#18336
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to ourterms of service andprivacy statement. We’ll occasionally send you account related emails.
Already on GitHub?Sign in to your account
base:main
Are you sure you want to change the base?
Conversation
ff568a1 to566fe99CompareCan we update the release notes to point to this documentation once it's merged? |
d3ac4ea toe69afa5Compare| @@ -0,0 +1,62 @@ | |||
| #Configure OIDC refresh tokens | |||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
The problem that prompted this update to docs doesn't have to do with external-auth it has to do with configuring your OIDC provider so this page should be a section inoidc-auth.md. We should also be adding a big fatWARNING orNOTE or whatever to let people know what the consequences are of not configuring your provider to issue refresh tokens.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
isn'thttps://coder.com/docs/admin/users/oidc-auth also a form of external authentication?
we could add the warning here too, but since this the stand-alone doc that's for people trying to do it, I don't think we need to warn people about why they shouldn't.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
They're related but OIDC is used specifically for logging in/authenticating users. The consequences of not issuing refresh tokens with your OIDC provider are far more disruptive than if you forget to do it with your external auth provider. I'm not saying we shouldn't document doing it for external auth, but the issue here is that we don't currently document in the same place that we tell people how to setup OIDC that you will have a degraded experience inv2.23.0 onward if you misconfigure your provider.
EdwardAngertJun 13, 2025 • edited
Loading Uh oh!
There was an error while loading.Please reload this page.
edited
Uh oh!
There was an error while loading.Please reload this page.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
I see - thanks@sreya
I'll move it and add some more
edit: pushed a commit with a new location and I have more changes staged locally that I need to edit
| By combining the`{"access_type":"offline"}` parameter in the OIDC Auth URL with | ||
| the`offline_access` scope, you can achieve the desired behavior of obtaining | ||
| refresh tokens for offline access to the user's resources. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
I think this corresponds to
CODER_OIDC_AUTH_URL_PARAMS='{"access_type": "offline"}'which might be helpful as an example
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
@spikecurtis from what I can tell, we always add this.
Line 45 in3ddc7a9
| opts=append(opts,oauth2.AccessTypeOffline) |
Regardless of your config
| ##Troubleshooting OIDC refresh tokens | ||
| ###Users Are Logged Out Every Hour |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
They get logged out whenever the OIDC token expires --- this is 1 hour for Google anddefaults to 1 hour in Okta, but is configurable. Not sure about the other providers. I suggest we rephrase this so that we're not quoting a specific timeout, e.g. "Users are asked to reauthenticate with the OIDC provider too frequently"
| ###Users Are Logged Out Every Hour | ||
| **Symptoms**: Users experience session timeouts approximately every hour and must re-authenticate | ||
| **Cause**: Missing`offline_access` scope in`CODER_OIDC_SCOPES` |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
| **Cause**:Missing`offline_access` scope in`CODER_OIDC_SCOPES` | |
| **Cause**:OIDC provider is not sending refresh tokens |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
these are list items onLL165-166
| **Cause**: Missing`offline_access` scope in`CODER_OIDC_SCOPES` | ||
| **Solution**: | ||
| 1. Add`offline_access` to your`CODER_OIDC_SCOPES` configuration |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
| 1.Add`offline_access` to your`CODER_OIDC_SCOPES` configuration | |
| 1.Configure refresh tokens as discussed above |
(different providers have different config, as you have in the above section.)
| ###Refresh Tokens Not Working After Configuration Change | ||
| **Symptoms**: Hourly timeouts, even after adding`offline_access` |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
So, aftersuccessfully configuring refresh tokens, users will get logged out early up to one more time. Once they reauthenticate they should get the refresh token---so if users are continuing to get "hourly timeouts" (plural), then refresh tokens are still misconfigured.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
added:
Users might get logged out again before the new configuration takes effect completely.
but I'm about to move it to the end of the next FAQ
| To confirm that refresh tokens are working correctly: | ||
| 1. Check that`offline_access` is included in your`CODER_OIDC_SCOPES` |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
depends on the identity provider.
| 1. Checkthat`offline_access` is included inyour`CODER_OIDC_SCOPES` | |
| 1. Checkyour configuration as described above foryouridentity provider |
| To confirm that refresh tokens are working correctly: | ||
| 1. Check that`offline_access` is included in your`CODER_OIDC_SCOPES` | ||
| 1. Verify users can stay logged in beyond Okta's access token lifetime (typically one hour) |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
| 1. Verify users can stay logged in beyondOkta's access token lifetime (typically one hour) | |
| 1. Verify users can stay logged in beyondyour provider's access token lifetime (typically one hour) |
| 1. Check that`offline_access` is included in your`CODER_OIDC_SCOPES` | ||
| 1. Verify users can stay logged in beyond Okta's access token lifetime (typically one hour) | ||
| 1. Monitor Coder logs for any OIDC refresh errors during token renewal |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
If they have access to the database, and it is not encrypted, then they can check theuser_links table and verify that there are entries in theoauth_refresh_token column.
Getting these instructions doesn't need to block merging.
| ```env | ||
| CODER_OIDC_SCOPES=openid,profile,email,offline_access | ||
| CODER_OIDC_AUTH_URL_PARAMS='{"access_type":"offline"}' |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
| ##Troubleshooting OIDC Refresh Tokens | ||
| ###Users are logged out too frequently |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
| - Missing`offline_access` scope in`CODER_OIDC_SCOPES` | ||
| - Provider not configured to issue refresh tokens |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
I'm going to push another commit with a "for most, this; for google, that"
| ###Users Are Logged Out Every Hour | ||
| **Symptoms**: Users experience session timeouts approximately every hour and must re-authenticate | ||
| **Cause**: Missing`offline_access` scope in`CODER_OIDC_SCOPES` |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
these are list items onLL165-166
| ###Refresh Tokens Not Working After Configuration Change | ||
| **Symptoms**: Hourly timeouts, even after adding`offline_access` |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
added:
Users might get logged out again before the new configuration takes effect completely.
but I'm about to move it to the end of the next FAQ
Uh oh!
There was an error while loading.Please reload this page.
closes#18307
relates to#18318
preview:
(not sure why@Emyrk 's photo is so huge there though)✔️to do:
convert some paragraphs to OLcalling this out of scope for now