Skip to content

SSO doc updates #24129

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
akristen wants to merge 4 commits into
base: main
Choose a base branch
from
+67 −82
Open

SSO doc updates #24129

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
63f202f
initial updates around doc structure
akristen Feb 10, 2026
f0fdefe
Simplify procedures and add context to certain steps, edit test conne…
akristen Feb 10, 2026
b7d6f09
fixing some errors, fixing the weird callout, fixing the steps
akristen Feb 10, 2026
73d8391
fixing build issues
akristen Feb 10, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
149 changes: 67 additions & 82 deletions content/manuals/enterprise/security/single-sign-on/connect.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,96 +10,84 @@
{{< summary-bar feature_name="SSO" >}}

Setting up a single sign-on (SSO) connection involves configuring both Docker
and your identity provider (IdP). This guide walks you through setup
in Docker, setup in your IdP, and final connection.
and your identity provider (IdP). This guide walks you through set-up
Copy link
Contributor

@github-actions github-actions bot Feb 13, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Inconsistent noun hyphenation

The word appears as "set-up" in "This guide walks you through set-up". Per STYLE.md, hyphens are used for compound adjectives before nouns (e.g., "up-to-date documentation"), not for nouns themselves. In this context, "set-up" is a noun and should be "setup" without hyphenation.

Suggested fix: Change "set-up" to "setup" on both lines 13 and 14.

in Docker, set-up in your IdP, and final connection.

> [!TIP]
>
> You’ll copy and paste values between Docker and your IdP. Complete this guide
in one session with separate browser windows open for Docker and your IdP.
## Prerequisites

Before you begin:

- Verify your domain. You must [verify at least one domain](/manuals/enterprise/security/single-sign-on/configure.md) before creating an SSO connection.
- Set up an account with your identity provider (IdP).
- Complete the steps in the [Configure single sign-on](configure.md) guide.

## Supported identity providers
## Set up SSO for Docker

Docker supports any SAML 2.0 or OIDC-compatible identity provider. This guide
provides detailed setup instructions for the most commonly
used providers: Okta and Microsoft Entra ID.

If you're using a
used providers: Okta and Microsoft Entra ID. If you're using a
different IdP, the general process remains the same:

Copy link
Contributor

@github-actions github-actions bot Feb 13, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Extra space in bullet list item

This line has "- Complete..." with two spaces after the dash. Adjacent bullet points on lines 28-29 and 31 use a single space after the dash.

Suggested fix: Change "- Complete" to "- Complete" (single space after dash).

1. Configure the connection in Docker.
1. Set up the application in your IdP using the values from Docker.
1. Complete the connection by entering your IdP's values back into Docker.
1. Test the connection.
- Configure the connection in Docker.
- Set up the application in your IdP using the values from Docker.
- Complete the connection by entering your IdP's values back into Docker.
- Test the connection.

## Prerequisites

Before you begin:
These procedures prompt you to navigate between Docker docs and IdP docs. You will also need to copy and paste values
between Docker and your IdP. Complete this guide in one session with separate browser windows open for Docker and your IdP.

- Verify your domain
- Set up an account with your identity provider (IdP)
- Complete the steps in the [Configure single sign-on](configure.md) guide

## Step one: Create an SSO connection in Docker

> [!NOTE]
>
> You must [verify at least one domain](/manuals/enterprise/security/single-sign-on/configure.md) before creating an SSO connection.
### Create an SSO connection in Docker

1. Sign in to [Docker Home](https://app.docker.com) and choose your
organization.
1. Select **Admin Console**, then **SSO and SCIM**.
1. Select **Create Connection** and provide a name for the connection.
1. Select an authentication method: **SAML** or **Azure AD (OIDC)**.
1. Copy the required values for your IdP:
1. From [Docker Home](https://app.docker.com), choose your
organization and toggle the **Admin Console** dropdown. Select **SSO and SCIM** from the **Security** section.

Check warning on line 42 in content/manuals/enterprise/security/single-sign-on/connect.md

View workflow job for this annotation

GitHub Actions / validate (vale) 

[vale] reported by reviewdog 🐶
[Docker.RecommendedWords] Consider using 'drop-down' instead of 'dropdown'

Raw Output:
{"message": "[Docker.RecommendedWords] Consider using 'drop-down' instead of 'dropdown'", "location": {"path": "content/manuals/enterprise/security/single-sign-on/connect.md", "range": {"start": {"line": 42, "column": 47}}}, "severity": "INFO"}
1. Select **Create Connection** and name the connection. Choose either **SAML** or **Azure AD (OIDC)** for your authentication method.
1. Copy the required values for your IdP and store these values in a text editor:
- Okta SAML: **Entity ID**, **ACS URL**
- Azure OIDC: **Redirect URL**

Keep this window open to paste values from your IdP later.

## Step two: Create an SSO connection in your IdP
### Create an SSO connection in your IdP

Use the following tabs based on your IdP provider.

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

1. Sign in to your Okta account and open the Admin portal.
1. Select **Administration** and then **Create App Integration**.
1. Select **SAML 2.0**, then **Next**.
1. Name your app "Docker".
1. Optional. Upload a logo.
1. Paste values from Docker:
- Docker ACS URL -> **Single Sign On URL**
- 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.

1. Open the Admin portal from your Okta account and select **Administration**.
1. Choose **Create App Integration** and select **SAML 2.0**.
- When prompted, name your app "Docker."
- You may upload a logo, but it's not required.
1. Paste the values you copied from creating an SSO connection in Docker:
- For the **Single Sign On URL** value, paste the Docker ACS URL.
- For the **Audience URI (SP Entity ID)** value, paste the Docker Entity ID.
1. Configure the following settings. These settings determine the primary identification method your IdP sends to Docker for verification:
- Name ID format: `EmailAddress`
- Application username: `Email`
- Update application on: `Create and update`
1. Optional. Add SAML attributes. See [SSO attributes](/manuals/enterprise/security/provisioning/_index.md#sso-attributes).
1. Select **Next**.
1. Select the **This is an internal app that we have created** checkbox.
1. Select **Finish**.
1. Optional. Add [SAML attributes](/manuals/enterprise/security/provisioning/_index.md#sso-attributes), if required by your org.
1. Select the **This is an internal app that we have created** checkbox before finishing.

{{< /tab >}}
{{< tab name="Entra ID SAML 2.0" >}}

1. Sign in to Microsoft Entra (formerly Azure AD).
1. Select **Default Directory** > **Add** > **Enterprise Application**.
1. Choose **Create your own application**, name it "Docker", and choose **Non-gallery**.
To enable SSO with Microsoft Entra, you need [Cloud Application Administrator](https://learn.microsoft.com/en-us/entra/identity/role-based-access-control/permissions-reference#cloud-application-administrator) permissions.

1. From Microsoft Entra admin center, select **Entra ID**, then go to **Enterprise apps**. Select **All applications**.
1. Choose **Create your own application** and name your app "Docker". Select **Non-gallery**.
1. After creating your app, go to **Single Sign-On** and select **SAML**.
1. Select **Edit** on the **Basic SAML configuration** section.
1. Edit **Basic SAML configuration** and paste values from Docker:
- Docker Entity ID -> **Identifier**
- Docker ACS URL -> **Reply URL**
1. Optional. Add SAML attributes. See [SSO attributes](/manuals/enterprise/security/provisioning/_index.md#sso-attributes).
1. Save the configuration.
1. Select **Edit** on the **Basic SAML configuration** section. From **Basic SAML configuration**, choose **Edit** and paste the values you copied from creating an SSO connection in Docker:
- For the **Identifier** value, paste the Docker Entity ID.
- For the **Reply URL** value, paste Docker ACS URL.
1. Optional. Add [SAML attributes](/manuals/enterprise/security/provisioning/_index.md#sso-attributes), if required by your org.
1. From the **SAML Signing Certificate** section, download your **Certificate (Base64)**.

{{< /tab >}}
{{< tab name="Azure Connect (OIDC)" >}}

### Register the app
#### Register the app

1. Sign in to Microsoft Entra (formerly Azure AD).
1. Select **App Registration** > **New Registration**.
Expand All @@ -108,13 +96,13 @@
1. Select **Register**.
1. Copy the **Client ID**.

### Create client secrets
#### Create client secrets

1. In your app, go to **Certificates & secrets**.
1. Select **New client secret**, describe and configure duration, then **Add**.
1. Copy the **value** of the new secret.

### Set API permissions
#### Set API permissions

1. In your app, go to **API permissions**.
1. Select **Grant admin consent** and confirm.
Expand All @@ -125,22 +113,22 @@
{{< /tab >}}
{{< /tabs >}}

## Step three: Connect Docker to your IdP
### Connect Docker to your IdP

Complete the integration by pasting your IdP values into Docker.

Copy link
Contributor

@github-actions github-actions bot Feb 13, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Malformed callout syntax will break rendering

The IMPORTANT callout has improper indentation with 4 spaces before the ">" character on continuation lines. Per COMPONENTS.md, callout syntax requires each line to start with "> " without any leading spaces.

Current format (broken):

> [!IMPORTANT]
    > 
    > When prompted to copy...

Correct format:

> [!IMPORTANT]
>
> When prompted to copy a certificate, copy the entire certificate starting with `----BEGIN CERTIFICATE----` and including the `----END CERTIFICATE----` lines.

This syntax error will prevent the callout from rendering correctly.

> [!IMPORTANT]
Copy link
Contributor

@github-actions github-actions bot Feb 13, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Stray character disrupts callout text

Line 120 contains "starting > with" where a stray ">" character appears embedded in the text. This should read "starting with ----BEGIN CERTIFICATE----" without the embedded ">".

This appears to be related to the malformed callout syntax on line 119. When fixing the callout indentation, this stray character should also be removed.

>
> When prompted to copy a certificate, copy the entire certificate starting > with `----BEGIN CERTIFICATE----` and including the `----END
> CERTIFICATE----` lines.

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

1. In Okta, select your app and go to **View SAML setup instructions**.
1. Copy the **SAML Sign-in URL** and **x509 Certificate**.

> [!IMPORTANT]
>
> Copy the entire certificate, including `----BEGIN CERTIFICATE----` and `----END CERTIFICATE----` lines.
1. Return to the Docker Admin Console.
1. Copy the **SAML Sign-in URL** and **x509 Certificate**, then return to the Docker Admin Console.
1. Paste the **SAML Sign-in URL** and **x509 Certificate** values.
1. Optional. Select a default team.
1. Optional. Select a default team, if required by your org.
1. Review and select **Create connection**.

{{< /tab >}}
Expand All @@ -150,13 +138,8 @@
1. Copy the following values:
- From Azure AD: **Login URL**
- **Certificate (Base64)** contents

> [!IMPORTANT]
>
> Copy the entire certificate, including `----BEGIN CERTIFICATE----` and `----END CERTIFICATE----` lines.
1. Return to the Docker Admin Console.
1. Paste the **Login URL** and **Certificate (Base64)** values.
1. Optional. Select a default team.
1. Return to the Docker Admin Console, then paste the **Login URL** and **Certificate (Base64)** values.
1. Optional. Select a default team, if required by your org.
1. Review and select **Create connection**.

{{< /tab >}}
Expand All @@ -167,30 +150,32 @@
- **Client ID**
- **Client Secret**
- **Azure AD Domain**
1. Optional. Select a default team.
1. Optional. Select a default team, if required by your org.
1. Review and select **Create connection**.

{{< /tab >}}
{{< /tabs >}}

## Step four: Test the connection
### Test the connection

IdPs like Microsoft Entra and Okta may require that you assign a user to an application before testing SSO. You can review [Microsoft Entra](https://learn.microsoft.com/en-us/entra/identity/enterprise-apps/add-application-portal-setup-sso#test-single-sign-on)'s documentation and [Okta](https://help.okta.com/wf/en-us/content/topics/workflows/connector-reference/okta/actions/assignusertoapplicationforsso.htm)'s documentation to learn how to assign yourself or other users to an app.

After assigning yourself to an app:

1. Open an incognito browser window.
1. Sign in to the Admin Console using your **domain email address**.
1. The browser will redirect to your identity provider's sign in page to authenticate. If you have [multiple IdPs](#optional-configure-multiple-idps), choose the sign sign-in option **Continue with SSO**.
1. Authenticate through your domain email instead of using your Docker ID.
1. Open an incognito browser window and sign in to the Admin Console using your domain email address.
1. When redirected to your IdP's sign in page, authenticate with your domain email instead of using your Docker ID.

If you're using the CLI, you must authenticate using a personal access token.
If you have multiple IdPs, choose the sign-in option **Continue with SSO**. If you're using the CLI, you must authenticate using a personal access token.

## Optional: Configure multiple IdPs
## Configure multiple IdPs

Docker supports multiple IdP configurations. To use multiple IdPs with one domain:

- Repeat Steps 1-4 on this page for each IdP.
- Each connection must use the same domain.
- Users will select **Continue with SSO** to choose their IdP at sign in.

## Optional: Enforce SSO
## Enforce SSO

> [!IMPORTANT]
>
Expand Down