SCIM provisioning

Before you start

• Enterprise plan, with an active subscription
• At least one verified domain in the CCTVplanner organization console
• A sign-on connection that has passed its test and is switched on, so the accounts your directory creates can be used
• Owner or administrator access to cctvplanner.io/organization
• Application Administrator in Microsoft Entra ID, or Super Administrator in Okta
• A password manager or vault, the provisioning token is shown once

Steps

1. 1

   Check the sign-on connection before you start

   A connection is in one of four states: draft, testing, active or disabled. Provisioned accounts are of no use until the connection is active, so settle this first.

   Open the connection in the organization console and run its test. The console opens your identity provider in a new browser tab and you sign in there. That sign-in creates a twin account: a second, separate CCTVplanner account at your own address, held by the identity provider and occupying no seat, because an SSO identity is never linked to an existing password account. The test tab confirms the result, signs that twin account out again and hands the outcome back to the original console tab, which restores your own session.

   Only after the test passes can you switch the connection on.

   Editing an active connection's metadata puts it back into testing. Plan metadata edits accordingly: while a connection is testing, the people who depend on it cannot sign in.

   The states and what a sign-in through them does are in the table below.

   DraftNot yet tested, not usable for sign-in

   TestingOrdinary sign-ins are refused with SSO_CONNECTION_TESTING

   ActiveSign-in works for addresses at your verified domains

   DisabledSign-ins are refused with SSO_PROVIDER_DISABLED

   A connection is bound to your verified domains. An assertion carrying an address outside them is refused with SSO_EMAIL_OUTSIDE_DOMAIN, at sign-in and again at every token refresh.

2. 2

   Create the provisioning token

   Open cctvplanner.io/organization and find the provisioning tokens.

   Create a bearer token. It is shown once, then stored only as a SHA-256 hash, so paste it into your vault before you close the dialog.

   Two tokens can be live at a time. That second slot exists so you can rotate without an outage: create the new token, paste it into the directory, test, then revoke the old one.

   Tokens expire after one year.

   Token lifetimeOne year from creation

   Live tokens per organisationTwo

   StorageSHA-256 hash, the token itself is never shown again

   If you lose the token there is no recovery. Create a new one and revoke the lost one.

3. 3

   Copy the SCIM base URL

   The console shows the SCIM base URL for your project with a copy button. Copy it from there rather than typing it from this page.

   Its shape is https://<project>.supabase.co/functions/v1/scim/v2, where the project host is yours.

   Paste the value exactly as the console gives it to you. Do not add or remove a trailing slash on your own.

   Seats: an account created by the directory occupies a seat, and deactivating that account in the directory does not release it.

   SCIM base URL (shape)https://<project>.supabase.co/functions/v1/scim/v2

   AuthenticationBearer token in the Authorization header

   ResourcesUsers. Groups is read-only and always returns an empty list.

   Filteringeq only, on userName, externalId, id and emails[type eq "work"].value
4. 4

   Microsoft Entra ID: add the provisioning configuration

   In the Microsoft Entra admin center, go to Entra ID, then Enterprise apps, and open the application you already use for SAML sign-in.

   Select Provisioning in the left panel, then + New configuration.

   Put the base URL in Tenant URL and the token from the previous step in Secret Token.

   Select Test Connection, then Create. Older tenants show the previous screen instead, where you set Provisioning Mode to Automatic and open Admin Credentials to reach the same two fields.

   Tenant URLThe SCIM base URL copied from the console

   Secret TokenThe bearer token created in the previous step

   Do not leave Secret Token blank. Entra then sends a token it issued itself, which we do not accept. Test Connection queries the endpoint for a user that does not exist, using a random GUID as the matching property, so it only proves the connection when the matching property is one we can filter on.

5. 5

   Microsoft Entra ID: fix the mappings you keep, delete the rest

   Select Attribute mapping in the left panel, then the user mapping.

   Entra maps userName from userPrincipalName by default. If your people sign in with a UPN on an onmicrosoft.com domain, change the source so userName carries the corporate address at a verified domain.

   Set Matching precedence 1 on userName. We support eq filtering on userName, externalId, id and the work e-mail, so matching on userName is safe and it is the value a person signs in with.

   Entra's default mapping for externalId is mailNickname. Change it to objectId, which survives a rename.

   Keep userName, active, name.givenName, name.familyName, emails[type eq "work"].value and externalId. Delete the rest, including the telephony, address, manager and locale rows, and disable the group mapping.

   Attributes we do not read are accepted and ignored, not rejected. Delete their mappings to keep your provisioning log readable, not to prevent an error.

   Filtering supports eq only. A mapping that makes Entra match on anything else will fail on every cycle.

6. 6

   Microsoft Entra ID: set the scope, then start provisioning

   In the provisioning configuration you created two steps ago, set Scope to Sync only assigned users and groups. Syncing the whole directory pushes every account at every domain, including the ones outside your verified domains.

   On the Users and groups tab, assign the group that should have CCTVplanner. Nothing is provisioned until you do.

   Select Provision on-demand in the left panel and run a single person first, then read the result.

   Select Overview, then Properties, then the pencil to edit. Enable notification emails, give an address for quarantine mail, and select Apply.

   Select Start provisioning.

   The first cycle runs long, and later cycles run approximately every 40 minutes. Provision on-demand is the only fast feedback loop.

7. 7

   Okta: enable the API integration

   In the Okta admin console, open Applications, open your SAML app, and select the Provisioning tab.

   Select Configure API Integration, then tick Enable API Integration.

   Put the base URL in SCIM connector base URL and userName in the unique identifier field for users.

   Under Supported provisioning actions, tick Push New Users and Push Profile Updates. Leave Import New Users and Profile Updates off: we do not support directory-driven import. Leave Push Groups off.

   For Authentication Mode select HTTP Header and paste the bearer token into the Authorization field. Okta sends it as Authorization: Bearer followed by your token, so paste the token on its own.

   Select Test API Credentials, then Save.

   SCIM connector base URLThe SCIM base URL copied from the console

   Unique identifier field for usersuserName

   Supported provisioning actionsPush New Users and Push Profile Updates only

   Authentication ModeHTTP Header

   AuthorizationThe bearer token created earlier, on its own
8. 8

   Okta: turn on the provisioning actions and check the mappings

   Still on the Provisioning tab, open To App and select Edit.

   Enable Create Users, Update User Attributes and Deactivate Users. Without Deactivate Users an offboarding in Okta leaves the CCTVplanner account live.

   Scroll to the attribute mappings and confirm that userName carries the corporate address. If your Okta usernames are not e-mail addresses, for example accounts at "@yourorg.okta.com", map userName from user.email.

   We read the user name, the active flag, the given and family names, the work e-mail and the external id. Okta fills externalId with the Okta user id by itself, so there is nothing to map for it.

   Remove mappings you do not need. Anything else you send is accepted and ignored.

   Do not push groups. Groups is read-only here and always returns an empty list, and roles are set in CCTVplanner.

9. 9

   Okta: assign the app to the right people

   Open the Assignments tab and assign the group that should have CCTVplanner.

   Assign a group rather than individuals, so an offboarding in the directory removes the assignment and triggers the deactivation.

   An Okta group assignment governs who gets an account. It does not set anyone's role. Roles are set in the CCTVplanner console.

10. 10

    Deactivate one person and confirm the behaviour

    Deactivate your test account in the directory and watch what happens here.

    Deactivating suspends the account, ends the sessions and bans the login. It does not delete anything.

    Access tokens live fifteen minutes, so an open browser stops working within fifteen minutes at the latest and then shows SSO_ACCOUNT_SUSPENDED. There is no shorter cut-off: the ban applies at once, the token already in the browser has to expire.

    The seat stays occupied and the projects, offers and price lists stay with the organisation. That is deliberate: an offboarding must never take the work with it.

11. 11

    Work inside the limits

    Users only. Groups is read-only and always returns an empty list, because roles are set in CCTVplanner and not in your directory.

    There is no group to role mapping. Set the role in the console after the account appears.

    Filtering supports eq only, on userName, externalId, id and emails[type eq "work"].value. PATCH is supported. Bulk and sort are not.

    The directory may only create people at your verified domains. Contractors on a foreign address have to be invited by hand.

Attribute mapping

Prove it works

1. In the organization console, run the test on the sign-on connection. Sign in at your identity provider in the tab the console opens, and wait for the console to report the outcome and restore your own session.
2. Confirm the console reports that the test passed, then switch the connection on.
3. Run Test Connection in Entra ID, or Test API Credentials in Okta, and confirm the directory reports success.
4. Provision one person: Provision on-demand in Entra, or assign one test user in Okta.
5. Open cctvplanner.io/organization, confirm the person appears, and set their role there.
6. Have that person sign in through single sign-on and reach a project.
7. Change their surname in the directory and confirm the change reaches the console, on demand or on the next cycle.
8. Deactivate them in the directory, then confirm the console shows them suspended and their open session stops working within fifteen minutes, with SSO_ACCOUNT_SUSPENDED.

Troubleshooting

Worth knowing

• Provisioning and sign-in are separate switches. A person created by SCIM still cannot sign in while the connection is disabled, and they see SSO_PROVIDER_DISABLED; while it is testing, they see SSO_CONNECTION_TESTING.
• An SSO identity is never linked to an existing password account at the same address. Somebody who already has a password account here and then signs in through your identity provider ends up with a second, separate account. SCIM does not change that.
• A connection takes either a metadata URL or pasted metadata XML. Prefer the URL: re-saving the connection re-reads it, while a pasted document has to be replaced by hand.
• We do not refresh provider metadata on a schedule. A daily job reads the identity provider's signing certificate expiry from the metadata and e-mails the organization's owner before it lapses. After your provider rotates the certificate, open the connection in the console and save it again, which re-reads the metadata URL. If the metadata was pasted as XML, paste the new document.
• A sign-in redirect target has to be on our allow list.
• The console shows the owner the service provider values with copy buttons, the claimed and verified domains with the DNS TXT record to publish, the connection with its display name, provider template, entity id and certificate expiry, the sign-in policy, the provisioning tokens, and an audit list with an export button.
• There is no SIEM streaming. The audit list exports from the console, and that is where provisioning activity on our side can be reviewed.
• The e-mail attribute names are tried first, in the order documented on the sign-on page. The NameID is the fallback, used only when no e-mail attribute arrives, so a wrong NameID on its own does not break a connection that maps an e-mail attribute.