User & group provisioning for Microsoft Entra ID

This feature is available for the Personal 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.

Contents

  1. Features
  2. Requirements
  3. 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

  1. In the User management page of the admin console, click Enable Provisioning.

  2. Copy the generated key to the clipboard.

    Generate SCIM API key
  3. 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.

  1. Log in to the Microsoft Azure portal.

  2. Click Microsoft Entra ID.

  3. Under Manage in the left-hand navigation, click Enterprise applications.

  4. Click New application.

  5. In the Browse Microsoft Entra Gallery page, search for Tailscale and then click Tailscale.

  6. 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.

  7. In the application Overview page, under Manage in the left-hand navigation, click Provisioning.

  8. Click Get started.

  9. Set Provisioning Mode to Automatic.

  10. 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.

  11. For Secret Token, enter the SCIM API key that you generated in the Tailscale admin console.

    Provide credentials to Microsoft Entra ID
  12. Click Test Connection.

    A popup will display a message about whether the supplied credentials are authorized to enable provisioning.

  13. In the Settings section, ensure Send an email notification when an error occurs is checked, and provide an email to use for the notification.

  14. 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.

  15. Ensure that Provisioning Status is set to On.

    Provision Microsoft Entra ID
  16. Click Save.

  17. 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.

Assignment Required?

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.

  1. Log in to the Microsoft Azure portal.
  2. Click Microsoft Entra ID.
  3. Under Manage in the left-hand navigation, click Enterprise applications.
  4. Search for the Tailscale application and click it.
  5. Under Manage, click Properties.
  6. Click Delete and then click Yes.

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.
  • 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 suspended 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.