User & group provisioning for Okta

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

Contents

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

1. In Settings > User management > SCIM Provisioning, click Enable Provisioning.

   

2. Copy the generated key to the clipboard.

   

In Okta

Copy the key into the Tailscale app

1. (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.

   

2. On the Provisioning tab, select Integration, then click Configure API Integration.

   

3. Select Enable API integration. Paste the generated key into the API Token field. Note that Tailscale-generated SCIM API keys are case-sensitive.

   

4. If there is an Import Groups checkbox, uncheck it.

5. Click Test API Credentials to verify the SCIM connection, and then click Save.

Enable User Sync

1. In Okta, under Sign On > Credential Details, select Email as the Application username format.

   

2. Under Provisioning > Settings > To App, click to enable Create Users, Update User Attributes, and Deactivate Users, and then click Save.

   

3. Under Assignments, click 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

1. Under Applications, click the Tailscale app.

2. Under Push Groups, expand the Push Groups button, and select the group to push to Tailscale.

1. Click Save, or click 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 click 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.

Updating Okta Group Names

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.

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

1. Under Applications, click the Tailscale app.

2. Under Push Groups, expand the Push Groups button, unselect the groups you no longer want to push to Tailscale, and click Save.

In Tailscale

In the Access controls page in the admin console, update your rules to no longer reference any group which is no longer pushed.

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.