User & group provisioning for Okta

This feature is available for the Enterprise plan.

Tailscale supports System for Cross-domain Identity Management (SCIM) to integrate with Okta.

Features
Requirements
Step-by-Step Configuration Instructions

Features

The following provisioning features are supported:

Create users in Tailscale from Okta
Update user attributes in Tailscale from Okta
Deactivate users in Okta to suspend them in Tailscale
Group push from Okta to Tailscale

Requirements

Install the Tailscale app from the Okta Integration Network and configure it to activate Okta for your domain.

If you're using Tailscale through a custom app integration you'll need to replace that configuration with the Tailscale app and configuration.
You must use Email as the Application username format, and each Okta user's primary email must be identical to their application username. Failure to do so will result in errors.

Step-by-Step Configuration Instructions

Enable Provisioning

In Tailscale

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.

In Okta

Copy the key into the Tailscale app

(Optional) On the Sign On tab, in Advanced Sign-on Settings select the Tailscale instance to connect to. For most users, leave the default option Tailscale selected. If you need to connect to the US high compliance server, select Tailscale (US high compliance) – must be allowlisted and fill out the Identity provider configuration or change section of the support form.
On the Provisioning tab, select Integration, then select Configure API Integration.
Select Enable API integration. Paste the generated key into the API Token field. Note that Tailscale-generated SCIM API keys are case-sensitive.
If there is an Import Groups checkbox, uncheck it.
Select Test API Credentials to verify the SCIM connection, and then select Save.

Enable User Sync

In Okta, under Sign On > Credential Details, select Email as the Application username format.
Under Provisioning > Settings > To App, select to enable Create Users, Update User Attributes, and Deactivate Users, and then select Save.
Under Assignments, select Provision User to ensure that all users previously assigned to the application are provisioned in Tailscale.

Enable Group Sync

With group sync, you can refer to a group from Okta in your ACL file, with a human-readable name. 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:engineering@example.com"],
      "dst": ["tag:logging:*"]
    }
  ]
}

Groups synced from Okta do not replace ACL groups in Tailscale. You can use Okta group sync and also define groups in the tailnet policy file.

In Okta

Under Applications, select the Tailscale app.
Under Push Groups, expand the Push Groups button, and select the group to push to Tailscale.
Select Save, or select Save & Add Another if you want to push another group.

In practice, changes to groups in Okta tend to be reflected to Tailscale in seconds, but that is not a guarantee.

In Tailscale

In the Access controls page in the admin console, under Group Sync you should see the groups that you pushed from Okta.

To use a pushed group in an access rule, either select Copy and paste it into a rule, or type it in:

"acls": [
  {
    "action": "accept",
    "src": ["group:engineering@example.com"],
    "dst": ["tag:logging:*"],
  },
]

Synced group names are treated as lowercase. They can include spaces, but not the @ symbol.

If you change the name of your group in Okta, the Tailscale ACLs for that group will no longer apply. The ACL is dependent on the name you configured in Okta, not on a group reference. Tailscale will fail closed, and you will see an error message in the admin console.

Error message in UI for group not syncing

If you modified the name of the group, update the group in the access rule to the new group name. You can also revert the name change in Okta if this was unintentional.

Disabling Group Sync

In Okta

Under Applications, select the Tailscale app.
Under Push Groups, expand the Push Groups button, unselect the groups you no longer want to push to Tailscale, and select Save.

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 Okta, revoke the key.

Known Limitations

If you configured Okta as your identity provider for Tailscale prior to November 2021, you will need to reconfigure your identity provider. In order to use user & group provisioning, use the new Tailscale app in Okta.
You must use Email as the Application username format for Tailscale in Okta.
Tailscale groups are parsed lowercased in the tailnet policy file, so any casing in Okta is ignored.
Groups from Okta cannot contain the @ symbol.
If the name of your group changes, the ACLs for that group will no longer apply and Tailscale will fail closed. See Updating Okta Group Names for recommended actions.
Users suspended in Okta are not synced to Tailscale. Only users deactivated or unassigned from the Tailscale app in Okta are suspended in Tailscale.
- A user suspended in Okta 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 Okta.
Groups unlinked in Okta that are retained in Tailscale, as well as those deactivated from group push are not synced to Tailscale.
You cannot use group sync to assign Tailscale admins or other user roles, only manage permissions in ACLs.