Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit 0801760

Browse files
stirbystirby
authored
docs: add guides section (#11199)
* setup manifest * added okta guide from steven M * improved index by adding children * changed icon to notes.svg * added meta guide, fixed profile photo fmt
1 parent a495952 commit 0801760

File tree

11 files changed

+237
-0
lines changed

11 files changed

+237
-0
lines changed

‎docs/guides/configuring-okta.md

Lines changed: 160 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,160 @@
1+
# Configuring Custom Claims/Scopes with Okta for group/role
2+
3+
<div style="pad: 0px; margin: 0px;">
4+
<span style="vertical-align:middle;">Author: </span>
5+
<a href="https://github.com/Emyrk" style="text-decoration: none; color: inherit; margin-bottom: 0px;">
6+
<span style="vertical-align:middle;">Steven Masley</span>
7+
<img src="https://avatars.githubusercontent.com/u/5446298?v=4" width="24px" height="24px" style="vertical-align:middle; margin: 0px;"/>
8+
</a>
9+
</div>
10+
December 13, 2023
11+
12+
---
13+
14+
> Okta is an identity provider that can be used for OpenID Connect (OIDC) Single
15+
> Sign On (SSO) on Coder.
16+
17+
To configure custom claims in Okta to support syncing roles and groups with
18+
Coder, you must first have setup an Okta application with
19+
[OIDC working with Coder](https://coder.com/docs/v2/latest/admin/auth#openid-connect).
20+
From here, we will add additional claims for Coder to use for syncing groups and
21+
roles.
22+
23+
You may use a hybrid of the following approaches.
24+
25+
# (Easiest) Sync using Okta Groups
26+
27+
If the Coder roles & Coder groups can be inferred from
28+
[Okta groups](https://help.okta.com/en-us/content/topics/users-groups-profiles/usgp-about-groups.htm),
29+
Okta has a simple way to send over the groups as a `claim` in the `id_token`
30+
payload.
31+
32+
In Okta, go to the application “Sign On” settings page.
33+
34+
Applications > Select Application > General > Sign On
35+
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.
39+
40+
> !! If the user does not belong to any groups, the claim will not be sent. Make
41+
> sure the user authenticating for testing is in at least 1 group. Defer to
42+
> [troubleshooting](https://coder.com/docs/v2/latest/admin/auth#troubleshooting)
43+
> with issues
44+
45+
![Okta OpenID Connect ID Token](../images/guides/okta/oidc_id_token.png)
46+
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/v2/latest/admin/auth#group-sync-enterprise).
50+
51+
```bash
52+
# Add the 'groups' scope.
53+
CODER_OIDC_SCOPES=openid,profile,email,groups
54+
# This name needs to match the "Claim name" in the configuration above.
55+
CODER_OIDC_GROUP_FIELD=groups
56+
```
57+
58+
These groups can also be used to configure role syncing based on group
59+
membership.
60+
61+
```bash
62+
# Requires the "groups" scope
63+
CODER_OIDC_SCOPES=openid,profile,email,groups
64+
# This name needs to match the "Claim name" in the configuration above.
65+
CODER_OIDC_USER_ROLE_FIELD=groups
66+
# Example configuration to map a group to some roles
67+
CODER_OIDC_USER_ROLE_MAPPING='{"admin-group":["template-admin","user-admin"]}'
68+
```
69+
70+
# (Easy) Mapping Okta profile attributes
71+
72+
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)”.
75+
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,
78+
then add a mapping from the Okta profile to the application.
79+
80+
“Directory > Profile Editor > {Your Application} > Add Attribute”
81+
82+
Create the attribute for the roles, groups, or both. **Make sure the attribute
83+
is of type `string array`.**
84+
85+
![Okta Add Attribute view](../images/guides/okta/add_attribute.png)
86+
87+
On the “Okta User to {Your Application}” tab, map a `roles` or `groups`
88+
attribute you have configured to the application.
89+
90+
![Okta Add Claim view](../images/guides/okta/add_claim.png)
91+
92+
Configure using these new attributes in Coder.
93+
94+
```bash
95+
# This must be set to false. Coder uses this endpoint to grab the attributes.
96+
CODER_OIDC_IGNORE_USERINFO=false
97+
# No custom scopes are required.
98+
CODER_OIDC_SCOPES=openid,profile,email
99+
# Configure the group/role field using the attribute name in the application.
100+
CODER_OIDC_USER_ROLE_FIELD=approles
101+
# See our docs for mapping okta roles to coder roles.
102+
CODER_OIDC_USER_ROLE_MAPPING='{"admin-group":["template-admin","user-admin"]}'
103+
104+
# If you added an attribute for groups, set that here.
105+
# CODER_OIDC_GROUP_FIELD=...
106+
```
107+
108+
# (Advanced) Custom scopes to retrieve custom claims
109+
110+
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.
113+
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+
119+
Authorization servers also give more refined controls over things such as
120+
token/session lifetimes.
121+
122+
![Okta API view](../images/guides/okta/api_view.png)
123+
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+
127+
Go to “Scopes”, and “Add Scope”. Feel free to create one for roles, groups, or
128+
both.
129+
130+
![Okta Add Scope view](../images/guides/okta/add_scope.png)
131+
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.
138+
139+
![Okta Add Claim with Roles view](../images/guides/okta/add_claim_with_roles.png)
140+
141+
Now we have a custom scope + claim configured under an authorization server, we
142+
need to configure coder to use this.
143+
144+
```bash
145+
# Grab this value from the Authorization Server > Settings > Issuer
146+
# DO NOT USE the application issuer URL. Make sure to use the newly configured
147+
# authorization server.
148+
CODER_OIDC_ISSUER_URL=https://dev-12222860.okta.com/oauth2/default
149+
# Add the new scope you just configured
150+
CODER_OIDC_SCOPES=openid,profile,email,roles
151+
# Use the claim you just configured
152+
CODER_OIDC_USER_ROLE_FIELD=roles
153+
# See our docs for mapping okta roles to coder roles.
154+
CODER_OIDC_USER_ROLE_MAPPING='{"admin-group":["template-admin","user-admin"]}'
155+
```
156+
157+
You can use the “Token Preview” page to verify it has been correctly configured
158+
and verify the `roles` is in the payload.
159+
160+
![Okta Token Preview](../images/guides/okta/token_preview.png)

‎docs/guides/example-guide.md

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
# Guide Title (Only Visible in Github)
2+
3+
<div>
4+
<a href="https://github.com/<your_github_handle>" style="text-decoration: none; color: inherit;">
5+
<span style="vertical-align:middle;">Your Name</span>
6+
<img src="<your_github_profile_photo_url>" width="24px" height="24px" style="vertical-align:middle; margin: 0px;"/>
7+
</a>
8+
</div>
9+
December 13, 2023
10+
11+
---
12+
13+
This is a guide on how to make Coder guides, it is not listed on our
14+
[official guides page](coder.com/docs/v2/latest/guides) in the docs. This is
15+
intended for those who don't frequently contribute documentation changes to the
16+
`coder/coder` repository.
17+
18+
## Content
19+
20+
Defer to our
21+
[Contributing/Documentation](coder.com/docs/v2/latest/contributing/documentation)
22+
page for rules on technical writing.
23+
24+
### Adding Photos
25+
26+
Use relative imports in the markdown and store photos in
27+
`docs/images/guides/<your_guide>/<image>.png`.
28+
29+
### Setting the author data
30+
31+
At the top of this example you will find a small html snippet that nicely
32+
renders the author's name and photo, while linking to their Github profile.
33+
Before submitting your guide in a PR, replace `your_github_handle`,
34+
`your_github_profile_photo_url` and "Your Name". The entire `<img>` element can
35+
be omitted.
36+
37+
## Setting up the routes
38+
39+
Once you've written your guide, you'll need to add its route to
40+
`docs/manifest.json` under `Guides` > `"children"` at the bottom:
41+
42+
```json
43+
{
44+
// Overrides the "# Guide Title" at the top of this file
45+
"title": "Contributing to Guides",
46+
"description": "How to add a guide",
47+
"path": "./guides/my-guide-file.md"
48+
},
49+
```
50+
51+
## Format before push
52+
53+
Before pushing your guide to github, run `make fmt` to format the files with
54+
Prettier. Then, push your changes to a new branch and create a PR.

‎docs/guides/index.md

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
# Guides and Tutorials
2+
3+
Here you can find a list of employee-written guides on Coder for OSS and
4+
Enterprise. These tutorials are hosted on our
5+
[Github](https://github.com/coder/coder/) where you can leave feedback or
6+
request new topics to be covered.
7+
8+
<children>
9+
This page is rendered on https://coder.com/docs/v2/latest/guides. Refer to the other documents in the `guides/` directory for specific employee-written guides.
10+
</children>

‎docs/images/guides/okta/add_attribute.png

105 KB
Loading

‎docs/images/guides/okta/add_claim.png

35.3 KB
Loading

‎docs/images/guides/okta/add_claim_with_roles.png

35.3 KB
Loading

‎docs/images/guides/okta/add_scope.png

56.4 KB
Loading

‎docs/images/guides/okta/api_view.png

27 KB
Loading

‎docs/images/guides/okta/oidc_id_token.png

32.9 KB
Loading

‎docs/images/guides/okta/token_preview.png

117 KB
Loading

‎docs/manifest.json

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1018,6 +1018,19 @@
10181018
"description": "Frequently asked questions",
10191019
"path": "./faqs.md",
10201020
"icon_path": "./images/icons/info.svg"
1021+
},
1022+
{
1023+
"title": "Guides",
1024+
"description": "Employee-authored tutorials",
1025+
"path": "./guides/index.md",
1026+
"icon_path": "./images/icons/notes.svg",
1027+
"children": [
1028+
{
1029+
"title": "Configuring Okta",
1030+
"description": "Custom claims/scopes with Okta for group/role sync",
1031+
"path": "./guides/configuring-okta.md"
1032+
}
1033+
]
10211034
}
10221035
]
10231036
}

0 commit comments

Comments
 (0)