Provision members with SCIM

With SCIM, your identity provider keeps Polzy's members in step with your directory. When someone joins, changes or leaves on your side, your directory tells Polzy straight away, and nobody has to invite or remove people by hand. This guide covers the token, the setup in each directory, and what Polzy does with each change.

How it works

• Added. A new person in your directory becomes a member, in the workspace and with the role you chose for single sign-on, without an invitation email. They sign in through your identity provider.
• Updated. A change to their name reaches every workspace they belong to.
• Deactivated. Deactivating someone in your directory deactivates them in Polzy at once and ends their sessions. Their seat is freed.
• Removed. Deleting someone in your directory removes their memberships of your organization. Their answers and what they made stay.
• Groups. Your directory sends its groups as well as its people. The group rules in single sign-on's People step give the people in each group a workspace and a role: one set of rules for single sign-on and SCIM.

On Organization settings → Members, people your directory created or holds carry the label Managed by your directory.

Before you start

• Single sign-on, up to the People step. SCIM places people with the workspace, the role and the group rules you choose there. Choose the workspace under Create a member automatically; if you then switch to Only people already invited or synced, the workspace you chose is kept for SCIM. See Choose who gets in.
• Every domain verified. A person whose address is on any other domain is refused. See Verify your domain.
• No people sync. SCIM and a people sync from BambooHR, Workday, Personio or Microsoft Entra ID cannot both manage one organization. Disconnect the sync under Contacts → Sync & fields before you create a token; while a token exists, a sync cannot be connected.
• Free seats. Each membership a directory makes takes a seat on your plan.

Create the token

1. Open Organization settings → Security. In the Single sign-on section, find SCIM provisioning and choose Set up.
2. Under Connect your directory, copy the SCIM base URL: https://api.polzy.ai/api/scim/v2.
3. Under Token, choose Create token. Copy it from the window that opens: it is shown this once. Polzy keeps only a fingerprint of it, and its first characters to recognize it by.
4. Paste both into your directory, as the sections below describe.

• Replace token gives you a new token and keeps the current one working for 24 hours while you paste the new one into your directory.
• Revoke stops every token at once, and provisioning with it. The members your directory added stay as they are.
• Recent activity shows how many changes your directory made in the last 30 days.
• Workspaces and roles says where the people your directory sends land. Edit group rules opens the single sign-on People step, where the default workspace, the default role and the group rules are kept.

If someone else looks after your directory, the setup link you send them from the Single sign-on section has a SCIM step where they can create the token themselves. Replacing it stays with you, and revoking the link stops a token made through it. See Let your IT team do it.

Okta

SCIM in Okta runs in the same app you created for single sign-on.

1. On the app's General tab, choose Edit under App Settings, set Provisioning to SCIM and save. A Provisioning tab appears.
2. On the Provisioning tab, open Integration and choose Edit. Paste the base URL into SCIM connector base URL and enter userName as the Unique identifier field for users.
3. Under Supported provisioning actions, select Push New Users, Push Profile Updates and Push Groups.
4. Set Authentication Mode to HTTP Header and paste the token as the bearer token in Authorization. Choose Test Connector Configuration, then Save.
5. Under To App, choose Edit, turn on Create Users, Update User Attributes and Deactivate Users, and save.
6. On the Push Groups tab, choose Push Groups and push the groups your group rules name. Assigning a group on the Assignments tab sends its people, not the group: only a pushed group reaches your group rules.

Okta sends the Okta username as userName, so it must be the person's email address on one of your verified domains.

Okta's guides: Add SCIM provisioning to app integrations and Enable Group Push.

Microsoft Entra ID

1. In the Microsoft Entra admin center, open the Polzy enterprise application you created for single sign-on and go to Provisioning.
2. Set Provisioning Mode to Automatic (in newer tenants, choose New configuration).
3. Under Admin Credentials, paste the base URL as the Tenant URL and the token as the Secret Token. Choose Test Connection, then save.
4. Under Mappings, open the user mapping and check the source of userName: userPrincipalName by default, or mail if your people's sign-in names are not their email addresses.
5. Under Settings, set the scope to Sync only assigned users and groups, and assign the people and groups under Users and groups.
6. Set Provisioning Status to On and save.

Entra provisions in cycles of about 40 minutes. Provision on demand sends one person, or one group of up to five, straight away: the quickest way to try it.

Entra sends the groups assigned to the app with their object ID as externalId, so a group rule can name a group by its name or by that object ID, which is what Entra's group claim sends at sign-in.

Microsoft's guides: Develop and plan provisioning for a SCIM endpoint, Configure automatic user provisioning and Provision a user or group on demand.

OneLogin

OneLogin provisions through its SCIM Provisioner with SAML connector, which signs people in with SAML as well: you can set single sign-on up in that same app, with the values from the OneLogin section of the single sign-on guide.

1. Go to Applications → Add App and add SCIM Provisioner with SAML (the core schema). Name it Polzy.
2. On the Configuration tab, paste the base URL into SCIM Base URL and the token into SCIM Bearer Token. Keep the default SCIM JSON Template, which sends the email address as userName. Save, then choose Enable under API Connection.
3. On the Provisioning tab, select Enable provisioning.
4. On the Parameters tab, open Groups and select Include in User Provisioning.
5. Give the people who use Polzy access to the app.

OneLogin's guide: Create a SCIM app.

JumpCloud

1. In the JumpCloud Admin Portal, open the Polzy app under Access → SSO Applications and go to its Provisioning tab.
2. Paste the base URL into Base URL and the token into Token. Under Test User Email, enter the address of someone already in Polzy, and choose Test Connection.
3. Turn on Enable management of User Groups and Group Membership in this application, then choose Activate. Choosing Save instead leaves provisioning off.
4. On the User Groups tab, add the groups who use Polzy.

JumpCloud's guide: Integrate with custom SCIM.

Ping Identity

1. In PingOne, go to Integrations → Provisioning, add a New Connection of the kind Identity Store → SCIM Outbound.
2. Enter the base URL as SCIM Base URL, /Users as Users Resource and /Groups as Groups Resource, and choose SCIM 2.0.
3. Set Authentication Method to OAuth 2 Bearer Token, paste the token into OAuth Access Token, and choose Test connection.
4. Set the User Identifier to the email address, and enable creating, updating, disabling and deprovisioning users.
5. Add an outbound rule that names the people and groups to provision: a connection alone provisions nobody.

Ping Identity's guides: Creating a SCIM connection and Creating an outbound rule.

Google Workspace

Google Workspace provisions to apps outside its catalog through custom SCIM profiles, a beta open to a limited number of participants. If your Google Workspace has it, configure auto-provisioning on the Polzy SAML app with the base URL as the Endpoint URL and the token as the Access token.

Google's guide: Set up automated user provisioning with custom SCIM profiles.

Another SCIM 2.0 directory

Any SCIM 2.0 client that can send a bearer token works. Point it at the base URL and send Authorization: Bearer followed by the token.

• Users and groups. /Users and /Groups, with filtering by userName, emails.value and externalId (the eq operator, joined by and; userName and emails.value whatever their case). Group membership arrives on /Groups, by POST, PUT or PATCH; a groups attribute sent on a user is read-only in SCIM and ignored.
• What a user carries. userName (the email address), name.givenName, name.familyName, externalId and active. From the enterprise extension, department and employeeNumber fill workspace fields of the same name, and manager sets the person's manager where reporting lines are on.
• Not supported. Bulk requests, sorting, ETags and password changes.
• Rate limit. 600 requests a minute per token.

What Polzy does

• Existing members. Someone already in your organization is matched by their email address. If they first arrived by signing in through your identity provider, your directory takes their membership over once it sends a group they are in, and the group rules decide their role from then on; taking it over never lowers the role they have. Someone an admin invited keeps the workspaces and roles they have.
• Groups. A person in a group that a rule names is a member of that rule's workspace, with the strongest role their groups give, and in the default workspace never less than the default role. The rules are applied each time your directory adds someone to a group or takes them out of one: Okta and Microsoft Entra ID create the person first and add them to the group a moment later, and the role follows then. A rule matches a group by its name, whatever its case, or by the ID your directory sends as externalId. Leaving the group removes that membership again, unless their default workspace or another rule still gives it.
• What stays yours. Memberships an admin made by hand are never removed or changed by the directory. The Owner is never deactivated or removed by it, and someone the Owner blocked stays blocked.
• Seats. Each membership needs a free seat. When none is free, Polzy refuses the change and your directory reports the error. Deactivating someone frees their seats; activating them again needs free ones.
• Audit log. Every change the directory makes is recorded in the audit log, with Directory (SCIM) as who made it.

When you change the default workspace or the group rules in the single sign-on People step, everyone your directory placed is placed again by them, in the background.

Troubleshooting

Your directory shows Polzy's answer in its provisioning log. The usual ones:

Limits

• SCIM 2.0, for users and groups, tested with Okta and Microsoft Entra ID provisioning.
• One directory per organization, through one token at a time.
• Usernames must be email addresses on your verified domains, and a username cannot change.
• SCIM and a people sync cannot both manage the same organization.
• Deleting someone removes their memberships, not their data: erasing a person is a separate step an admin takes from their record. See People, contacts and fields.

Useful links

• Okta: Add SCIM provisioning to app integrations
• Microsoft: Develop and plan provisioning for a SCIM endpoint
• OneLogin: Create a SCIM app
• JumpCloud: Integrate with custom SCIM
• Ping Identity: Creating a SCIM connection
• Set up single sign-on, which SCIM builds on.