Skip to main content

Provisioning Users and Groups with SCIM

Automate user and group management in Poka by connecting your Identity Provider (IdP) directly to the platform.

Written by Eyad Saheb

SCIM automates user and group management in Poka by connecting your Identity Provider (IdP) directly to the platform. Once configured, your IdP becomes the source of truth — creating, updating, and deactivating users and groups automatically.

This setup requires collaboration between your Poka Global Administrator and your IT team. We recommend reading through the full article before starting.

  • SCIM provisioning is only available with an eligible subscription. Check with your Poka representative to confirm availability.

  • Only Global Administrators can activate and manage SCIM in Poka.

Key Behaviors

  • SCIM-managed and locally managed users can coexist.

  • Existing users matched by username during sync are converted to SCIM-managed.

  • New users are created if no match is found.

  • Fields managed by SCIM and become not editable in Poka:

    • Username

    • First Name

    • Last Name

    • Email Address

  • Required uniqueness across all accounts:

    • Username

    • Email

    • Employee Number

  • SCIM provisioning is a one-way sync — changes made in Poka do not sync back to your IdP.

Step 1 — Poka Admin: Generate Your SCIM Credentials

The Poka Admin completes this step first and passes the credentials to IT.

  1. Go to Admin Panel > Security > Identity Providers > User Provisioning

  2. Select a Default Home Plant — this is assigned to new users when no Home Plant is specified during provisioning

  3. Click Generate Token and copy to a secure location

  4. Note the SCIM API URL

Pass both the SCIM API URL and SCIM Authentication Token to your IT team to proceed with Step 2.

Note: The SCIM Authentication Token cannot be used with other Poka API endpoints. If you delete the token, SCIM is instantly disabled. To re-enable, generate a new token and update your IdP.

IP & Geo Access

If your Poka instance has IP/Geo restrictions enabled, you must allow access for the SCIM token.

  1. Go to Admin Panel > Security > IP/Geo Access Rules in Poka

  2. Create a rule with no restrictions (0.0.0.0) and assign it to the SCIM Token user

Consult your IdP documentation for the specific IP ranges your Entra instance uses if you prefer a more restrictive rule.

Step 2 — IT: Configure Entra ID (Azure AD)

Initial Setup

  1. In Entra ID, create a new enterprise application (or reusing the existing one from SSO if that's already configured)

  2. Navigate to Manage > Provisioning

  3. Set Provisioning Mode to Automatic

  4. Under Admin Credentials, enter:
    - Tenant URL: paste the SCIM API URL provided by the Poka Admin
    - Secret Token: paste the SCIM Authentication Token provided by the Poka Admin

  5. Click Test Connection to verify, then click Save

Field Mappings

Next you'll configure which Entra attributes map to Poka user fields.

Navigate to Mappings and open the User mappings.

Configure the following fields:

customappsso (Poka)

Entra ID Attribute

Type

Matching

userName

userPrincipalName

Direct

Yes

active

see below*

Expression

emails[type eq "work"].value

mail

Direct

name.givenName

givenName

Direct

name.familyName

surname

Direct

externalId

mailNickname

Direct

Yes

urn...employeeNumber (optional)

employeeId

Direct

* Switch([IsSoftDeleted], , "False", "True", "True", "False")

Mapping Home Plant (Recommended)

This tells Poka which plant to assign each user to during provisioning. Before proceeding, confirm which Entra attribute contains a plant identifier for each user. This may be a custom extension attribute (e.g., extension_xxxx_PlantID). If this attribute doesn't exist yet, work with your Entra administrator to create and populate it before continuing.

To add the home plant mapping:

  1. In the User mappings screen, click Add New Mapping

  2. Set Mapping Type to Expression

  3. In the Expression field, enter:

Append("external|", [your-plant-attribute])

  1. Set Target Attribute to urn....:Poka:2.0:User:homePlantId

  2. Set Apply this mapping to Always

  3. Click OK

Important: The value produced by this expression must exactly match an External ID configured for each plant in Poka. For example, if your Entra attribute contains NEW_YORK, the expression produces external|NEW_YORK — and NEW_YORK must be set as the External ID for that plant under Admin Panel > Structure > Plants in Poka.

Group Mappings

Navigate to Mappings and open the Group mappings. Configure the following:

Poka Field

Entra ID Attribute

Type

displayName

displayName

Direct

members

members

Direct

Tip: Avoid assigning a group as both an App Assignment Group and a Push Group — this can cause sync issues.

Activating Provisioning

  1. Click Start Provisioning to activate

  2. Use Provision on Demand to test individual users before your full sync runs

Step 2 (Alternative) — IT: Configure Okta

Initial Setup

  1. In Okta, navigate to your Poka SSO Application

  2. Go to the Provisioning tab

  3. Click Configure API Integration and enable it

  4. Enter the following:

    • SCIM Base URL: paste the SCIM API URL provided by the Poka Admin

    • Unique Identifier: userName

    • Authentication Mode: HTTP Header

    • Authorization: paste the SCIM Authentication Token provided by the Poka Admin

  5. Click Test Connector Configuration to verify

Confirm the following features are detected:

Feature

Status

Create Users

✅ Enabled

Update User Attributes

✅ Enabled

Push Groups

✅ Enabled

Deactivate Users

✅ Enabled

Click Save.

Provisioning Operations

Under the Provisioning tab, go to To App settings and enable:

  • ✅ Create Users

  • ✅ Update User Attributes

  • ✅ Deactivate Users

Do not enable:

  • ❌ Import New Users and Profile Updates

  • ❌ Import Groups

Field Mappings

Navigate to the Attribute Mappings section and configure the following:

Poka Field

Okta Attribute

Type

userName

user.login

Direct

name.givenName

user.firstName

Direct

name.familyName

user.lastName

Direct

email

user.email

Direct

employeeNumber (optional)

user.employeeNumber

Direct

homePlantId (recommended)

see below

Expression

Mapping Home Plant (Recommended)

As with Entra, the source attribute must exist in your Okta user schema before completing this step. This is typically a custom attribute holding a plant identifier per user.

  1. In the Attribute Mappings screen, locate or add the homePlantId field

  2. Set the mapping to an Expression using:

Append("external|", user.homePlant)

Replace user.homePlant with whichever Okta attribute holds your plant identifier

  1. Set Apply on to Create and Update

Important: The same rule applies as in Entra — the value produced must exactly match the External ID configured for the plant in Poka under Admin Panel > Structure > Plants.

Group Mappings

  1. Under the Push Groups tab, add the groups you want to sync to Poka

  2. Okta will push group names and memberships to Poka automatically

Note: Unlike Entra ID, Okta does not support SCIM-based user deletion. Deactivating a user in Okta will deactivate them in Poka, but will not delete them from the platform.

Tip: Avoid assigning a group as both an App Assignment Group and a Push Group — this can cause sync issues.

Activating Provisioning

Once mappings are configured, assign users or groups to the application in Okta to trigger provisioning.

Use Provision on Demand in Okta to test individual user syncs before rolling out to your full user base.

Troubleshooting

Users are not being assigned to the correct Home Plant

  • Check your Entra Provisioning Logs (Entra > Enterprise Application > Provisioning > Provisioning Logs) to see exactly what value is being pushed for homePlantId and confirm that the value matches the external ID set for the plant in Poka under Admin Panel > Structure > Plants

  • Confirm that the source attribute in Entra is populated for all affected users — empty values will cause users to fall back to the Default Home Plant

"Access from your GEO / IP address is not allowed" error

  • Your SCIM token is being blocked by IP/Geo access rules — see the IP & Geo Access section above

Users are not being created

  • Verify the SCIM API URL and Authentication Token were entered correctly in your IdP, and that the SCIM provisioning status in Poka is active (token has not been deleted)

  • Check your Entra Provisioning Logs (Entra > Enterprise Application > Provisioning > Provisioning Logs) to see exactly what value is being pushed for homePlantId and confirm that the value matches an external ID set for the plant in Poka under Admin Panel > Structure > Plants. Incorrect values for homePlantId will result in a SCIM provisioning error.

  • Check your Entra Provisioning Logs (Entra > Enterprise Application > Provisioning > Provisioning Logs) to see if there's an error such as "an employee with this number already exists". Search for that value among existing Poka profiles in Admin Panel > Users. Use the filters to adjust Account Status to All Users. If an existing profile is found with that value, remove it from their account so SCIM can use it to provision the new user.

Did this answer your question?