docs: rework "admin/authentication" page + PKI authentication docs #9236
Conversation
|
|
||
| Navigate to your Coder host and run the following command to start up the Coder | ||
| The most common way to authenticate with OIDC providers is with a `client_secret`. Navigate to your Coder host and run the following command to start up the Coder | ||
| server: | ||
|
|
There was a problem hiding this comment.
What do you think about adding subheadings?
- CLI
- System Service
- Helm
|
|
||
| Once the key and certificate are uploaded, you can run Coder with the files. Navigate to your Coder host and run the following command to start up the Coder server: | ||
|
|
||
| ```console |
There was a problem hiding this comment.
the same concept of subheadings here.
|
|
||
| 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`](https://coder.com/docs/v2/latest/cli/server#--access-url) (e.g. `https://coder.example.com`) |
There was a problem hiding this comment.
| - **Homepage URL**: Set to your Coder deployments [`CODER_ACCESS_URL`](https://coder.com/docs/v2/latest/cli/server#--access-url) (e.g. `https://coder.example.com`) | |
| - **Homepage URL**: Set to your Coder deployments [`CODER_ACCESS_URL`](https://coder.com/docs/v2/latest/cli/server.md#--access-url) (e.g. `https://coder.example.com`) |
Even if this is a valid URL, our URL checker gives a 404 if .md is missing.
| @@ -1,7 +1,5 @@ | |||
| # Authentication | |||
|
|
|||
| [OIDC with Coder Sequence Diagram](https://raw.githubusercontent.com/coder/coder/138ee55abb3635cb2f3d12661f8caef2ca9d0961/docs/images/oidc-sequence-diagram.svg). | |||
There was a problem hiding this comment.
Where should this image be referenced?
There was a problem hiding this comment.
I link to it later in the doc under "How it works"
There was a problem hiding this comment.
|
|
||
| Once complete, restart your server. GitHub authentication should appear on your log-in screen 🎉 | ||
|
|
||
|  |
There was a problem hiding this comment.
Replace with a relative image URL.
Also, you can use the excellent VS Code Doc Writer profile to preview your changes better.
There was a problem hiding this comment.
Yeah I like to preview with the coder site too
| 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`](https://coder.com/docs/v2/latest/cli/server#--access-url) (e.g. `https://coder.example.com`) | ||
| - **User Authorization Callback URL**: Set to `https://coder.example.com/api/v2/users/oauth2/github/callback` |
There was a problem hiding this comment.
Per my testing, it is enough to set it to https://coder.example.com or even https://example.com if you want multiple coder deployments on different subdomains to use the same GitHub OAuth app.
As per my understanding, Coder doesn't use the callback URL and sends a redirect_uri that is of the correct form.
See, we are doing it here.
Line 1560 in 545a256
@deansheather for confirmation, please.
There was a problem hiding this comment.
IMO, this section should not be under auth directory as it is not an auth method but a feature on top of OIDC/SAML. May be we should have a subdirectory OIDC under auth directory and move this along with setting up OIDC.
These are my thoughts, and they are not very important. If you feel the current flow and organization are right. Please ignore this comment.
There was a problem hiding this comment.
Yea, that makes sense to me too. Like "Identity Providers" can be a subsection under OIDC and have each one listed.
| - **Homepage URL**: Set to your Coder deployments [`CODER_ACCESS_URL`](https://coder.com/docs/v2/latest/cli/server#--access-url) (e.g. `https://coder.example.com`) | ||
| - **User Authorization Callback URL**: Set to `https://coder.example.com/api/v2/users/oauth2/github/callback` | ||
|
|
||
| > Note: If you want to allow multiple coder deployments hosted on subdomains e.g. coder1.example.com, coder2.example.com, to be able to authenticate with the same GitHub OAuth app, then you can set **User Authorization Callback URL** to the `https://example.com` |
There was a problem hiding this comment.
| > Note: If you want to allow multiple coder deployments hosted on subdomains e.g. coder1.example.com, coder2.example.com, to be able to authenticate with the same GitHub OAuth app, then you can set **User Authorization Callback URL** to the `https://example.com` | |
| > [!NOTE] | |
| > If you want to allow multiple coder deployments hosted on subdomains, e.g., `coder1.example.com`, `coder2.example.com`, to be able to authenticate with the same GitHub OAuth app, then you can set **User Authorization Callback URL** to the `https://example.com` |
| @@ -0,0 +1,42 @@ | |||
| # Active Directory Federation Services OIDC with Coder (ADFS) | |||
|
|
|||
| > **Note:** Tested on ADFS 4.0, Windows Server 2019 | |||
There was a problem hiding this comment.
| > **Note:** Tested on ADFS 4.0, Windows Server 2019 | |
| > ![NOTE] | |
| > Tested on ADFS 4.0, Windows Server 2019 |
| <blockquote class="warning"> | ||
| <p> | ||
| Only <b>Azure AD</b> has been tested with this method. Other OIDC providers may not work, as most providers add additional requirements ontop of the standard that must be implemented. If you are using another provider and run into issues, please leave an issue on our <a href="https://github.com/coder/coder/issues">Github</a>. | ||
| </p> | ||
| </blockquote> |
There was a problem hiding this comment.
I noticed that sometimes we use these HTML blockquotes and sometimes GitHub Style blockquote.
There was a problem hiding this comment.
I grabbed this warning from another page. I was unaware we had two methods 🤔
There was a problem hiding this comment.
The other method is I am not sure if we support. I asked Bruno if he can add it.
|
|
||
| In the Users page `https://coder.example.com/users`, create a new user with `Login Type: none`: | ||
|
|
||
|  |
There was a problem hiding this comment.
replace image path with realative
| CODER_OIDC_ICON_URL="https://upload.wikimedia.org/wikipedia/commons/f/fa/Microsoft_Azure.svg" | ||
| ``` | ||
|
|
||
|  |
| <blockquote class="warning"> | ||
| <p> | ||
| Only <b>Azure AD</b> has been tested with this method. Other OIDC providers may not work, as most providers add additional requirements ontop of the standard that must be implemented. If you are using another provider and run into issues, please leave an issue on our <a href="https://github.com/coder/coder/issues">Github</a>. | ||
| </p> | ||
| </blockquote> |
There was a problem hiding this comment.
I grabbed this warning from another page. I was unaware we had two methods 🤔
There was a problem hiding this comment.
Yea, that makes sense to me too. Like "Identity Providers" can be a subsection under OIDC and have each one listed.
|
|
||
| The access_type parameter has two possible values: "online" and "offline." By default, the value is set to "offline". This means that when a user authenticates using OIDC, the application requests offline access to the user's resources, including the ability to refresh access tokens without requiring the user to reauthenticate. | ||
|
|
||
| To enable the `offline_access` scope, which allows for the refresh token functionality, you need to add it to the list of requested scopes during the authentication flow. Including the `offline_access` scope in the requested scopes ensures that the user is granted the necessary permissions to obtain refresh tokens. |
There was a problem hiding this comment.
Should we provide the example?
CODER_OIDC_SCOPES=openid,profile,email,offline_accessThere was a problem hiding this comment.
It would be better if we also include an example
| returned by the upstream identity provider in a message containing the | ||
| string `got oidc claims`, as well as the user info returned. | ||
|
|
||
| The following information is also avalible via a [sequence diagram](https://raw.githubusercontent.com/coder/coder/138ee55abb3635cb2f3d12661f8caef2ca9d0961/docs/images/oidc-sequence-diagram.svg) for visual learners. |
| returned by the upstream identity provider in a message containing the | ||
| string `got oidc claims`, as well as the user info returned. | ||
|
|
||
| The following information is also avalible via a [sequence diagram](https://raw.githubusercontent.com/coder/coder/138ee55abb3635cb2f3d12661f8caef2ca9d0961/docs/images/oidc-sequence-diagram.svg) for visual learners. |
There was a problem hiding this comment.
Change to main branch now imo.
| The following information is also avalible via a [sequence diagram](https://raw.githubusercontent.com/coder/coder/138ee55abb3635cb2f3d12661f8caef2ca9d0961/docs/images/oidc-sequence-diagram.svg) for visual learners. | |
| The following information is also avalible via a [sequence diagram](https://raw.githubusercontent.com/coder/coder/main/docs/images/oidc-sequence-diagram.svg) for visual learners. |
There was a problem hiding this comment.
This is stored in docs/images. We plan to remove the absolute link and use relative link for images too.
| <blockquote class="warning"> | ||
| <p> | ||
| Only <b>Azure AD</b> has been tested with this method. Other OIDC providers may not work, as most providers add additional requirements ontop of the standard that must be implemented. If you are using another provider and run into issues, please leave an issue on our <a href="https://github.com/coder/coder/issues">Github</a>. | ||
| </p> | ||
| </blockquote> |
There was a problem hiding this comment.
I know I probably did this, but move this up. The previous sentence and the content after this should be continous.
| From there, you can create a long-lived token on behalf of the passwordless user using the [Create token API key](../../api/users.md#create-token-api-key): | ||
|
|
||
| ```sh | ||
| # Replace API_KEY with a token from https://coder.example.com/cli-auth |
There was a problem hiding this comment.
| # Replace API_KEY with a token from https://coder.example.com/cli-auth | |
| # Replace API_KEY with a token from https://coder.example.com/cli-auth | |
| # The logged in user needs to have the requisite permissions to create an API | |
| # key on behalf of another user. |
|
|
||
| ```sh | ||
| # Replace API_KEY with a token from https://coder.example.com/cli-auth | ||
| curl -X POST http://coder-server:8080/api/v2/users/coder-bot/keys/tokens \ |
There was a problem hiding this comment.
| curl -X POST http://coder-server:8080/api/v2/users/coder-bot/keys/tokens \ | |
| curl -X POST http://coder-server:8080/api/v2/users/<machine_username>/keys/tokens \ |
@Emyrk brought up that this page was getting a bit out of hand, and I agree. Would appreciate folks thoughts on the new format.
Closes #9188
Before merging
I'd appreciate a review in the meantime.