RillaRilladevelopers
Go to Rilla
DocumentationFull reference

SCIM provisioning

Let Microsoft Entra ID or Okta create, update and remove Rilla users and teams automatically.

Overview

SCIM lets your identity provider (IdP) manage Rilla users for you. Assign someone in your IdP and they get a Rilla account. Change their name, email or role and Rilla updates. Unassign them and they lose access. Groups you push become Rilla teams.

Rilla supports SCIM 2.0 with Microsoft Entra ID and Okta.

Base URL

https://customer.rillavoice.com/scim/v2

Before you start

  • SSO must already work. SCIM adds user provisioning to your existing Rilla SSO connection. If you don't have one, contact Rilla support first.
  • You need the Admin role in Rilla.
  • Your IdP becomes the source of truth. Edits made by hand in Rilla can be overwritten on the next sync.
  • Only provisioned people can sign in. With SCIM on, signing in with SSO no longer creates an account.

Generate a token

  1. In Rilla, go to Settings → Developer → SCIM.
  2. Click Generate token next to your SSO connection.
  3. Copy the token. It's shown once.

Keep your token secure

Anyone with the token can add and remove users in your organization. Store it only in your IdP.

Rotate token replaces it and stops the old one right away. Revoke token turns SCIM off. Existing users and teams stay.

Set up your identity provider

Rilla SSO with Entra uses an App registration. Entra can't provision through an App registration, so SCIM needs its own enterprise app. Your existing SSO setup doesn't change. If your SSO app has Assignment required turned on, assign people to both apps: the SSO app lets them sign in, the SCIM app gives them an account.

In the Microsoft Entra admin center, go to Enterprise applications → New application → Create your own application. Name it something like Rilla SCIM and choose Integrate any other application you don't find in the gallery (Non-gallery).

Open the new app, go to Provisioning, and set Provisioning Mode to Automatic. Under Admin Credentials:

  • Tenant URL: https://customer.rillavoice.com/scim/v2
  • Secret Token: the token from Rilla

Click Test Connection, then Save.

Under Mappings → Provision Microsoft Entra ID Users, change userName from userPrincipalName to mail. Rilla matches people by email.

On the app's registration (App registrations → All applications → Rilla SCIM), add app roles named Admin, Team Manager and Sales Rep. Then add a mapping from SingleAppRoleAssignment([appRoleAssignments]) to roles[primary eq "True"].value.

Under Users and groups, assign who should have Rilla. Assigned groups become teams.

Set Provisioning Status to On. Entra syncs about every 40 minutes. Use Provision on demand to sync one person now.

Turn SCIM on in your Rilla SSO app if Okta offers it there. SAML apps and OpenID Connect apps created in the Okta Integration Wizard support it. Older OpenID Connect apps don't, so create a separate app for SCIM: Applications → Create App Integration → SWA, with https://app.rilla.com as the login URL. With two apps, assign people to both: the SSO app lets them sign in, the SCIM app gives them an account.

In the app, go to General → App Settings and set Provisioning to SCIM.

On Provisioning → Integration, click Edit and set:

  • SCIM connector base URL: https://customer.rillavoice.com/scim/v2
  • Unique identifier field for users: userName
  • Supported provisioning actions: Push New Users, Push Profile Updates, Push Groups
  • Authentication Mode: HTTP Header, with the token from Rilla

Click Test Connector Configuration, then Save.

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

Set Application username format to Email. Rilla matches people by email.

In the Profile Editor, add an attribute with external name roles.^[primary==true].value and namespace urn:ietf:params:scim:schemas:core:2.0:User. Set it to Admin, Team Manager or Sales Rep.

Assign people on Assignments. Add groups on Push Groups to create teams.

What syncs

In your IdPIn Rilla
Assign a personCreates their account. No invite email: they sign in with SSO.
Change name, email or roleUpdates the account.
Unassign or deactivateRemoves access and frees the seat. Their history is kept.
ReassignRestores the same account.
Push a groupLinks the team with the same name, or creates one.
Change group members or nameUpdates the team.
Delete a groupUnlinks the team. The team and its members stay.
  • Existing users are matched by email, ignoring case, so they aren't duplicated.
  • New non-admins join your default team if you have one. Group sync doesn't remove them from it.
  • Admins aren't added to teams. They already see the whole organization.
  • Removed people can't sign back in with SSO. Only your IdP can restore them.

Roles

Rilla reads the primary roles value. Case and spacing don't matter.

ValueRilla role
AdminAdmin
Team ManagerTeam Manager
Sales RepSales Rep
  • New users without a recognized role are Sales Reps.
  • An unrecognized role on an update keeps the current role, so a mapping mistake can't demote an admin.
  • In Okta, set the role to Sales Rep instead of clearing it. Okta can leave a cleared role out of the update, which keeps the old role.

User attributes

SCIM attributeRilla field
userNameEmail, used to find existing users
emails (primary)Email, when present
name.givenName / name.familyNameFirst and last name
roles (primary)Role
activefalse removes the user, true restores them
externalIdYour IdP's ID for the user
phoneNumbers (primary)Phone number, set on creation only

Other attributes are ignored.

Troubleshooting

Reference

  • Base URL: https://customer.rillavoice.com/scim/v2
  • Authentication: Authorization: Bearer <token>
  • Content type: application/scim+json or application/json
  • Errors: RFC 7644 responses with status, scimType and detail
EndpointMethods
/ServiceProviderConfig, /ResourceTypes, /SchemasGET
/Users, /GroupsGET, POST
/Users/{id}, /Groups/{id}GET, PUT, PATCH, DELETE
  • Filters: userName and externalId on /Users, displayName and externalId on /Groups, with eq only. Anything else returns 400 invalidFilter.
  • Paging: startIndex and count, up to 200 per page.
  • Not supported: bulk operations, sorting, ETags, passwords.
  • DELETE /Users/{id} works like active: false. Repeating it does nothing.
On this page