User & group provisioning for Okta

User & group provisioning for Okta is currently in beta.

This feature is only available for the Business plan or higher.

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.
  • 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 > General > SCIM Provisioning, click Enable Provisioning.

    Enable Provisioning for Okta
  2. Copy the generated key to the clipboard.

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

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

    Configure SCIM API Integration in Okta Admin UI
  3. Select Enable API integration. Paste the generated key into the API Token field.

    Enable SCIM API Integration with Tailscale SCIM API Key
  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.

    Select Email as the Application username format in Okta Admin UI
  2. Under Provisioning > Settings > To App, click to enable Create Users, Update User Attributes, and Deactivate Users, and then click Save.

    Enable User Sync features in Okta Admin UI
  3. Under Assignments, click Provision User to ensure that all users previously assigned to the application are provisioned in Tailscale.

    Provision Users 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 ACL 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.

Enable Group Sync in Okta Admin UI
  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.

Sync groups in Tailscale Access Controls UI

To use a pushed group in an ACL 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:*"],
  },
]

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.

Error message in UI for group not syncing

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 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.
  • Groups are parsed lowercased in the Tailscale ACL file, so any casing in Okta is ignored.
  • 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.

Last updated

WireGuard is a registered
trademark of Jason A. Donenfeld.

© 2022 Tailscale Inc.

Privacy & Terms