admin: add sso troubleshooting (#20497)

* admin: add sso troubleshooting

Signed-off-by: Craig Osterhout <craig.osterhout@docker.com>

content/security/for-admins/single-sign-on/troubleshoot.md

@@ -0,0 +1,161 @@
+---
+description: Learn how to troubleshoot common SSO issues.
+keywords: sso, troubleshoot, single sign-on
+title: Troubleshoot single sign-on
+---
+
+While configuring or using single sign-on (SSO), you may encounter issues that
+can stem from your identity provider (IdP) or Docker configuration. The
+following sections describe how to view the error messages in the Docker Admin
+Console as well as some common errors and possible solutions. You can also see
+your identity provider's documentation to learn if you can view error logs in
+their service.
+
+## View SSO and SCIM error logs
+
+1. Sign in to the [Admin Console](https://app.docker.com/admin/).
+2. Select your organization or company in the left navigation drop-down menu,
+   and then select **SSO and SCIM**.
+3. In the SSO connections table, select the **Actions** icon and **View error
+   logs**. The **Connection errors** page appears with a list of errors that
+   have occurred in the past 7 days.
+4. In the **Connection errors** page, select **View error details** next to an
+   error message for more details. A modal appears with a JSON object containing
+   more details.
+
+## Common SSO errors and solutions
+
+[View the SSO and SCIM error logs](#view-sso-and-scim-error-logs) and then use
+the following sections for solutions to common configuration errors.
+
+### IdP-initiated sign in is not enabled for connection
+
+An error message, similar to the following, appears in the error logs for this
+issue.
+
+```text
+IdP-Initiated sign in is not enabled for connection '$ssoConnection'.
+```
+
+Docker doesn't support an IdP-initiated SAML flow. This error can occur when a
+user attempts to authenticate from the IdP, for example using the Docker SSO App
+tile on the dashboard.
+
+Possible solutions:
+
+ * The user must initiate authentication from Docker apps (Hub, Desktop, etc).
+   The user needs to enter their email address and they will get redirected to
+   the configured SSO IdP for their domain.
+ * (Optional) Configure the Docker SSO App as not visible to users on your IdP
+   so users don’t attempt to start authentication from there.
+
+### Not enough seats in organization
+
+An error message, similar to the following, appears in the error logs for this
+issue.
+
+```text
+Not enough seats in organization '$orgName'. Add more seats or contact your administrator.
+```
+
+This error can occur when attempting to provision a user into the organization
+via SSO Just-in-Time provisioning or SCIM, but the organization has no available
+seats for the user.
+
+Possible solutions:
+
+ * Add more Docker Business subscription seats to the organization. For details,
+   see [Add seats to your
+  subscription](/subscription/core-subscription/add-seats/).
+ * Remove some users or pending invitations from your organization to make more
+   seats available. For more details, see [Manage organization
+   members](/admin/organization/members/).
+
+### Domain is not verified for SSO connection
+
+An error message, similar to the following, appears in the error logs for this
+issue.
+
+```text
+Domain '$emailDomain' is not verified for your SSO connection. Contact your company administrator. TraceID: XXXXXXXXXXXXXX
+```
+
+This error occurs if the IdP authenticated a user through SSO and the UPN
+returned to Docker doesn’t match any of the verified domains associated to the
+SSO connection configured in Docker.
+
+Possible solutions:
+
+ * Make sure the IdP SSO connection is returning the correct UPN value as part
+   of the assertion attributes (attributes mapping).
+ * Add and verify all domains and subdomains that are used as UPN by your IdP
+   and associate them to your Docker SSO connection. For more details, see [Add
+   and verify your
+   domain](/security/for-admins/single-sign-on/configure/#step-one-add-and-verify-your-domain).
+
+### Unable to find session
+
+An error message, similar to the following, appears in the error logs for this
+issue.
+
+```text
+We couldn't find your session. You may have pressed the back button, refreshed the page, opened too many sign-in dialogs, or there is some issue with cookies. Try signing in again. If the issue persists, contact your administrator.
+```
+
+This error typically occurs during the authentication flow when a user presses
+the back or the refresh button on the browser. This causes the sign-in flow to
+lose track of the initial authentication request, which is required to complete
+all authentication flows.
+
+Possible solutions:
+
+ * Avoid pressing the back or refresh buttons during sign in.
+ * Close the browser’s tab and start the authentication flow from the beginning
+   in the app (Docker Desktop, Hub, etc.)
+
+### User is not assigned to the organization
+
+An error message, similar to the following, appears in the error logs for this
+issue.
+
+```text
+User '$username' is not assigned to this SSO organization. Contact your administrator. TraceID: XXXXXXXXXXXXX
+```
+
+This error occurs if SSO Just-In-Time (JIT) provisioning is disabled. JIT
+provisioning ensures that a user is added to an organization after they
+authenticate via SSO. JIT provisioning can be optionally disabled to prevent
+users taking seats in the organization automatically or when SCIM is used as
+the only option for user provisioning.
+
+Possible solutions:
+
+ * Review your SSO connection configuration and enable JIT provisioning to add
+   all users to the organization after authenticating via SSO. For more details,
+   see [Just-in-Time
+   provisioning](/security/for-admins/provisioning/just-in-time/).
+ * If JIT provisioning should remain disabled, then add the user to the
+   organization by manually inviting them. Next time the user authenticates via
+   SSO they will get added to the org because they are invited. For more
+   details, see [Manage organization members](/admin/organization/members/).
+ * If SCIM should provision the user, then ensure that the IdP controlling SCIM
+   provisioning is properly configured to synchronize users with Docker as soon
+   as they get assigned to the app. For more details, refer to your identity
+   provider's documentation.
+
+### Name ID is not an email address
+
+An error message, similar to the following, appears in the error logs for this
+issue.
+
+```text
+The name ID sent by the identity provider is not an email address. Contact your company administrator.
+```
+
+This error can occur during SAML authentication, when your IdP sends back a Name
+ID (UPN) that doesn't comply with the email address format required. The Docker
+SSO app requires a name identifier to be the primary email address of the user.
+
+Possible solutions:
+
+ * Ensure that the Name ID attribute format is `EmailAddress`.

data/toc.yaml

@@ -2267,7 +2267,7 @@ Manuals:
     title: Overview
   - sectiontitle: For admins
     section:
-    - sectiontitle: Single Sign-on
+    - sectiontitle: Single sign-on
       section:
       -  path: /security/for-admins/single-sign-on/
          title: Overview
@@ -2279,6 +2279,8 @@ Manuals:
          title: Connect
       -  path: /security/for-admins/single-sign-on/manage/
          title: Manage
+      -  path: /security/for-admins/single-sign-on/troubleshoot/
+         title: Troubleshoot
     - sectiontitle: Provisioning
       section:
       - path: /security/for-admins/provisioning/scim/