From 0f2360779d1acf5ff85c0ecc5b5fbeec9169d53e Mon Sep 17 00:00:00 2001 From: sarahsanders-docker Date: Thu, 23 Oct 2025 10:40:58 -0400 Subject: [PATCH] iam: idp-initiated doc updates --- .../security/single-sign-on/_index.md | 57 +++++++++++++++++-- .../security/single-sign-on/connect.md | 1 + hugo_stats.json | 1 + 3 files changed, 55 insertions(+), 4 deletions(-) diff --git a/content/manuals/enterprise/security/single-sign-on/_index.md b/content/manuals/enterprise/security/single-sign-on/_index.md index 8c3156842e..a45f87fdca 100644 --- a/content/manuals/enterprise/security/single-sign-on/_index.md +++ b/content/manuals/enterprise/security/single-sign-on/_index.md @@ -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. + +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. + +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. @@ -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). diff --git a/content/manuals/enterprise/security/single-sign-on/connect.md b/content/manuals/enterprise/security/single-sign-on/connect.md index d8c3b46a6f..6e91b47d97 100644 --- a/content/manuals/enterprise/security/single-sign-on/connect.md +++ b/content/manuals/enterprise/security/single-sign-on/connect.md @@ -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] diff --git a/hugo_stats.json b/hugo_stats.json index 4907c59ce4..2947f53879 100644 --- a/hugo_stats.json +++ b/hugo_stats.json @@ -135,6 +135,7 @@ "Svelte", "Testcontainers-Cloud", "TypeScript", + "Typescript", "Ubuntu", "Ubuntu/Debian", "Unix-pipe",