Directory Sync
This feature is in public BETA and may not be available on all plans.
# Overview
Directory Sync allows organization Owners to easily manage their Netlify organization’s users across multiple teams. The System for Cross-domain Identity Management (SCIM) is an open standard used to implement Directory Sync. As an organization Owner, you can assign Netlify team access and user roles to groups set up in your identity provider.
Once you activate Directory Sync, users are automatically provisioned to Netlify teams and user roles based on your directory group mapping. Existing members of your Netlify teams that are not provisioned will not be affected, and will retain their roles and team assignments.
Once a user is provisioned by Directory Sync, organization Owners can change the role for all users within a directory group. Team owners will not be able to change a provisioned user’s team member role. Reviewers and Git Contributors can’t be provisioned through Directory Sync.
Organization owners and Team owners can choose which sites provisioned and non-provisioned users can access through the Members page.
# Directory Sync prerequisites
Before you can get started configuring Directory Sync, you need to have Organization single sign-on (SSO) set up for your organization.
# Configure Directory Sync
After you set up Organization SSO, you can start configuring Directory Sync.
# Set up a directory in your identity provider
To get started, you need to set up a directory in your identity provider. A directory stores information about your users and the directory groups they belong to. These groups are created in your identity provider.
In the Netlify UI, select your organization name at the top of the page, then select Organization overview.
Go to Settings > Directory Sync.
Select Configure Directory Sync. If the button is disabled, you need to first set up SSO for your Organization.
Select your preferred identity provider.
As part of the guided setup, you are prompted to create a Netlify app. You can use the existing Netlify app you created as part of Organization SSO.
Follow the guided flow to set up your directory. Follow the prompts to assign the users and groups defined in your identity provider to your Netlify app.
Once you set up your users and groups in your identity provider and assign them to your Netlify app, you are ready to assign your directory groups to Netlify roles and teams in the Netlify UI.
After you set up your directory groups successfully in your identity provider, Netlify will update your Identity Provider and Status in the Netlify UI, under Organization overview > Settings > Directory Sync.
Your Directory Sync Status will show as Inactive until you map your directory groups to Netlify roles and teams and activate Directory Sync.
# Map directory groups to Netlify roles and teams
To map your directory groups to Netlify roles and teams:
Go to Organization overview > Team management > Directory group mapping. If you successfully set up your directory groups in your identity provider, you’ll find your groups listed.
Select a group, then select Add mapping.
Unable to map your directory group?
You can’t map a team to the same directory group more than once. If you have mapped all available teams to a directory group and role, you will not be able to select Add mapping. You must either create a new team or remove the directory group mapping from an existing team to continue.
Assign the directory group a Netlify team and user role. The available roles include team Owner, Collaborator, and Billing Admin.
By default, Collaborators will have access to all sites within their team. If you want to limit a Collaborator’s access to only specific sites, organization and team Owners can do so on the Members page after they are provisioned.
If a user is in two directory groups with different user roles, Netlify will grant them the user role with the most access and permissions.
Select Save.
You are now ready to activate Directory Sync. Your directory group mappings will not take effect until Directory Sync is activated.
# Activate Directory Sync
Once you’re done mapping your directory groups, you need to activate Directory Sync.
When Directory Sync is active, users are automatically provisioned, which means they are assigned to Netlify teams and user roles based on your directory group mapping.
If you used Directory Sync to provision a user who was already a member of one of your teams, that user would now be managed by Directory Sync.
To activate Directory Sync:
In your Organization Overview, go to Settings > Directory Sync.
Select Edit status.
Change the status to Active and select Save.
# Manage provisioned team members
Once you activate Directory Sync, provisioned members will show on their team’s Members page as Managed by Org, which indicates they are managed by your organization’s Directory Sync settings.
Provisioned users can be managed in the following ways:
- Organization and team Owners can change a provisioned team member’s site access.
- Organization Owners can change a user role for a directory group.
- Organization Owners can change which team is assigned to a directory group by removing an existing directory group mapping.
# Change site access for a provisioned user
Organization and team Owners can change a provisioned team member’s site access from the Team members list.
Using the team menu at the top of the Netlify UI, select a team.
Go to the team’s Members page to access the list of team members.
Select Options > Edit member next to a team member to change the sites they are able to access.
Refer to our docs on managing site member access for more information.
When a user is provisioned by Directory Sync, you can only change their role by editing their directory group mapping.
# Change the user role for a directory group
Once Directory Sync is activated, organization Owners can only change a provisioned user’s role through their directory group.
In Team management > Directory group mapping, find the group you want to edit.
Next to the group, select Options > Edit mapping to select a new user role. This will change the role for everyone in the specified group.
After choosing a new role, select Save.
# Remove directory group mapping
Organization Owners can remove all users in a directory group from their assigned team and roles by going to Team management > Directory group mapping and selecting Options > Remove mapping.
# Deactivate Directory Sync
When Directory Sync is inactive, members will not be automatically provisioned to roles and teams. Any changes you make in your identity provider or in your Netlify directory group mapping will not take effect until the status is Active.
Organization Owners can deactivate Directory Sync in Organization overview > Settings > Directory Sync. Select Edit status and choose Inactive. Select Update to save your changes.
If the status is changed to Inactive, existing team members will keep their assigned teams and roles and will still be able to access the Netlify UI.
# Delete Directory Sync
Organization Owners can delete Directory Sync for their organization by going to Organization overview > Settings > Directory Sync. When deleting, there are two options:
Keep provisioned users (default): provisioned users will not be removed from Netlify, and will retain their assigned teams and roles. You can still manage them on their respective team’s Members page.
Remove provisioned users: provisioned users will be removed from their teams and will no longer be able to access Netlify. If you want to set up Directory Sync again, you will have to re-map the users to Netlify teams and roles.
Did you find this doc useful?
Your feedback helps us improve our docs.