User & group provisioning for Microsoft Entra ID

This feature is available for the Personal and Enterprise plans.

User & group provisioning for Microsoft Entra ID is currently in beta.

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, click 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.
Click Microsoft Entra ID.
Under Manage in the left-hand navigation, click Enterprise applications.
Click New application.
In the Browse Microsoft Entra Gallery page, search for Tailscale and then click Tailscale.
Click 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, click Provisioning.
Click 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.
Click 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.
Click Save.
Return to the application's Provisioning page. In the top menu, click Start Provisioning.

If you encounter issues after provisioning, open the application's Overview page and then click 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