---
description: Learn how to troubleshoot common SSO issues.
keywords: sso, troubleshoot, single sign-on
title: Troubleshoot single sign-on
linkTitle: Troubleshoot SSO
tags: [Troubleshooting]
toc_max: 2
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