diff --git a/docs/guides/configuring-okta.md b/docs/guides/configuring-okta.md
new file mode 100644
index 0000000000000..e87552be76dba
--- /dev/null
+++ b/docs/guides/configuring-okta.md
@@ -0,0 +1,160 @@
+# Configuring Custom Claims/Scopes with Okta for group/role
+
+
+December 13, 2023
+
+---
+
+> Okta is an identity provider that can be used for OpenID Connect (OIDC) Single
+> Sign On (SSO) on Coder.
+
+To configure custom claims in Okta to support syncing roles and groups with
+Coder, you must first have setup an Okta application with
+[OIDC working with Coder](https://coder.com/docs/v2/latest/admin/auth#openid-connect).
+From here, we will add additional claims for Coder to use for syncing groups and
+roles.
+
+You may use a hybrid of the following approaches.
+
+# (Easiest) Sync using Okta Groups
+
+If the Coder roles & Coder groups can be inferred from
+[Okta groups](https://help.okta.com/en-us/content/topics/users-groups-profiles/usgp-about-groups.htm),
+Okta has a simple way to send over the groups as a `claim` in the `id_token`
+payload.
+
+In Okta, go to the application “Sign On” settings page.
+
+Applications > Select Application > General > Sign On
+
+In the “OpenID Connect ID Token” section, turn on “Groups Claim Type” and set
+the “Claim name” to `groups`. Optionally configure a filter for which groups to
+be sent.
+
+> !! If the user does not belong to any groups, the claim will not be sent. Make
+> sure the user authenticating for testing is in at least 1 group. Defer to
+> [troubleshooting](https://coder.com/docs/v2/latest/admin/auth#troubleshooting)
+> with issues
+
+
+
+Configure Coder to use these claims for group sync. These claims are present in
+the `id_token`. See all configuration options for group sync in the
+[docs](https://coder.com/docs/v2/latest/admin/auth#group-sync-enterprise).
+
+```bash
+# Add the 'groups' scope.
+CODER_OIDC_SCOPES=openid,profile,email,groups
+# This name needs to match the "Claim name" in the configuration above.
+CODER_OIDC_GROUP_FIELD=groups
+```
+
+These groups can also be used to configure role syncing based on group
+membership.
+
+```bash
+# Requires the "groups" scope
+CODER_OIDC_SCOPES=openid,profile,email,groups
+# This name needs to match the "Claim name" in the configuration above.
+CODER_OIDC_USER_ROLE_FIELD=groups
+# Example configuration to map a group to some roles
+CODER_OIDC_USER_ROLE_MAPPING='{"admin-group":["template-admin","user-admin"]}'
+```
+
+# (Easy) Mapping Okta profile attributes
+
+If roles or groups cannot be completely inferred from Okta group memberships,
+another option is to source them from a user’s attributes. The user attribute
+list can be found in “Directory > Profile Editor > User (default)”.
+
+Coder can query an Okta profile for the application from the `/userinfo` OIDC
+endpoint. To pass attributes to Coder, create the attribute in your application,
+then add a mapping from the Okta profile to the application.
+
+“Directory > Profile Editor > {Your Application} > Add Attribute”
+
+Create the attribute for the roles, groups, or both. **Make sure the attribute
+is of type `string array`.**
+
+
+
+On the “Okta User to {Your Application}” tab, map a `roles` or `groups`
+attribute you have configured to the application.
+
+
+
+Configure using these new attributes in Coder.
+
+```bash
+# This must be set to false. Coder uses this endpoint to grab the attributes.
+CODER_OIDC_IGNORE_USERINFO=false
+# No custom scopes are required.
+CODER_OIDC_SCOPES=openid,profile,email
+# Configure the group/role field using the attribute name in the application.
+CODER_OIDC_USER_ROLE_FIELD=approles
+# See our docs for mapping okta roles to coder roles.
+CODER_OIDC_USER_ROLE_MAPPING='{"admin-group":["template-admin","user-admin"]}'
+
+# If you added an attribute for groups, set that here.
+# CODER_OIDC_GROUP_FIELD=...
+```
+
+# (Advanced) Custom scopes to retrieve custom claims
+
+Okta does not support setting custom scopes and claims in the default
+authorization server used by your application. If you require this
+functionality, you must create (or modify) an authorization server.
+
+To see your custom authorization servers go to “Security > API”. Note the
+`default` authorization server **is not the authorization server your app is
+using.** You can configure this default authorization server, or create a new
+one specifically for your application.
+
+Authorization servers also give more refined controls over things such as
+token/session lifetimes.
+
+
+
+To get custom claims working, we should map them to a custom scope. Click the
+authorization server you wish to use (likely just using the default).
+
+Go to “Scopes”, and “Add Scope”. Feel free to create one for roles, groups, or
+both.
+
+
+
+Now create the claim to go with the said scope. Go to “Claims”, then “Add
+Claim”. Make sure to select **ID Token** for the token type. The **Value**
+expression is up to you based on where you are sourcing the role information.
+Lastly, configure it to only be a claim with the requested scope. This is so if
+other applications exist, we do not send them information they do not care
+about.
+
+
+
+Now we have a custom scope + claim configured under an authorization server, we
+need to configure coder to use this.
+
+```bash
+# Grab this value from the Authorization Server > Settings > Issuer
+# DO NOT USE the application issuer URL. Make sure to use the newly configured
+# authorization server.
+CODER_OIDC_ISSUER_URL=https://dev-12222860.okta.com/oauth2/default
+# Add the new scope you just configured
+CODER_OIDC_SCOPES=openid,profile,email,roles
+# Use the claim you just configured
+CODER_OIDC_USER_ROLE_FIELD=roles
+# See our docs for mapping okta roles to coder roles.
+CODER_OIDC_USER_ROLE_MAPPING='{"admin-group":["template-admin","user-admin"]}'
+```
+
+You can use the “Token Preview” page to verify it has been correctly configured
+and verify the `roles` is in the payload.
+
+
diff --git a/docs/guides/example-guide.md b/docs/guides/example-guide.md
new file mode 100644
index 0000000000000..820a6f3ffecdd
--- /dev/null
+++ b/docs/guides/example-guide.md
@@ -0,0 +1,54 @@
+# Guide Title (Only Visible in Github)
+
+
+December 13, 2023
+
+---
+
+This is a guide on how to make Coder guides, it is not listed on our
+[official guides page](coder.com/docs/v2/latest/guides) in the docs. This is
+intended for those who don't frequently contribute documentation changes to the
+`coder/coder` repository.
+
+## Content
+
+Defer to our
+[Contributing/Documentation](coder.com/docs/v2/latest/contributing/documentation)
+page for rules on technical writing.
+
+### Adding Photos
+
+Use relative imports in the markdown and store photos in
+`docs/images/guides//.png`.
+
+### Setting the author data
+
+At the top of this example you will find a small html snippet that nicely
+renders the author's name and photo, while linking to their Github profile.
+Before submitting your guide in a PR, replace `your_github_handle`,
+`your_github_profile_photo_url` and "Your Name". The entire `![]()
` element can
+be omitted.
+
+## Setting up the routes
+
+Once you've written your guide, you'll need to add its route to
+`docs/manifest.json` under `Guides` > `"children"` at the bottom:
+
+```json
+{
+ // Overrides the "# Guide Title" at the top of this file
+ "title": "Contributing to Guides",
+ "description": "How to add a guide",
+ "path": "./guides/my-guide-file.md"
+},
+```
+
+## Format before push
+
+Before pushing your guide to github, run `make fmt` to format the files with
+Prettier. Then, push your changes to a new branch and create a PR.
diff --git a/docs/guides/index.md b/docs/guides/index.md
new file mode 100644
index 0000000000000..d33a7a3ed35f6
--- /dev/null
+++ b/docs/guides/index.md
@@ -0,0 +1,10 @@
+# Guides and Tutorials
+
+Here you can find a list of employee-written guides on Coder for OSS and
+Enterprise. These tutorials are hosted on our
+[Github](https://github.com/coder/coder/) where you can leave feedback or
+request new topics to be covered.
+
+
+ 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.
+
diff --git a/docs/images/guides/okta/add_attribute.png b/docs/images/guides/okta/add_attribute.png
new file mode 100644
index 0000000000000..a849f95d8f8a1
Binary files /dev/null and b/docs/images/guides/okta/add_attribute.png differ
diff --git a/docs/images/guides/okta/add_claim.png b/docs/images/guides/okta/add_claim.png
new file mode 100644
index 0000000000000..f0ff24197ff28
Binary files /dev/null and b/docs/images/guides/okta/add_claim.png differ
diff --git a/docs/images/guides/okta/add_claim_with_roles.png b/docs/images/guides/okta/add_claim_with_roles.png
new file mode 100644
index 0000000000000..f0ff24197ff28
Binary files /dev/null and b/docs/images/guides/okta/add_claim_with_roles.png differ
diff --git a/docs/images/guides/okta/add_scope.png b/docs/images/guides/okta/add_scope.png
new file mode 100644
index 0000000000000..770487e4e393b
Binary files /dev/null and b/docs/images/guides/okta/add_scope.png differ
diff --git a/docs/images/guides/okta/api_view.png b/docs/images/guides/okta/api_view.png
new file mode 100644
index 0000000000000..59391210aa0f3
Binary files /dev/null and b/docs/images/guides/okta/api_view.png differ
diff --git a/docs/images/guides/okta/oidc_id_token.png b/docs/images/guides/okta/oidc_id_token.png
new file mode 100644
index 0000000000000..4a8ba3a87e0df
Binary files /dev/null and b/docs/images/guides/okta/oidc_id_token.png differ
diff --git a/docs/images/guides/okta/token_preview.png b/docs/images/guides/okta/token_preview.png
new file mode 100644
index 0000000000000..8f0ce8a6528b7
Binary files /dev/null and b/docs/images/guides/okta/token_preview.png differ
diff --git a/docs/manifest.json b/docs/manifest.json
index be663809c2d59..cf52cb481f4a5 100644
--- a/docs/manifest.json
+++ b/docs/manifest.json
@@ -1018,6 +1018,19 @@
"description": "Frequently asked questions",
"path": "./faqs.md",
"icon_path": "./images/icons/info.svg"
+ },
+ {
+ "title": "Guides",
+ "description": "Employee-authored tutorials",
+ "path": "./guides/index.md",
+ "icon_path": "./images/icons/notes.svg",
+ "children": [
+ {
+ "title": "Configuring Okta",
+ "description": "Custom claims/scopes with Okta for group/role sync",
+ "path": "./guides/configuring-okta.md"
+ }
+ ]
}
]
}