User and group provisioning

With provisioning, your identity provider manages who is in your Peerlify network. Assign someone to Peerlify in Microsoft Entra ID or Okta and they become a member; unassign or deactivate them and they lose access to the network within seconds. Groups from your identity provider become groups you can use in access rules.

Provisioning uses SCIM 2.0: your identity provider sends the changes to Peerlify. It is available on the Enterprise plan, for one identity provider per network: Microsoft Entra ID or Okta.

Before you start

• Your network must sign in through the same identity provider. Peerlify links a provisioned user to the person who signs in through that provider's own user ID (see How provisioned users are linked), so:
  • for Microsoft Entra ID, turn on provisioning in your Entra tenant's network, the one people join with Continue with Microsoft (see Sign in with Microsoft);
  • for Okta, turn it on in the network created when you set up single sign-on with Okta.
• Only the network's Owner or an Admin can open Settings → Provisioning and set it up.
• The network must be on Enterprise. On other plans the section reads User and group provisioning is part of Enterprise. Enterprise is arranged with sales; see Plans and limits.

Turn on provisioning

1. In the console, open Settings → Provisioning.
2. Pick Microsoft Entra ID or Okta.
3. Click Enable provisioning.
4. Under Copy these into your identity provider, copy the Tenant URL and the Secret token.

The Tenant URL looks like https://web.peerlify.com/scim/v2/n/<network ID>. The secret token starts with pscim_.

Then set up your identity provider: Microsoft Entra ID or Okta.

Once your identity provider starts sending changes, Settings → Provisioning shows:

• a status line, such as Receiving updates · last request 2 min ago, No requests in 24 hours, or Last request failed: followed by the reason;
• counts of Users, Waiting for first sign-in, Suspended by IdP, Can't be linked, Groups and Name conflicts;
• the token's first characters and the date it was issued;
• Recent events, the latest provisioning changes;
• Members not in your identity provider (see Existing members).

Rotate or revoke the token

• Rotate issues a new token, shown once like the first. The new token works at once, and the old one keeps working for 10 more minutes so a sync your identity provider has already started can finish. The console shows when the previous token stops working. Paste the new token into your identity provider within that time.
• Revoke stops the token immediately, with a confirmation: Revoke the token? Your identity provider stops syncing immediately. Nothing else changes. To sync again, click Issue token and paste the new token into your identity provider.

The token works only for your network's Tenant URL. It can't be used with the REST API, and an API token can't be used for provisioning.

Turn off provisioning

Turn off provisioning at the bottom of the section stops the token. Synced users and groups stay as they are: groups keep applying in your rules, and people suspended by your identity provider stay suspended. Members your identity provider managed can now be removed on the Members page. To turn provisioning back on for a network that has synced users, pick the same identity provider.

Set up Microsoft Entra ID

You need an Entra role that can manage enterprise applications, such as Application Administrator or Cloud Application Administrator.

1. In the Microsoft Entra admin center, go to Enterprise applications → New application → Create your own application. Name it, for example Peerlify provisioning, choose Integrate any other application you don't find in the gallery (Non-gallery), and create it.
2. In the new application, open Provisioning and set Provisioning Mode to Automatic.
3. Under Admin Credentials, paste the Tenant URL and the Secret Token from Peerlify. Click Test Connection, then Save.
4. Under Mappings, open Provision Microsoft Entra ID Users and change the mapping for externalId: set its source attribute to objectId. Save.
5. Under Mappings, keep Provision Microsoft Entra ID Groups enabled if you want groups in Peerlify.
6. Under Settings, set Scope to Sync only assigned users and groups.
7. In Users and groups, assign the people and groups who should be in the network.
8. Back in Provisioning, set Provisioning Status to On and save.

Entra syncs in cycles, usually every 40 minutes. To try one person straight away, use Provision on demand in the application's Provisioning page. Assigning groups to an application needs a Microsoft Entra ID P1 or P2 license; without one, assign people individually.

Set up Okta

You need an Okta administrator who can create app integrations.

1. In the Okta Admin Console, go to Applications → Applications → Create App Integration. Choose SWA or SAML 2.0, the app types Okta adds SCIM provisioning to, and name it, for example Peerlify provisioning. People keep signing in to Peerlify through your existing single sign-on app; this one only provisions.

2. On the app's General tab, under App Settings, set Provisioning to SCIM and save.

3. On the Provisioning tab, under Integration, click Edit and set:

   • SCIM connector base URL: the Tenant URL from Peerlify;
   • Unique identifier field for users: userName;
   • Supported provisioning actions: Push New Users, Push Profile Updates and Push Groups;
   • Authentication Mode: HTTP Header, with the Secret token from Peerlify as the bearer token.

   Click Test Connector Configuration, then Save.

4. Under Provisioning → To App, enable Create Users, Update User Attributes and Deactivate Users.

5. On the Assignments tab, assign the people and groups who should be in the network.

6. On the Push Groups tab, push the groups you want in Peerlify.

Peerlify needs externalId to be the person's Okta user ID, the same ID Okta gives Peerlify when that person signs in, and links on it. Check that your app's attribute mapping sends it, and don't map anything else to externalId. A user whose ID is missing shows Can't be linked; one whose externalId is something else never links to their sign-in.

How provisioned users are linked

When your identity provider adds someone who hasn't signed in to Peerlify yet, they appear on the Members page as Waiting for first sign-in. They hold no seat until they sign in.

The first time they sign in through the same identity provider, Peerlify links them by the provider's own user ID:

• Microsoft Entra ID: your tenant and the person's object ID;
• Okta: the person's Okta user ID, through your network's single sign-on.

Peerlify never links by email address. Someone else who signs in with the same email, through another provider or as another account in your tenant, isn't linked and doesn't get the provisioned person's access.

If the person was already a member, for example from an invite or from signing in before provisioning was set up, the existing membership is linked and keeps its role. A person who already signed in is linked as soon as your identity provider sends them.

The Members page shows each provisioned member's state:

Roles aren't taken from your identity provider. Provisioned people join as Member; change roles on the Members page (see Members and roles).

Only provisioned users can join

Settings → Provisioning → Only provisioned users can join controls whether people who sign in through your identity provider need to be assigned to Peerlify there first. With it on, a person from your Entra tenant or your Okta single sign-on who hasn't been provisioned doesn't join the network when they sign in. When they sign in from the Peerlify console or app, the sign-in page asks them to contact their IT admin; if they sign in on the sign-in page directly, they land in the console without this network. Their own network and any other networks they belong to aren't affected.

It is on by default when the network signs in through the identity provider you picked, which is the setup this page describes. Invites still work with it on: an invite is an explicit decision by an admin, so an invited person joins even if they aren't provisioned, including people at other domains.

Deactivation and deletion

Suspension by your identity provider applies to this network only. The person can still sign in to Peerlify and keeps their own network and any other network they belong to.

When your identity provider deactivates someone:

• the console refuses them for this network within about 30 seconds;
• their devices disappear from every other device's peer list, and lose all their peers, within about 10 seconds;
• every device session they have in this network is ended, and auth keys and new device sign-ins into this network are refused;
• they no longer match any email:, role: or synced group: selector.

When your identity provider reactivates them, their role and approval are as before, and their devices have to sign in again, for example with peerlify login.

What your identity provider sends differs:

When your identity provider deletes someone, they are suspended at once and removed 30 days after Peerlify receives the delete: their membership is deleted and the auth keys they created in the network are revoked. If your identity provider adds the same person again within those 30 days, the earlier membership comes back with its role. After the removal, signing in through your identity provider doesn't add them back; only provisioning them again does. Because Okta never deletes users, members it deactivated stay Suspended by IdP until you remove them on the Members page.

The network Owner

Deactivation applies to the Owner too: an identity provider is trusted to say who still works for you. The Owner loses access to the network like anyone else, and Peerlify emails the network's Security issues contact (or, if that is blank, the Owner) saying so. Ownership can't be moved by your identity provider: contact Peerlify support to transfer it. A deleted Owner's membership isn't removed after 30 days; it stays suspended until ownership is transferred.

Groups in access rules

Each group your identity provider sends becomes a synced group. Access → Groups lists them under Synced groups, read-only, with their names and the identity provider they come from.

A synced group's name is group:<name>@<domain>:

• <name> is the group's name in your identity provider, lowercased, with each run of characters other than letters and digits replaced by -, and at most 64 characters. Security Team becomes security-team.
• <domain> is your organization's primary domain: your Entra tenant's default domain, or the domain your single sign-on is registered for.

For example, group:security-team@example.com. Use it like any other group:

{
  "name": "Security team reaches production over SSH",
  "action": "accept",
  "source": ["group:security-team@example.com"],
  "destination": ["tag:prod"],
  "ports": ["22"],
  "protocol": ["tcp"]
}

A synced group can be used in rule sources and destinations, shadowing rules, exit-point rule sources, inside your own groups, and as a tag manager. It can't be used to assign roles, and it doesn't count toward the plan's group limit.

It matches the untagged devices of members who are linked and not suspended, like any person-based selector (see Which devices a person-based selector covers). People still Waiting for first sign-in match nothing until they sign in. Membership changes at your identity provider reach devices within about 10 seconds of Peerlify receiving them, without editing the policy.

• Renaming a group at your identity provider changes the name shown in the console only. Its group: name stays the same, so your rules keep working.
• Deleting a group at your identity provider, or removing it from provisioning, deletes the synced group. Rules that refer to it then match nobody. Edits to a policy that already refers to it still save.
• Your own groups win. If your policy already declares a group with the same name, or another synced group already holds it, the new synced group shows Name conflict and matches nobody; the existing group keeps its meaning. The conflict clears when the other group goes: when you remove the policy group from the policy, or when the other synced group is deleted. Renaming a group at your identity provider doesn't clear it, because the name is fixed when the group is created; to use a new name, rename the group and then remove it from provisioning and add it again.
• You can't declare a policy group with the name of an active synced group: saving the policy fails with Invalid groups.
• Nested groups aren't synced: a group can contain people only.

Existing members

Turning on provisioning removes nobody. Members who joined before, through invites or sign-ins, keep their access. If your identity provider later sends one of them, they are linked and keep their role.

Settings → Provisioning lists signed-in members your identity provider hasn't sent under Members not in your identity provider. Review the list and remove anyone who should no longer have access with Remove. Nothing removes them automatically, and invites keep working, so you can still add people from outside your identity provider, such as contractors.

Removing provisioned members

While provisioning is on, a member your identity provider manages (Synced) can't be removed in Peerlify: Remove member is disabled, and the REST API answers 409 with Provisioned by Entra ID. Unassign them in your identity provider. (or Okta). Unassign them in your identity provider instead, so the two can't disagree.

You can remove members who are Waiting for first sign-in, Can't be linked or Suspended by IdP, members your identity provider never sent, and anyone once provisioning is off. If your identity provider later sends a removed member again, they get a new membership.

When the plan lapses or changes

Provisioning can always take access away, and can grant it only while the network is on Enterprise and active. If the network is suspended, its plan lapses, or it moves to a plan without provisioning:

• your identity provider can still read users and groups, deactivate and delete users, delete groups and remove group members, so a deprovisioning is never lost;
• every other change, such as adding a user or a group member, is refused with Provisioning is paused: and the reason; a request mixing both is refused as a whole;
• users and groups already synced stay and keep applying in your rules;
• the status line reads Provisioning paused: with the reason, Deactivations still apply.;
• a new token can't be issued, but you can still revoke the token or turn provisioning off.

Peerlify doesn't keep the refused changes. When the network is back on Enterprise, your identity provider sends them again as it retries or on its next full sync; in Entra ID, Restart provisioning resends everything at once.

Audit

Every change your identity provider makes is recorded in the network's audit log with Entra ID (SCIM) or Okta (SCIM) as the actor. Turning provisioning on or off, rotating and revoking the token, and changing its settings are recorded with the person who did it. Updates that change nothing aren't recorded.

Limits

• One identity provider per network.
• Size: up to 50,000 provisioned users, 5,000 groups and 50,000 group memberships per network. Beyond that, your identity provider's request is refused with 403 and a message naming the limit.
• Rate: 600 requests a minute per network. Beyond that, Peerlify answers 429 with a Retry-After header, and your identity provider retries.
• Requests: at most 512 KB, 1,000 operations per update and 1,000 members per operation. User names are at most 256 characters.
• Not supported: SCIM bulk requests, sorting, and password changes (passwords your identity provider sends are ignored and never stored).
• Google Workspace isn't supported yet. People from your Workspace still join through Sign in with Google.
• Roles aren't assigned from groups.

Next steps

• Members and roles
• Tags, groups and roles
• Sign in with Microsoft
• Set up single sign-on