SSO doc updates by akristen · Pull Request #24129 · docker/docs

akristen · 2026-02-10T22:37:54Z

This PR updates SSO documentation to address inconsistencies, per tech support's jira ticket. I've made some additional changes as well:

I've removed 4/5ish call outs throughout the doc. Callouts lose effectiveness if you use them often.
I've condensed certain redundant UI steps like "Save", "Finish", "Select X" and created more compound steps. This shortens the procedures and simplifies the ~weight of each substep.
Merged Configure and Connect docs into one. Having 1 doc for two steps when they're necessary for the overall action risks losing users and adding confusion.
I've added Prerequisites from the index page to the actual procedures. Prereqs should always be associated closely with the action users are taking after establishing those pre-requisites.

…ction section to address ticket

netlify · 2026-02-10T22:37:59Z

✅ Deploy Preview for docsdocker ready!

Name	Link
🔨 Latest commit	`1365158`
🔍 Latest deploy log	https://app.netlify.com/projects/docsdocker/deploys/69b08d63d8b363000868dd8d
😎 Deploy Preview	https://deploy-preview-24129--docsdocker.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

github-actions

Documentation Review

I've reviewed the SSO documentation updates and found several issues that should be addressed:

Critical Issues (2)

Malformed callout syntax (line 119): The IMPORTANT callout has incorrect indentation that will break rendering
Stray character in callout (line 120): An embedded ">" character disrupts the text

Formatting Issues (2)

Inconsistent hyphenation (line 13): "set-up" should be "setup" per style guide
Extra space in list (line 30): Bullet point has two spaces instead of one

Please see the inline comments for details and suggested fixes.

content/manuals/enterprise/security/single-sign-on/connect.md

gonzo919

Updates complete

gonzo919 · 2026-02-13T14:35:55Z

content/manuals/enterprise/security/single-sign-on/connect.md

 {{< tab name="Okta SAML" >}}

-1. Sign in to your Okta account and open the Admin portal.
-1. Select **Administration** and then **Create App Integration**.


Should read "Applications"

gonzo919 · 2026-02-13T14:40:58Z

content/manuals/enterprise/security/single-sign-on/connect.md

 {{< tabs >}}
 {{< tab name="Okta SAML" >}}

 1. In Okta, select your app and go to **View SAML setup instructions**.


Should say, In Okta, select your app, go to Sign On tab and go to View SAML setup instructions.

…configure doc from docs site, move prereqs from index to the procedures

akristen · 2026-03-10T20:15:08Z

/review

…the left nav more cohesively

docker-agent

Review Summary

This PR consolidates SSO documentation by merging configure.md into connect.md. The reorganization improves document structure by combining related content, which aligns with user workflow. However, there are a few issues that need attention:

🟡 NEEDS ATTENTION

Issues Found

MEDIUM Severity

Broken link anchor in configure-admin-console.md

LOW Severity

Minor style guide inconsistencies in phrasing

Assessment

The documentation consolidation is valuable and the redirect aliases are properly configured. The critical issue is a broken link anchor that will send users to the wrong section. The low-severity issues are minor style improvements that would enhance clarity and consistency with Docker's style guide.

docker-agent · 2026-03-10T20:22:16Z

.../manuals/enterprise/security/hardened-desktop/settings-management/configure-admin-console.md


 - [Docker Desktop 4.37.1 or later](/manuals/desktop/release-notes.md) installed
- [A verified domain](/manuals/enterprise/security/single-sign-on/configure.md#step-one-add-and-verify-your-domain)
+- [A verified domain](/manuals/enterprise/security/single-sign-on/connect.md#step-one-add-and-verify-your-domain)


ISSUE: Broken link anchor

The link points to connect.md#step-one-add-and-verify-your-domain but this anchor doesn't exist in the new connect.md file. The heading in connect.md is now ### Step 1: Add a domain which generates the anchor #step-1-add-a-domain.

Suggested fix:

- [A verified domain](/manuals/enterprise/security/single-sign-on/connect.md#step-1-add-a-domain)

Or remove the anchor to link to the top of the page:

- [A verified domain](/manuals/enterprise/security/single-sign-on/connect.md)

docker-agent · 2026-03-10T20:22:17Z

content/manuals/enterprise/security/single-sign-on/connect.md

-1. Copy the required values for your IdP:
+### Step 3. Create an SSO connection in Docker
+
+1. From [Docker Home](https://app.docker.com), choose your


Style: Awkward phrasing with 'toggle'

The phrase "toggle the Admin Console dropdown" is imprecise. According to the Docker style guide, navigation instructions should be direct and use "select" rather than action verbs like "toggle."

Suggested revision:

organization, select **Admin Console** from the dropdown, then select **SSO and SCIM** from the **Security** section.

Or:

organization and select **Admin Console** > **Security** > **SSO and SCIM**.

docker-agent · 2026-03-10T20:22:17Z

content/manuals/enterprise/security/single-sign-on/connect.md


 {{< tabs >}}
 {{< tab name="Okta SAML" >}}



Style: Could be more direct

The phrase "To enable SSO with Okta, you need..." is slightly indirect. The Docker style guide recommends removing unnecessary phrasing like "To enable" in favor of more direct language.

Suggested revision:

Enabling SSO with Okta requires [super admin](https://help.okta.com/en-us/content/topics/security/administrators-super-admin.htm) permissions for the Okta org.

Or even simpler:

You need [super admin](https://help.okta.com/en-us/content/topics/security/administrators-super-admin.htm) permissions for the Okta org.

docker-agent · 2026-03-10T20:22:17Z

content/manuals/enterprise/security/single-sign-on/connect.md

-    - Docker Entity ID -> **Audience URI (SP Entity ID)**
-1. Configure the following settings:
+To enable SSO with Okta, you need [super admin](https://help.okta.com/en-us/content/topics/security/administrators-super-admin.htm) permissions for the Okta org. 
+


Style: Could be more direct and consistent

The phrasing "Open the Admin portal from your Okta account and select..." could be simplified for consistency with other steps in the document.

Suggested revision:

1. In the Okta Admin portal, select **Administration**.

Or:

1. Sign in to the Okta Admin portal and select **Administration**.

akristen added 2 commits February 10, 2026 14:45

initial updates around doc structure

63f202f

Simplify procedures and add context to certain steps, edit test conne…

f0fdefe

…ction section to address ticket

akristen added 2 commits February 10, 2026 16:52

fixing some errors, fixing the weird callout, fixing the steps

b7d6f09

fixing build issues

73d8391

akristen self-assigned this Feb 10, 2026

akristen added the area/admin Relates to Docker Admin label Feb 10, 2026

akristen marked this pull request as ready for review February 13, 2026 15:13

github-actions bot reviewed Feb 13, 2026

View reviewed changes

some light copyedit changes

34b3c7e

gonzo919 reviewed Feb 19, 2026

View reviewed changes

merge Connect and Configure doc into one doc, remove references from …

424c1f1

…configure doc from docs site, move prereqs from index to the procedures

akristen added 2 commits March 10, 2026 15:16

change linktitle to match what it's telling users to do

0ff9e74

update title to be more descriptive/obvious and add weights to order …

82c629d

…the left nav more cohesively

docker-agent bot reviewed Mar 10, 2026

View reviewed changes

update some titles to distinguish btwn other manage docs

1365158

Conversation

akristen commented Feb 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

netlify bot commented Feb 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for docsdocker ready!

Uh oh!

github-actions bot left a comment

Choose a reason for hiding this comment

Documentation Review

Critical Issues (2)

Formatting Issues (2)

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

gonzo919 left a comment

Choose a reason for hiding this comment

Uh oh!

gonzo919 Feb 13, 2026

Choose a reason for hiding this comment

Uh oh!

gonzo919 Feb 13, 2026

Choose a reason for hiding this comment

Uh oh!

akristen commented Mar 10, 2026

Uh oh!

docker-agent bot left a comment

Choose a reason for hiding this comment

Review Summary

Issues Found

Assessment

Uh oh!

docker-agent bot Mar 10, 2026

Choose a reason for hiding this comment

Uh oh!

docker-agent bot Mar 10, 2026

Choose a reason for hiding this comment

Uh oh!

docker-agent bot Mar 10, 2026

Choose a reason for hiding this comment

Uh oh!

docker-agent bot Mar 10, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

akristen commented Feb 10, 2026 •

edited

Loading

netlify bot commented Feb 10, 2026 •

edited

Loading