Skip to content

iam: idp-initiated doc updates #23598

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

Draft
wants to merge 2 commits into
base: main
Choose a base branch
from
+55 −27
Draft

iam: idp-initiated doc updates #23598

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
0f23607
iam: idp-initiated doc updates
sarahsanders-docker Oct 23, 2025
935fdee
remove troubleshooting section
sarahsanders-docker Oct 23, 2025
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
57 changes: 53 additions & 4 deletions content/manuals/enterprise/security/single-sign-on/_index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,12 +18,59 @@ identity providers (IdPs). SSO can be configured for an entire company,
including all associated organizations, or for a single organization that has a
Docker Business subscription.

## SSO authentication flows

Docker supports two authentication flows for SSO.

### Service-provider initiated (SP-initiated) flow

Users begin the authentication process from Docker Hub or Docker Desktop. Users
navigate to Docker's sign-in page and are then redirected to your IdP for
authentication.

> [!NOTE]
>
> This is the default and recommended flow for all SSO connections.

### Identity provider-initiated (IdP-initiated) flow

In the IdP-initiated flow, users start the authentication process directly from
your IdP's portal or dashboard. After authenticating with the IdP, users are
automatically redirected to Docker services.
Copy link
Contributor

@ivan-californias ivan-californias Oct 23, 2025 •
edited
Loading

Choose a reason for hiding this comment

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

suggestion: make more clear that users will get signed in into Docker home only (web), but not into Docker Desktop. However, if they try to sign in on DD next, it will pick up the established session.


IdP-initiated flow is:

- Only available for SAML-based SSO connections
- Disabled by default
- Not applicable to OIDC or Azure AD connections

Enabling IdP-initiated authentication introduces additional security risks
that you should carefully evaluate:

- CSRF (Cross-Site Request Forgery) vulnerability: IdP-initiated flows are more
susceptible to CSRF attacks where malicious actors could potentially trick
users into unintended authentication actions.
- Reduced security controls: The SP-initiated flow provides additional
validation and security checks that may be bypassed in IdP-initiated flows.
- Session management complexity: IdP-initiated flows can make it more difficult
to track and manage user sessions consistently.
Comment on lines +55 to +56
Copy link
Contributor

@ivan-californias ivan-californias Oct 23, 2025

Choose a reason for hiding this comment

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

thought: Not sure if this last point is true


For detailed security considerations, see
[Auth0's guidance on IdP-initiated SSO](https://auth0.com/docs/authenticate/protocols/saml/saml-sso-integrations/idp-initiated-sso).

> [!WARNING]
>
> Only enable IdP-initiated flow if your organization specifically requires it.
The SP-initiated flow provides better security and is recommended for most use
cases.

## How SSO works

When SSO is enabled, Docker supports a non-IdP-initiated flow for user sign-in.
Instead of signing in with a Docker username and password, users are redirected
to your IdP’s sign-in page. Users must initiate the SSO authentication process
by signing in to Docker Hub or Docker Desktop.
When SSO is enabled, users sign in to Docker through your identity provider
instead of using a Docker username and password. Users must initiate the SSO
authentication process by signing in to Docker Hub or Docker Desktop
(SP-initiated), or optionally through your IdP portal if IdP-initiated flow is
enabled for SAML connections.

The following diagram illustrates how SSO operates and is managed between
Docker Hub, Docker Desktop, and your IdP.
Expand All @@ -37,6 +84,8 @@ To configure SSO in Docker, follow these steps:
1. [Configure your domain](configure.md) by creating and verifying it.
1. [Create your SSO connection](connect.md) in Docker and your IdP.
1. Link Docker to your identity provider.
1. Optional. For SAML connections, enable IdP-initiated flow if required
by your organization.
1. Test your SSO connection.
1. Provision users in Docker.
1. Optional. [Enforce sign-in](../enforce-sign-in/_index.md).
Expand Down
1 change: 1 addition & 0 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 @@ -133,6 +133,7 @@ Complete the integration by pasting your IdP values into Docker.
{{< tab name="Okta SAML" >}}

1. In Okta, select your app and go to **View SAML setup instructions**.
1. Optional. Select the checkbox to **Enable IdP-initiated** option.
1. Copy the **SAML Sign-in URL** and **x509 Certificate**.

> [!IMPORTANT]
Expand Down
23 changes: 0 additions & 23 deletions content/manuals/enterprise/troubleshoot/troubleshoot-sso.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -114,29 +114,6 @@ If you have SCIM enabled, troubleshoot your SCIM connection using the following
1. Ensure that the attributes being synced from your IdP match Docker's [supported attributes](/manuals/enterprise/security/provisioning/scim.md#supported-attributes) for SCIM.
1. Test user provisioning by trying to provision a test user through your IdP and verify if they appear in Docker.

## IdP-initiated sign in is not enabled for connection

### Error message

When this issue occurs, the following error message is common:
```text
IdP-Initiated sign in is not enabled for connection '$ssoConnection'.
```

### Causes

Docker does not support an IdP-initiated SAML flow. This error occurs when a user attempts to authenticate from your IdP, such as using the Docker SSO app tile on the sign in page.

### Solutions

**Authenticate from Docker apps**

The user must initiate authentication from Docker applications (Hub, Desktop, etc). The user needs to enter their email address in a Docker app and they will get redirected to the configured SSO IdP for their domain.

**Hide the Docker SSO app**

You can hide the Docker SSO app from users in your IdP. This prevents users from attempting to start authentication from the IdP dashboard. You must hide and configure this in your IdP.

## Not enough seats in organization

### Error message
Expand Down
1 change: 1 addition & 0 deletions hugo_stats.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -135,6 +135,7 @@
"Svelte",
"Testcontainers-Cloud",
"TypeScript",
"Typescript",
"Ubuntu",
"Ubuntu/Debian",
"Unix-pipe",
Expand Down