SCIM with Okta
Let Okta add, update and deactivate your organisation's members in Plotwork, and push the groups that decide their roles. You need Enterprise, and an email domain verified on the Single sign-on tab, as the single sign-on guide describes.
TL;DR
| Okta field | Value from Plotwork |
|---|---|
| Where | Applications and Resources, Applications, your Plotwork app: General, then Provisioning |
| Provisioning (General tab, App Settings) | SCIM |
| SCIM connector base URL | The SCIM base URL: https://api.plotwork.dev/scim/v2/<organisation id> |
| Unique identifier field for users | userName |
| Supported provisioning actions | Push New Users, Push Profile Updates, Push Groups |
| Authentication Mode | HTTP Header |
| Authorization (Bearer) | The token from Make token, which starts with pwscim_ |
| To App | Create Users, Update User Attributes, Deactivate Users |
1. Make the token in Plotwork
- In the portal, open your organisation, then the Single sign-on tab.
- Under Provisioning with SCIM, press Make token.
- Copy the token now: it is shown once. Copy the SCIM base URL too.
2. Turn on SCIM for the app
Provision from the app integration your people sign in with, as set up in Single sign-on with Okta. Okta adds SCIM to a SAML or SWA app integration, and to an OpenID Connect one made with the App Integration Wizard.
- In the Okta Admin Console, open Applications and Resources (Applications in older consoles), then Applications, and select the Plotwork app.
- On the General tab, under App Settings, select Edit.
- Set Provisioning to SCIM, and select Save. A Provisioning tab appears.
If SCIM is not offered, provisioning is not turned on for your Okta org: Okta Support turns it on.
3. Paste the values
On the Provisioning tab, under Settings, Integration, select Edit, and fill in:
| Okta field | Value |
|---|---|
| SCIM connector base URL | The SCIM base URL from Plotwork, with nothing added at the end |
| Unique identifier field for users | userName |
| Supported provisioning actions | Push New Users, Push Profile Updates and Push Groups. Leave Import New Users and Profile Updates off: Plotwork does not send people to Okta. |
| Authentication Mode | HTTP Header |
| Authorization | The token from Plotwork. Okta adds Bearer itself. |
Select Test Connector Configuration. Okta calls the base URL with the token and lists the actions it can use. A refusal shows Plotwork's status and sentence; see Troubleshooting. Close the result and select Save.
4. Turn on what Okta sends
On the Provisioning tab, under Settings, To App, select Edit and turn on:
| Okta setting | What it does in Plotwork |
|---|---|
| Create Users | A person assigned to the app joins the organisation as a member, within your member limit |
| Update User Attributes | Their name follows Okta |
| Deactivate Users | A person unassigned or deactivated in Okta leaves the organisation at once, and every session they opened through your provider ends. Their API keys and agents stop at their next call. |
Leave Sync Password off: Plotwork has no passwords. Select Save.
5. Check the attribute mappings
Lower on To App, Attribute Mappings lists what Okta sends. Plotwork keeps these and ignores the rest:
| Okta attribute | Plotwork attribute | What Plotwork does with it |
|---|---|---|
Username (userName) | userName | The person's address, which must be on a verified domain. By default it is their Okta username. |
user.firstName | name.givenName | Kept |
user.lastName | name.familyName | Kept |
user.email | emails | Read only when userName is not an address |
If your Okta usernames are not addresses on your verified domain, change the app's username format on the Sign On tab, under Credentials Details, Application username format, to Email.
6. Assign people
On the Assignments tab, select Assign, then Assign to People or Assign to Groups, and assign who should be members of the Plotwork organisation. Okta provisions each one when you assign them.
7. Push groups
Assigning a group to the app gives its people access; pushing a group sends the group itself, so Plotwork can give it a role.
- Open the Push Groups tab.
- Select Push Groups, then Find groups by name (or Find groups by rule).
- Find the group, keep Push group memberships immediately ticked, and select Save.
Push only groups whose people are also assigned to the app: a member Okta has not provisioned cannot be in a Plotwork group.
8. Map groups to roles in Plotwork
The pushed groups appear in Plotwork under Groups and roles. Choose Admin, Member, Reader or No role for each.
| While | A provisioned person's role |
|---|---|
| No group gives a role | Never changed by SCIM |
| Any group gives a role | The highest role their groups give, or Member when none of theirs gives one |
For example, push Plotwork admins and Plotwork readers, give the first Admin and the second Reader, and everyone else assigned to the app is a Member. The owner is never changed.
9. Test it
- Assign one person whose username is on your verified domain.
- On the Assignments tab, their row shows whether provisioning worked. A failure is also a task under Dashboard, Tasks.
- In Plotwork, the person is on the Members tab, and Provisioning with SCIM counts them.
- Unassign them and check that they leave the organisation.
Okta's System Log, under Reports, lists every call with its result.
Troubleshooting
| What you see | What to check |
|---|---|
| Test Connector Configuration fails with 401 | The token was replaced or revoked in Plotwork, or Bearer was typed into Authorization. Make a new token and paste only the token. |
| Test Connector Configuration fails with 404 | The SCIM connector base URL is not the one from Plotwork. Copy it again, with nothing added at the end. |
| Test Connector Configuration fails with 403 | The organisation is not on Enterprise. |
| "The address is not on a domain the organisation verified for single sign-on." | The person's Okta username is on another domain. Set Application username format to Email, or verify the domain in Plotwork. |
| "userName cannot change." | The person's username changed in Okta. Unassign them and assign them again. |
| "A user with this userName already exists." | A person with this address is already provisioned here, by another app or before a reset. Remove the old app's assignment, or ask Plotwork support. |
| "The organisation has no free seats." | The member limit is reached. Raise it on the Members tab, or unassign someone. |
| "A member is not a user provisioned here." | A pushed group holds people who are not assigned to the app. Assign them, or push a group with only assigned people. |
| No Provisioning tab | Provisioning on the General tab is still None. Set it to SCIM. |
See also
| Page | Why |
|---|---|
| Provisioning with SCIM | What Plotwork keeps, what it supports, and every refusal |
| Single sign-on with Okta | Signing the same people in through Okta |
| SCIM with Microsoft Entra ID | The same for Microsoft Entra ID |
| Okta: connect a SCIM app integration (opens in a new tab) | Okta's own steps for the Provisioning tab |
| Okta: enable Group Push (opens in a new tab) | Pushing groups, by name or by rule |