OKTA SSO group mappings docs (#178)

* OKTA SSO group mappings docs

* update screenshots plus some style and formatting fixes

* couple of style fixes

* fix lint errors in nav

---------

Co-authored-by: Rosie Yohannan <[email protected]>

Author: notthepoint

docs/guides/modules/ROOT/images/authentication/sso-group-mapping-okta-setup.png

@@ -91,7 +91,7 @@
 ** How-to guides
 *** xref:permissions-authentication:pull-an-image-from-aws-ecr-with-oidc.adoc[Pull an image from AWS ECR with OIDC]
 *** xref:execution-managed:run-a-job-in-a-container.adoc[Run a job in a container on your machine with Docker]
-*** xref:execution-managed:docker-compose.adoc[Installing and using docker-compose]
+*** xref:execution-managed:docker-compose.adoc[Installing and using Docker Compose]
 *** xref:execution-managed:high-uid-error.adoc[Debugging container ID cannot be mapped to host ID error]
 ** Image support policies
 *** xref:execution-managed:android-images-support-policy.adoc[Android images support policy]
@@ -188,7 +188,7 @@
 *** xref:deploy:deploy-ios-applications.adoc[Deploy iOS applications]
 *** xref:deploy:deploy-over-ssh.adoc[Deploy over SSH]
 *** xref:deploy:publish-packages-to-packagecloud.adoc[Publish packages to Packagecloud]
-*** xref:deploy:deploy-to-npm-registry.adoc[Deploy to NPM registry]
+*** xref:deploy:deploy-to-npm-registry.adoc[Deploy to npm registry]
 
 * Optimize
 ** xref:optimize:optimizations.adoc[Optimizations reference]
@@ -225,6 +225,7 @@
 ** SSO authentication
 *** xref:permissions-authentication:sso-overview.adoc[SSO overview]
 *** xref:permissions-authentication:set-up-sso.adoc[SSO setup]
+*** xref:permissions-authentication:sso-group-mapping.adoc[Set up SSO group mapping with Okta]
 *** xref:permissions-authentication:sign-in-to-an-sso-enabled-organization.adoc[Sign in to an SSO-enabled org]
 ** Multi-factor authentication (MFA)
 *** xref:permissions-authentication:mfa.adoc[MFA overview]
@@ -288,7 +289,7 @@
 
 * Developer toolkit
 ** AI features
-*** xref:toolkit:using-the-circleci-mcp-server.adoc[Using the CircleCI MCP Server]
+*** xref:toolkit:using-the-circleci-mcp-server.adoc[Using the CircleCI MCP server]
 *** xref:toolkit:intelligent-summaries.adoc[Intelligent summaries]
 ** CLI
 *** xref:toolkit:local-cli.adoc[Install and configure the CircleCI local CLI]
@@ -312,7 +313,7 @@
 * Plans and pricing
 ** xref:plans-pricing:plan-overview.adoc[CircleCI plans overview]
 ** xref:plans-pricing:credits.adoc[Credits overview]
-** xref:plans-pricing:plan-free.adoc[Free plan overview]
-** xref:plans-pricing:plan-performance.adoc[Performance plan overview]
-** xref:plans-pricing:plan-scale.adoc[Scale plan overview]
-** xref:plans-pricing:plan-server.adoc[Server plan overview]
+** xref:plans-pricing:plan-free.adoc[Free Plan overview]
+** xref:plans-pricing:plan-performance.adoc[Performance Plan overview]
+** xref:plans-pricing:plan-scale.adoc[Scale Plan overview]
+** xref:plans-pricing:plan-server.adoc[Server Plan overview]

docs/guides/modules/ROOT/images/authentication/sso-group-mapping-open.png

@@ -0,0 +1,47 @@
+= Set up SSO group mapping with Okta
+:page-platform: Cloud
+:page-description: Follow this guide to set up SSO (Single sign-on) group mapping with Okta and CircleCI.
+:experimental:
+
+SSO Group Mapping automatically assigns users from your identity provider (IdP) to groups in CircleCI. Group assignments are updated in real-time when users authenticate through SSO.
+This feature enables you to manage both groups and their members directly within your identity provider, streamlining user administration across your organization.
+
+NOTE: Once SSO Group Mapping is configured, your IdP will have complete control over group management. Any group assignments created manually within CircleCI will be overwritten when users authenticate via SSO. All group management must be performed through your identity provider.
+
+== Prerequisites
+
+Before you begin, ensure you have the following:
+
+* You are using Okta as your IdP and have access to your Okta admin console.
+* SSO is configured in your CircleCI organization and you have the organization admin role in CircleCI. For information on roles and permissions, see the xref:roles-and-permissions-overview.adoc[Roles and permissions overview].
+* Your CircleCI organization has one or more groups. For more information on groups, see xref:manage-groups.adoc[Manage groups].
+
+== How to set up group mapping with Okta
+
+=== 1. Configure Okta
+
+First, you will need to configure your Okta settings. Follow the steps below, or refer to link:https://help.okta.com/oie/en-us/content/topics/apps/define-group-attribute-statements.htm[Okta's group attribute statements documentation] for more detailed information.
+
+. Open your Okta admin console and navigate to Applications.
+. Select your CircleCI application.
+. Navigate to the Sign On tab and scroll down to SAML Attributes.
+. Add a group attribute statement with the name 'groups'.
+. Use the filter to limit which groups will sync to CircleCI. Use the regex value `.*` to capture all groups.
+
+.Okta SSO group attribute settings
+image::guides:ROOT:authentication/sso-group-mapping-okta-setup.png[Screenshot of the Okta SSO group attribute settings]
+
+=== 2. Configure CircleCI
+
+. In the link:https://app.circleci.com/home/[CircleCI web app], select your organization.
+. Select **Organization Settings** in the sidebar.
+. Select **Single sign-on (SSO)** from the sidebar.
+. Go to the Group Mappings section and click btn:[Add mapping]. This will open a form in a dropdown.
+. Enter the name of your Okta group under "SAML group name" and select the corresponding CircleCI group you want to map it to.
+. Select btn:[Add mapping] in the form to save your configuration.
+
+.Okta SSO group attribute settings in CircleCI
+image::guides:ROOT:authentication/sso-group-mapping-open.png[Screenshot of the Okta SSO group attribute settings]
+
+
+Once you have completed these steps, user assignments for any groups you have added to group mappings will be automatically updated when users authenticate via SSO into CircleCI.

docs/guides/modules/ROOT/nav.adoc

@@ -1528,5 +1528,10 @@
     "component": "guides",
     "module": "permissions-authentication",
     "filename": "set-up-sso.adoc"
+  },
+  "sso-group-mapping": {
+    "component": "guides",
+    "module": "permissions-authentication",
+    "filename": "sso-group-mapping.adoc"
   }
 }