mirror of https://github.com/docker/docs.git
sso: update troubleshooting guide (#22001)
## Description - Added troubleshooting guide for SSO group mapping: https://deploy-preview-22001--docsdocker.netlify.app/security/troubleshoot/troubleshoot-sso/ - Moved old SSO troubleshooting guide to new file, added aliases - Reformatted old SSO troubleshooting content to match new template ## Related issues or tickets - [ENGDOCS-2367](https://docker.atlassian.net/browse/ENGDOCS-2367) ## Reviews - [ ] Editorial review [ENGDOCS-2367]: https://docker.atlassian.net/browse/ENGDOCS-2367?atlOrigin=eyJpIjoiNWRkNTljNzYxNjVmNDY3MDlhMDU5Y2ZhYzA5YTRkZjUiLCJwIjoiZ2l0aHViLWNvbS1KU1cifQ
This commit is contained in:
Sarah Sanders
GitHub
parent
6827d48e39
commit
bfbd3d7494
|
|
@ -1,165 +0,0 @@
|
|||
---
|
||||
description: Learn how to troubleshoot common SSO issues.
|
||||
keywords: sso, troubleshoot, single sign-on
|
||||
title: Troubleshoot single sign-on
|
||||
linkTitle: Troubleshoot
|
||||
tags: [Troubleshooting]
|
||||
---
|
||||
|
||||
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 from the **Choose profile** page, and then select **SSO and SCIM**.
|
||||
|
||||
> [!NOTE]
|
||||
>
|
||||
> When an organization is part of a company, you must select the company and
|
||||
> view the SSO connection for that organization at the company level.
|
||||
|
||||
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/manage-seats.md).
|
||||
* 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 [Configure single sign-on](../single-sign-on/configure.md).
|
||||
|
||||
### 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`.
|
||||
|
|
@ -0,0 +1,6 @@
|
|||
---
|
||||
build:
|
||||
render: never
|
||||
title: Troubleshoot
|
||||
weight: 40
|
||||
---
|
||||
|
|
@ -0,0 +1,232 @@
|
|||
---
|
||||
description: Learn how to troubleshoot common SSO issues.
|
||||
keywords: sso, troubleshoot, single sign-on
|
||||
title: Troubleshoot single sign-on
|
||||
linkTitle: Troubleshoot SSO
|
||||
tags: [Troubleshooting]
|
||||
aliases:
|
||||
- "/security/for-admins/single-sign-on/troubleshoot/"
|
||||
---
|
||||
|
||||
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 some common SSO errors and possible solutions.
|
||||
|
||||
## Check for errors
|
||||
|
||||
If you experience issues with SSO, check both the Docker Admin Console and your identity provider (IdP) for errors first.
|
||||
|
||||
#### Check Docker error logs
|
||||
|
||||
1. Sign in to the [Admin Console](https://app.docker.com/admin/) and select your organization.
|
||||
2. Select **SSO and SCIM**.
|
||||
3. In the SSO connections table, select the **Action** menu and then **View error logs**.
|
||||
4. For more details on specific errors, select **View error details** next to an error message.
|
||||
5. Note any errors you see on this page for further troubleshooting.
|
||||
|
||||
#### Check for errors in your IdP
|
||||
|
||||
1. Review your IdP’s logs or audit trails for any failed authentication or provisioning attempts.
|
||||
2. Confirm that your IdP’s SSO settings match the values provided in Docker.
|
||||
3. If applicable, confirm that you have configured user provisioning correctly and that it is enabled in your IdP.
|
||||
4. If applicable, verify that your IdP correctly maps Docker's required user attributes.
|
||||
5. Try provisioning a test user from your IdP and verify if they appear in Docker.
|
||||
|
||||
For further troubleshooting, check your IdP’s documentation. You can also contact their support team for guidance on error messages.
|
||||
|
||||
## Groups are not formatted correctly
|
||||
|
||||
#### Error message
|
||||
|
||||
When this issue occurs, the following error message is common:
|
||||
```text
|
||||
Some of the groups assigned to the user are not formatted as '<organization name>:<team name>'. Directory groups will be ignored and user will be provisioned into the default organization and team.
|
||||
```
|
||||
|
||||
#### Possible causes
|
||||
|
||||
- Incorrect group name formatting in your identity provider (IdP): Docker requires groups to follow the format `<organization>:<team>`. If the groups assigned to a user do not follow this format, they will be ignored.
|
||||
- Non-matching groups between IdP and Docker organization: If a group in your IdP does not have a corresponding team in Docker, it will not be recognized, and the user will be placed in the default organization and team.
|
||||
|
||||
#### Affected environments
|
||||
|
||||
- Docker single sign-on setup using IdPs such as Okta or Azure AD
|
||||
- Organizations using group-based role assignments in Docker
|
||||
|
||||
#### Steps to replicate
|
||||
|
||||
To replicate this issue:
|
||||
1. Attempt to sign in to Docker using SSO.
|
||||
2. The user is assigned groups in the IdP but does not get placed in the expected Docker Team.
|
||||
3. Review Docker logs or IdP logs to find the error message.
|
||||
|
||||
#### Solutions
|
||||
|
||||
Update group names in your IdP:
|
||||
1. Go to your IdP's group management section.
|
||||
2. Check the groups assigned to the affected user.
|
||||
3. Ensure each group follows the required format: `<organization>:<team>`
|
||||
4. Update any incorrectly formatted groups to match this pattern.
|
||||
5. Save changes and retry signing in with SSO.
|
||||
|
||||
## User is not assigned to the organization
|
||||
|
||||
#### Error message
|
||||
|
||||
When this issue occurs, the following error message is common:
|
||||
```text
|
||||
User '$username' is not assigned to this SSO organization. Contact your administrator. TraceID: XXXXXXXXXXXXX
|
||||
```
|
||||
|
||||
#### Possible causes
|
||||
|
||||
- User is not assigned to the organization: If Just-in-Time (JIT) provisioning is disabled, the user may not be assigned to your organization.
|
||||
- User is not invited to the organization: If JIT is disabled and you do not want to enable it, the user must be manually invited.
|
||||
- SCIM provisioning is misconfigured: If you use SCIM for user provisioning, it may not be correctly syncing users from your IdP.
|
||||
|
||||
#### Solutions
|
||||
|
||||
**Enable JIT provisioning**
|
||||
|
||||
JIT is enabled by default when you enable SSO. If you have JIT disabled and need
|
||||
to re-enable it:
|
||||
|
||||
1. Sign in to the [Admin Console](https://app.docker.com/admin) and select your organization.
|
||||
2. Select **SSO and SCIM**.
|
||||
3. In the SSO connections table, select the **Action** menu and then **Enable JIT provisioning**.
|
||||
4. Select **Enable** to confirm.
|
||||
|
||||
**Manually invite users**
|
||||
|
||||
When JIT is disabled, users are not automatically added to your organization when they authenticate through SSO.
|
||||
To manually invite users, see [Invite members](/manuals/admin/organization/members.md#invite-members)
|
||||
|
||||
**Configure SCIM provisioning**
|
||||
|
||||
If you have SCIM enabled, troubleshoot your SCIM connection using the following steps:
|
||||
|
||||
1. Sign in to the [Admin Console](https://app.docker.com/admin) and select your organization.
|
||||
2. Select **SSO and SCIM**.
|
||||
3. In the SSO connections table, select the **Action** menu and then **View error logs**. For more details on specific errors, select **View error details** next to an error message. Note any errors you see on this page.
|
||||
4. Navigate back to the **SSO and SCIM** page of the Admin Console and verify your SCIM configuration:
|
||||
- Ensure that the SCIM Base URL and API Token in your IdP match those provided in the Docker Admin Console.
|
||||
- Verify that SCIM is enabled in both Docker and your IdP.
|
||||
5. Ensure that the attributes being synced from your IdP match Docker's [supported attributes](/manuals/security/for-admins/provisioning/scim.md#supported-attributes) for SCIM.
|
||||
6. 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'.
|
||||
```
|
||||
|
||||
#### Possible 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
|
||||
|
||||
When this issue occurs, the following error message is common:
|
||||
```text
|
||||
Not enough seats in organization '$orgName'. Add more seats or contact your administrator.
|
||||
```
|
||||
|
||||
#### Possible causes
|
||||
|
||||
This error occurs when the organization has no available seats for the user when provisioning via Just-in-Time (JIT) provisioning or SCIM.
|
||||
|
||||
#### Solutions
|
||||
|
||||
**Add more seats to the organization**
|
||||
|
||||
Purchase additional Docker Business subscription seats. For details, see [Manage subscription seats](/manuals/subscription/manage-seats.md).
|
||||
|
||||
**Remove users or pending invitations**
|
||||
|
||||
Review your organization members and pending invitations. Remove inactive users or pending invitations to free up seats. For more details, see [Manage organization members](/manuals/admin/organization/members.md).
|
||||
|
||||
## Domain is not verified for SSO connection
|
||||
|
||||
#### Error message
|
||||
|
||||
When this issue occurs, the following error message is common:
|
||||
```text
|
||||
Domain '$emailDomain' is not verified for your SSO connection. Contact your company administrator. TraceID: XXXXXXXXXXXXXX
|
||||
```
|
||||
|
||||
#### Possible causes
|
||||
|
||||
This error occurs if the IdP authenticated a user through SSO and the User Principal Name (UPN)
|
||||
returned to Docker doesn’t match any of the verified domains associated to the
|
||||
SSO connection configured in Docker.
|
||||
|
||||
#### Solutions
|
||||
|
||||
**Verify UPN attribute mapping**
|
||||
|
||||
Ensure that the IdP SSO connection is returning the correct UPN value in the assertion attributes.
|
||||
|
||||
**Add and verify all domains**
|
||||
|
||||
Add and verify all domains and subdomains used as UPN by your IdP and associate them with your Docker SSO connection. For details, see [Configure single sign-on](/manuals/security/for-admins/single-sign-on/configure.md).
|
||||
|
||||
## Unable to find session
|
||||
|
||||
#### Error message
|
||||
|
||||
When this issue occurs, the following error message is common:
|
||||
```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.
|
||||
```
|
||||
|
||||
#### Possible causes
|
||||
|
||||
The following causes may create this issue:
|
||||
- The user pressed the back or refresh button during authentication.
|
||||
- The authentication flow lost track of the initial request, preventing completion.
|
||||
|
||||
#### Solutions
|
||||
|
||||
**Do not disrupt the authentication flow**
|
||||
|
||||
Do not press the back or refresh button during sign-in.
|
||||
|
||||
**Restart authentication**
|
||||
|
||||
Close the browser tab and restart the authentication flow from the Docker application (Desktop, Hub, etc).
|
||||
|
||||
## Name ID is not an email address
|
||||
|
||||
#### Error message
|
||||
|
||||
When this issue occurs, the following error message is common:
|
||||
```text
|
||||
The name ID sent by the identity provider is not an email address. Contact your company administrator.
|
||||
```
|
||||
|
||||
#### Possible causes
|
||||
|
||||
The following causes may create this issue:
|
||||
- The IdP sends a Name ID (UPN) that does not comply with the email format required by Docker.
|
||||
- Docker SSO requires the Name ID to be the primary email address of the user.
|
||||
|
||||
#### Solutions
|
||||
|
||||
In your IdP, ensure the Name ID attribute format is correct:
|
||||
1. Verify that the Name ID attribute format in your IdP is set to `EmailAddress`.
|
||||
2. Adjust your IdP settings to return the correct Name ID format.
|
||||
Loading…
Reference in New Issue