Skip to content

Refresh provisioning overview page #26172

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

Open
akristen wants to merge 7 commits into
base: main
Choose a base branch
from
+695 −470
Open

Refresh provisioning overview page #26172

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
5ec464b
docs: refresh provisioning overview page
akristen Sep 23, 2026
6d6942e
docs: clarify how JIT interacts with SCIM and auto-provisioning
akristen Sep 23, 2026
9c03ea0
docs: document how JIT and SCIM interact
akristen Sep 23, 2026
1a1f2d7
docs: clarify SCIM provisioning and its relationship to JIT
akristen Sep 25, 2026
854f1c5
docs: correct how SCIM manages existing users
akristen Sep 30, 2026
a4038c8
Merge upstream/main into scim-jit-clarification
akristen Sep 30, 2026
5c6ca7a
docs: tier 1 freshness pass on provisioning
akristen Sep 30, 2026
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
71 changes: 57 additions & 14 deletions content/manuals/faqs/security.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -90,25 +90,51 @@ If SSO is turned on but not enforced, users can fall back to username/password a

Yes, bot accounts need seats like regular users, requiring a non-aliased domain email in the IdP and using a seat in Docker Hub. You can add bot accounts to your IdP and create access tokens to replace other credentials.

### How can I troubleshoot an Entra ID SSO connection error?

Confirm that you've configured the necessary API permissions in Entra ID for your SSO connection. You need to grant administrator consent within your Entra ID tenant. See [Entra ID (formerly Azure AD) documentation](https://learn.microsoft.com/en-us/azure/active-directory/manage-apps/grant-admin-consent?pivots=portal#grant-admin-consent-in-app-registrations).

## Provisioning

### Does SAML SSO use Just-in-Time provisioning?

The SSO implementation uses Just-in-Time (JIT) provisioning by default. You can optionally turn off JIT in Docker Home if you turn on auto-provisioning using SCIM. See [Just-in-Time provisioning](/manuals/security/provisioning/just-in-time.md).
Yes. Docker turns on Just-in-Time (JIT) provisioning when you configure an SSO
connection. You can turn off JIT after you configure and test SCIM. See
[Just-in-Time provisioning](/manuals/security/provisioning/just-in-time.md).

### How can I troubleshoot an Entra ID SSO connection error?
### Can I use JIT and SCIM together?

Confirm that you've configured the necessary API permissions in Entra ID for your SSO connection. You need to grant administrator consent within your Entra ID tenant. See [Entra ID (formerly Azure AD) documentation](https://learn.microsoft.com/en-us/azure/active-directory/manage-apps/grant-admin-consent?pivots=portal#grant-admin-consent-in-app-registrations).
Yes, but Docker recommends using one provisioning source. When both are
enabled, sign-in and SCIM sync can each change a user's full name and team
memberships, so those values can move back and forth. Before you enable both,
review
[how SCIM works with JIT](/manuals/security/provisioning/scim/_index.md#choose-how-scim-works-with-jit).

### How can I give a user immediate access with SCIM?

If your IdP supports Provision on Demand, use it to synchronize the user
before the next scheduled SCIM synchronization. This provides immediate
provisioning without enabling JIT.

### Do I need to manually add users to my organization?

No, you don't need to manually add users to your organization. Just ensure user accounts exist in your IdP. When users sign in to Docker with their domain email address, they're automatically added to the organization after successful authentication.
Not when JIT, SCIM, or auto-provisioning covers the user. If none of those
methods applies, for example when JIT is turned off and the user isn't
assigned to the Docker application in your IdP, an organization owner must
invite the user.

### Can users use different email addresses to authenticate through SSO?

All users must authenticate using the email domain specified during SSO setup. Users with email addresses that don't match the verified domain can sign in as guests with username and password if SSO isn't enforced, but only if they've been invited.
All users must authenticate using the email domain specified during SSO setup.
Users with email addresses that don't match the verified domain can sign in as
guests with username and password if SSO isn't enforced, but only if they've
been invited.

### How will users know they're being added to a Docker organization?

When SSO is turned on, users are prompted to authenticate through SSO the next time they sign in to Docker Hub or Docker Desktop. The system detects their domain email and prompts them to sign in with SSO credentials instead.
When SSO is turned on, users are prompted to authenticate through SSO the next
time they sign in to Docker Hub or Docker Desktop. The system detects their
domain email and prompts them to sign in with SSO credentials instead.

For CLI access, users must authenticate using personal access tokens.

Expand All @@ -125,29 +151,46 @@ For detailed instructions, see [Configure single sign-on](/manuals/security/auth

### Is Docker SSO fully synced with the IdP?

Docker SSO provides Just-in-Time (JIT) provisioning by default. Users are provisioned when they authenticate with SSO. If users leave the organization, administrators must manually [remove the user](/manuals/accounts/organization/manage/members.md#remove-a-member-from-the-organization) from the organization.

[SCIM](/manuals/security/provisioning/scim/_index.md) provides full synchronization with users and groups. When using SCIM, the recommended configuration is to turn off JIT so all auto-provisioning is handled by SCIM.
Not with JIT alone. JIT provisions users when they authenticate, but it
doesn't deprovision users who leave your IdP. You must
[remove those users](/manuals/accounts/organization/manage/members.md#remove-a-member-from-the-organization)
manually.

Additionally, you can use the [Docker Hub API](/reference/api/hub/latest.md) to complete this process.
[SCIM](/manuals/security/provisioning/scim/_index.md) provides continuous user
and group synchronization, including automatic deprovisioning.

### How does turning off Just-in-Time provisioning affect user sign-in?

When JIT is turned off (available with SCIM in Docker Home), users must be organization members or have pending invitations to access Docker. Users who don't meet these criteria get an "Access denied" error and need administrator invitations.
You can turn off JIT only while SCIM is enabled. With JIT turned off, users
must already be members, have a pending invitation, or be provisioned through
SCIM. Users who don't meet these criteria get an "Access denied" error and
need an administrator to invite them.

See [SSO authentication with JIT provisioning disabled](/manuals/security/provisioning/just-in-time.md#sso-authentication-with-jit-provisioning-disabled).

### Can someone join an organization without an invitation?

Not without SSO. Joining requires an invite from an organization owner. When SSO is enforced, users with verified domain emails can automatically join the organization when they sign in.
Yes. JIT can add users when they sign in through SSO, SCIM can provision users
assigned in the IdP, and auto-provisioning can add existing Docker users whose
email addresses match a verified domain. Without an automatic provisioning
method, an organization owner must invite the user.

### What happens to existing licensed users when SCIM is turned on?

Turning on SCIM doesn't immediately remove or modify existing licensed users. They retain current access and roles, but you'll manage them through your IdP after SCIM is active. If SCIM is later turned off, previously SCIM-managed users remain in Docker but are no longer automatically updated based on your IdP.
SCIM can manage and deprovision organization members whose email domain is
verified on the SSO connection, including users created through JIT or added
manually. When your IdP pushes a user with a matching email address, SCIM
links the existing Docker account. Members whose email domain isn't verified
on the connection stay outside SCIM. To use SCIM as the only provisioning
source, see
[Migrate JIT to SCIM](/manuals/security/provisioning/scim/migrate-scim.md).

### Is user information visible in Docker Hub?

All Docker accounts have public profiles associated with their namespace. If you don't want user information (like full names) to be visible, remove those attributes from your SSO and SCIM mappings, or use different identifiers to replace users' full names.
All Docker accounts have public profiles associated with their namespace. If
you don't want user information (like full names) to be visible, remove those
attributes from your SSO and SCIM mappings, or use different identifiers to
replace users' full names.

## Enforcement

Expand Down
3 changes: 2 additions & 1 deletion content/manuals/security/authentication/single-sign-on/manage.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -116,7 +116,8 @@ Docker supports the following provisioning methods:
- SCIM provisioning: Sync users and groups from your identity provider to Docker
- Group mapping: Sync user groups from your identity provider with teams in your
Docker organization
- Manual provisioning: Turn off automatic provisioning and manually invite users
- Manual invitations: Invite users directly. You can turn off JIT only after you
enable SCIM.

For more information on provisioning methods, see
[Provision users](/manuals/security/provisioning/_index.md).
Expand Down
113 changes: 68 additions & 45 deletions content/manuals/security/provisioning/_index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,86 +1,109 @@
---
description: Learn about provisioning users for your SSO configuration.
keywords: provision users, provisioning, JIT, SCIM, group mapping, sso, docker admin, admin, security
title: Provision users
description: >-
Provision Docker organization users with SCIM, JIT, group mapping, or
auto-provisioning, and map SSO and SAML attributes from your identity
provider.
keywords: provision users, user provisioning, JIT, SCIM, group mapping,
auto-provisioning, SSO, SAML, identity provider, dockerOrg, dockerRole,
dockerTeam, dockerSessionMinutes, Docker Home, admin, security
title: User provisioning overview
linkTitle: Provision
weight: 30
aliases:
- /security/for-admins/provisioning/
- /enterprise/security/provisioning/
- /security/for-admins/provisioning/
- /enterprise/security/provisioning/
grid:
- title: "Add and manage domains"
description: "Add, verify, and manage domains to control user access and enable auto-provisioning."
- title: Add and manage domains
description: Add, verify, and manage domains for auto-provisioning.
icon: globe-alt
link: "domain-management/"
- title: "SCIM provisioning"
description: "Enable continuous user data synchronization between your IdP and Docker. Best for larger organizations."
- title: SCIM provisioning
description: Sync user data between your IdP and Docker with SCIM.
icon: arrow-path
link: "scim/"
- title: "Just-in-Time (JIT) provisioning"
description: "Set up automatic user creation on first sign-in. Ideal for smaller teams with minimal setup requirements."
- title: Just-in-Time (JIT) provisioning
description: Create user accounts automatically on first SSO sign-in.
icon: clock
link: "just-in-time/"
- title: "Auto-provisioning"
description: "Associate members to an organization when email addresses match a verified domain."
- title: Auto-provisioning
description: Add users whose email addresses match a verified domain.
icon: user-group
link: "auto-provisioning/"
---

{{< summary-bar feature_name="SSO" >}}

After configuring your SSO connection, the next step is to provision users. This process ensures that users can access your organization through automated user management.
After you configure single sign-on (SSO), provision users so they can
access your organization through automated account management.

This page provides an overview of user provisioning and the supported provisioning methods.
## Provisioning methods

## What is provisioning?
Provisioning automates account creation, updates, and deactivation using
data from your identity provider (IdP). Docker supports the following
methods:

Provisioning helps manage users by automating tasks like account creation, updates, and deactivation based on data from your identity provider (IdP). There are several methods for user provisioning, each offering benefits for different organizational needs:
| Provisioning method | When it runs | Lifecycle management | Default setting |
| :--- | :--- | :--- | :--- |
| [System for Cross-domain Identity Management (SCIM)](/manuals/security/provisioning/scim/_index.md) | On the IdP's synchronization schedule or through Provision on Demand | Creates and updates users, synchronizes configured groups, and deprovisions users | Disabled |
| [Just-in-Time (JIT)](/manuals/security/provisioning/just-in-time.md) | When a user signs in through SSO | Creates users and applies attributes from the SSO assertion. It doesn't deprovision users | Enabled when you configure SSO |
| [Auto-provisioning](/manuals/security/provisioning/auto-provisioning.md) | When an existing Docker user signs in or verifies their email, and that address uses a verified domain | Adds the user to the organization. It doesn't create or deprovision accounts | Disabled |

| Provisioning method | Description | Default setting in Docker | Recommended for |
| :--- | :--- | :------------- | :--- |
| System for Cross-domain Identity Management (SCIM) | Continuously syncs user data between your IdP and Docker, ensuring user attributes remain updated without manual intervention | Disabled by default | Larger organizations or environments with frequent changes in user information or roles |
| Group mapping | Maps user groups from your IdP to specific roles and permissions within Docker, enabling fine-grained access control based on group membership | Disabled by default | Organizations requiring strict access control and role-based user management |
| Just-in-Time (JIT) | Automatically creates and provisions user accounts when they first sign in via SSO | Enabled by default | Organizations needing minimal setup, smaller teams, or low-security environments |
| Auto-provision | Adds users when email addresses match a verified domain | Disabled by default | Orgs without SSO that need to add existing Docker users by domain |
[Group mapping](/manuals/security/provisioning/scim/group-mapping.md) assigns
users to Docker organizations and teams. Use it with SAML SSO or SCIM. You can
also invite users manually when automatic provisioning isn't configured.

## Default provisioning setup

By default, Docker enables JIT provisioning when you configure an SSO connection. With JIT enabled, user accounts are automatically created the first time a user signs in using your SSO flow.
Docker turns on JIT provisioning when you configure an SSO connection. If you
also enable SCIM, Docker recommends choosing one provisioning source to manage
users and attributes. Before configuring SCIM, review
[how SCIM works with JIT](/manuals/security/provisioning/scim/_index.md#choose-how-scim-works-with-jit).

JIT provisioning may not provide sufficient control or security for some organizations. In such cases, SCIM or group mapping can be configured to give administrators more control over user access and attributes.
For a domain that belongs to an SSO connection, JIT adds the user instead of
auto-provisioning.

## SSO attributes

When a user signs in through SSO, Docker obtains several attributes from your IdP to manage the user's identity and permissions. These attributes include:
Each time a user signs in through SSO, Docker reads attributes from your
IdP to set the user's identity and permissions:

- Email address: The unique identifier for the user
- Full name: The user's complete name
- Groups: Optional. Used for group-based access control
- Docker Org: Optional. Specifies the organization the user belongs to
- Docker Team: Optional. Defines the team the user belongs to within the organization
- Docker Role: Optional. Determines the user's permissions within Docker
- Docker session minutes: Optional. Sets the session duration before users must re-authenticate with their IdP. Must be a positive integer greater than 0. If not provided, default session timeouts apply
| Attribute | Required | Description |
| :--- | :--- | :--- |
| Email address | Yes | Unique identifier for the user |
| Full name | Yes | User's complete name |
| Groups | No | Group-based access control |
| Docker Org | No | Organization the user belongs to |
| Docker Team | No | Team within the organization |
| Docker Role | No | Permissions in Docker |
| Docker session minutes | No | Session duration, in minutes, before users must re-authenticate with their IdP. Must be a positive integer greater than 0. If omitted, default session timeouts apply |

> [!NOTE]
>
> Default session timeouts apply when Docker session minutes is not specified. Docker Desktop sessions expire after 90 days or 30 days of inactivity. Docker Hub and Docker Home sessions expire after 24 hours.
> Default session timeouts apply when Docker session minutes is not
> specified. Docker Desktop sessions expire after 90 days or 30 days of
> inactivity. Docker Hub and Docker Home sessions expire after 24 hours.

## SAML attribute mapping

If your organization uses SAML for SSO, Docker retrieves these attributes from the SAML assertion message. Different IdPs may use different names for these attributes.
If your organization uses SAML for SSO, Docker reads these attributes
from the SAML assertion. Identity providers may use different names for
the same attributes.

| SSO Attribute | SAML Assertion Message Attributes |
| SSO attribute | SAML assertion attributes |
| :--- | :--- |
| Email address | `"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier"`, `"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn"`, `"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress"`, `email` |
| Full name | `"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name"`, `name`, `"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname"`, `"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname"` |
| Groups (optional) | `"http://schemas.xmlsoap.org/claims/Group"`, `"http://schemas.microsoft.com/ws/2008/06/identity/claims/groups"`, `Groups`, `groups` |
| Docker Org (optional) | `dockerOrg` |
| Docker Team (optional) | `dockerTeam` |
| Docker Role (optional) | `dockerRole` |
| Docker session minutes (optional) | `dockerSessionMinutes`, must be a positive integer > 0 |
| Email address | `"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier"`, `"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn"`, `"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress"`, `email` |
| Full name | `"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name"`, `name`, `"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname"`, `"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname"` |
| Groups (optional) | `"http://schemas.xmlsoap.org/claims/Group"`, `"http://schemas.microsoft.com/ws/2008/06/identity/claims/groups"`, `Groups`, `groups` |
| Docker Org (optional) | `dockerOrg` |
| Docker Team (optional) | `dockerTeam` |
| Docker Role (optional) | `dockerRole` |
| Docker session minutes (optional) | `dockerSessionMinutes`, must be a positive integer greater than 0 |

## Next steps

Choose the provisioning method that best fits your organization's needs:
Choose the provisioning method that fits your organization:

{{< grid >}}
{{< grid >}}

If users get the wrong role or team after you change methods, see
[Troubleshoot provisioning](/manuals/security/provisioning/troubleshoot-provisioning.md).
Loading