User & group provisioning for Microsoft Entra ID

This feature is available for the Personal, Personal Plus, and Enterprise plans.

Tailscale supports System for Cross-domain Identity Management (SCIM) to integrate with Microsoft Entra ID (previously known as Azure AD).

With group sync, you can refer to a group from Microsoft Entra ID in your tailnet policy file, with a human-readable name.
- You can also refer to a group from Microsoft Entra ID in your tailnet policy file using the externalGroupId.
With user sync, you can onboard and offboard users easily to Tailscale. For related information, see Offboarding when using user & group provisioning.
- When a user is deleted in Microsoft Entra ID, they are first 'soft' deleted, which suspends the user in Tailscale. The user is then 'hard' deleted approximately 30 days later in Microsoft Entra ID, which causes them to be deleted in Tailscale.
- When a user is disabled in Microsoft Entra ID, they are suspended in Tailscale.

This article shows you how to set up Microsoft Entra ID as a SCIM-integrated identity provider for Tailscale. You can also view the Microsoft tutorial Configure Tailscale for automatic user provisioning.

Features
Requirements
Step-by-Step Configuration Instructions

Features

The following provisioning features are supported:

Create users in Tailscale from Microsoft Entra ID
Update user attributes in Tailscale from Microsoft Entra ID
Delete users in Microsoft Entra ID to first suspend them in Tailscale; after approximately 30 days they are automatically deleted in Tailscale
Disable users in Microsoft Entra ID to suspend them in Tailscale
Group push from Microsoft Entra ID to Tailscale

Requirements

You need a Microsoft Entra ID subscription.
You need a tailnet.
Your tailnet's identity provider needs to be Microsoft Entra ID. If your tailnet is not using Microsoft Entra ID and you want to use it, contact support to migrate from your current identity provider to Microsoft Entra ID.

Step-by-Step Configuration Instructions

Enable Provisioning

In Tailscale

You need to be an Owner, Admin, or IT admin in Tailscale to complete these steps.

Generate a SCIM API key

In the User management page of the admin console, under SCIM Provisioning, select Enable Provisioning.
Copy the generated key to the clipboard.
Save the key information in a secure spot. You will need to use it when you configure Microsoft Entra ID. Note that Tailscale-generated SCIM API keys are case-sensitive.

In Microsoft Entra ID

You need to have an admin role for the Microsoft Azure portal to complete these steps.

Log in to the Microsoft Azure portal.
Select Microsoft Entra ID.
Under Manage in the left-hand navigation, select Enterprise applications.
Select New application.
In the Browse Microsoft Entra Gallery page, search for Tailscale and then select Tailscale.
Select Sign up for Tailscale.

You will be redirected to sign up for Tailscale. If you already have a Tailscale account, proceed to the next step. Otherwise, follow the prompts to sign up for Tailscale.
In the application Overview page, under Manage in the left-hand navigation, select Provisioning.
Select Get started.
Set Provisioning Mode to Automatic.
Under Admin Credentials, for Tenant URL, enter https://controlplane.tailscale.com/scim/v2/?aadOptscim062020.

Note that the trailing parameter, ?aadOptscim062020, is required. For information about this parameter, see the Microsoft Entra ID topic Flags to alter the SCIM behavior.
For Secret Token, enter the SCIM API key that you generated in the Tailscale admin console.
Select Test Connection.

A popup will display a message about whether the supplied credentials are authorized to enable provisioning.
In the Settings section, ensure Send an email notification when an error occurs is checked, and provide an email to use for the notification.
In the Settings section, under Scope, choose to sync all users and groups, or only users and groups that are assigned the application. If you choose to only sync users and groups that are assigned the application, you will need to assign these under the Users and groups section in the left-hand navigation.
Ensure that Provisioning Status is set to On.
Select Save.
Return to the application's Provisioning page. In the top menu, select Start Provisioning.

If you encounter issues after provisioning, open the application's Overview page and then select Restart Provisioning.

Restricting access to the Tailscale application

By default all users in the Entra directory service will be allowed to access the Tailscale app. To control which users are allowed to access Tailscale, go to Enterprise Applications > Tailscale > Properties and set Assignment Required? to Yes.

When this setting is enabled, only users who are assigned to the Tailscale application will be able to access it.

Supported attribute mappings

Tailscale supports SCIM attributes from the core "User" and "Group" SCIM resources. Tailscale only uses the following attributes for Tailscale's functionality; other attributes are stored without being used:

Attribute	SCIM attribute type	Use in Tailscale
externalId	Common	Required
userName	Core user	Required
emails	Core user	Optional
name.givenName	Core user	Optional
name.familyName	Core user	Optional
name.formatted	Core user	Optional
displayName	Core user	Optional
active	Core user	Optional
preferredLanguage	Core user	Optional

userName must map to the email used by the user to sign in to the tailnet.

photos are not an attribute that can be synced, but are populated for users on login.

Tailscale does not support the SCIM Enterprise User Schema Extension. If any additional user attribute from these extensions is specified, the request will fail.

Referring to Microsoft Entra ID groups in your tailnet policy file

You can refer to a group from Microsoft Entra ID in your tailnet policy file using either the human-readable name or the Microsoft Entra ID group ID. For example:

{
  "acls": [
    {
      "action": "accept",
      "src": ["group:groupname@example.com"],
      "dst": ["*:*"]
    },
    {
      "action": "accept",
      "src": ["group:all employees@example.com"],
      "dst": ["autogroup:self:*"]
    },
    {
      "action": "accept",
      "src": ["group:3ac067a2-f424-87b0-14a3-926482d83980@example.com"],
      "dst": ["tag:logging:*"]
    }
  ]
}

Updating Microsoft Entra ID Group Names

If you are using the group name (not the group ID) in your tailnet policy file, and you change the name of your group in Microsoft Entra ID, the Tailscale access rules for that group will no longer apply. Tailscale will fail closed, and you will see an error message in the admin console.

If you modified the name of the group, update the group in the ACL rule to the new group name. You can also revert the name change in Microsoft Entra ID if this was unintentional.

If you are using the group ID in your tailnet policy file, renaming the group will not affect the Tailscale access rules for that group.

Disable Provisioning

You need to have an admin role for the Microsoft Azure portal to complete these steps.

In Microsoft Entra ID

Log in to the Microsoft Azure portal.
Select Microsoft Entra ID.
Under Manage in the left-hand navigation, select Enterprise applications.
Search for the Tailscale application and select it.
Under Manage, select Properties.
Select Delete and then select Yes.

In Tailscale

In the User management page of the admin console, under SCIM Provisioning, select Disable provisioning, and then select Disable provisioning to confirm.
In the Access controls page in the admin console, update your rules to no longer reference any group which is no longer pushed.
If you no longer want to keep the SCIM API key that you used for Microsoft Entra ID, revoke the key.

Known Limitations

Microsoft Entra ID syncs with Tailscale every 40 minutes. This is a limitation from Microsoft Entra ID and you cannot change this interval. To force the sync of a user, for example, as part of offboarding, use Microsoft Entra ID on-demand provisioning. This should sync the user in less than 30 seconds.
Microsoft Entra ID takes approximately 30 days from 'soft' deletion to 'hard' deletion of a user. You cannot change this interval.
Microsoft Entra ID doesn't automatically restore the dynamic membership group entries when a user goes from 'soft' deleted to active. If this causes issues, you can Restart provisioning from Entra ID's app provisioning page to force a refresh.
Tailscale does not support the SCIM Enterprise User Schema Extension. If any additional user attribute from these extensions is specified, the request will fail.
Tailscale groups are parsed lowercased in the tailnet policy file, so any casing in Microsoft Entra ID is ignored.
Groups from Microsoft Entra ID cannot contain the @ symbol.
If you are referring to the group name in your tailnet policy file, and the name of your group changes, the ACLs for that group will no longer apply and Tailscale will fail closed. If instead, you use the group ID in your tailnet policy file, renaming the group will not affect the Tailscale access rules for that group.
A user disabled in Microsoft Entra ID will remain logged into Tailscale, and maintain access to all of their nodes and permissions granted by ACLs. They will only lose access as their device keys expire and they are blocked from re-authenticating new sessions with Microsoft Entra ID. Instead, disable the user in Microsoft Entra ID to suspend them in Tailscale.
Groups unlinked in Microsoft Entra ID that are retained in Tailscale are not synced to Tailscale.
You cannot use group sync to assign Tailscale admins or other user roles.
Parent groups of nested groups do not aggregate members of their nested groups. In other words, you cannot use a parent of a nested group in your ACLs and expect it to contain all members of the nested groups.