BlueConic supports automated user provisioning through the System for Cross-domain Identity Management (SCIM) 2.0 standard. SCIM is an open IETF standard (RFC 7643 and RFC 7644) that automates user lifecycle management between an identity provider (IdP) and a service provider.
When SCIM is enabled, your IdP becomes the source of truth for user access in BlueConic. User accounts, role assignments, and domain assignments are created, updated, and deactivated automatically based on changes in your IdP. Your IT team no longer needs to manage these manually inside BlueConic.
With SCIM enabled:
New employees added to a group in your IdP are automatically created as BlueConic users.
Changes to roles or domain assignments in your IdP are automatically synced to BlueConic.
When employees leave and are deactivated or deleted in your IdP, that change propagates to BlueConic. Behavior depends on the IdP and connector configuration, as some IdPs do not send deletion events when a user is removed.
In BlueConic's SCIM setup, your IdP is the SCIM client and BlueConic is the SCIM service provider. Communication happens over HTTPS, authenticated with OAuth 2.0.
BlueConic recommends the client-credentials grant flow that your IdP exchanges a client ID and client secret for a short-lived access token, then uses that token to authenticate each SCIM call.
The authorization-code flow is also available if your IdP supports it, but most IdPs cannot complete it unattended, so client-credentials is the practical choice for SCIM.
BlueConic's SCIM 2.0 implementation has been verified with the following identity providers:
Identity provider | Status |
Microsoft Entra ID (formerly Azure AD) | Supported |
Okta | Supported |
OneLogin | Supported |
Before you begin
Before enabling SCIM provisioning, confirm the following:
Single sign-on (SSO) is configured for your BlueConic tenant. SCIM-provisioned users log in through your IdP using SSO. See Using single sign-on (SSO) with BlueConic.
All roles and domains your IdP will assign already exist in BlueConic. SCIM cannot create roles or domains. Configure each role's permissions and define each domain inside BlueConic before proceeding.
Your IdP-to-BlueConic group mappings are fully planned before you enable provisioning. Because SCIM clears existing role and domain memberships during a takeover, incomplete mappings result in roles or domains being removed from existing users on the first sync. A common approach is one BlueConic role per IdP group (for example, BC-Marketing, BC-Analyst, BC-Admin) and one IdP group per BlueConic domain (for example, BC-Domain-USsite, BC-Domain-EUsite).
Set up SCIM provisioning
Setting up SCIM is a manual, multi-step process and the order matters. Complete each step in sequence.
1. Configure SSO
Confirm SSO is configured for your tenant before enabling SCIM provisioning, so that SCIM-provisioned users can sign in. See Using single sign-on (SSO) with BlueConic.
2. Define roles and domains in BlueConic
A common approach is to define one BlueConic role per IdP group you intend to use for role provisioning (for example, BC-Marketing, BC-Analyst, BC-Admin), and similarly one IdP group per BlueConic domain (for example, BC-Domain-USsite, BC-Domain-EUsite).
3. Create a BlueConic OAuth application for SCIM
In BlueConic, go to Settings > Access Management > OAuth Applications and create a new application:
Flow / grant type: Client Credentials.
Scopes: USERS (both Read and Write).
Run-as user: an existing BlueConic user that has the MANAGE_USERS permission via one of its roles. This user is the audit actor for every SCIM call. We recommend creating a dedicated service user (for example [email protected]) so that audit trails clearly attribute SCIM activity to the IdP integration.
Save the application, then copy the Client ID and Client Secret. The secret is shown only once. You will need three URLs in the next step:
OAuth token endpoint:
Test URL (optional) — the SCIM ServiceProviderConfig discovery endpoint: https://[your-tenant].blueconic.net/blueconic/rest/v2/scim/v2/ServiceProviderConfig
4. Configure the BlueConic SCIM app in your IdP
Open or create the BlueConic SCIM application in your IdP. Most IdPs ask for the following fields under their SCIM integration (exact field names vary):
Tenant / Base URL: the SCIM base URL from Step 3.
Authentication method: OAuth 2.0 Client Credentials.
Token URL / Token endpoint: the OAuth token endpoint from Step 3.
Client ID: from Step 3.
Client Secret: from Step 3.
Note: Test the connection from the IdP — the IdP should be able to fetch the SCIM ServiceProviderConfig and Schemas endpoints using a freshly exchanged access token. The next section walks through the specifics for each supported IdP, including which field names each IdP uses for the values above.
5. Map IdP groups to BlueConic roles and domains
Before enabling any sync, decide which IdP groups in your organization should grant which BlueConic roles and domains, and configure those mappings in your IdP. There is no mapping table inside BlueConic. Your IdP discovers available BlueConic roles and domains through GET /Groups, and the linking is done entirely on the IdP side. See Configure SCIM by identity provider below.
6. Enable provisioning in your IdP
Once your role and domain mappings are complete, enable SCIM provisioning in your IdP and assign users to the BlueConic application. Start with a small pilot group of users to verify behavior before rolling out to all users.
7. Verify and roll out
Before expanding provisioning, confirm the following:
New users assigned to BlueConic in the IdP appear in BlueConic with the correct roles and domains.
Users who already existed in BlueConic show as provisioned (read-only) with the expected role and domain set.
Deactivating a test user in the IdP deactivates them in BlueConic on the next sync.
When the pilot is healthy, expand provisioning to the rest of your users.
Note: SCIM-provisioned users log in to BlueConic via your IdP using SSO. Make sure SSO is configured for your tenant before you enable SCIM provisioning, so that the users your IdP creates can actually sign in. |
Configure SCIM by identity provider
The mechanics of group discovery and mapping vary by IdP. The end result is the same: IdP groups assign BlueConic roles and domains. Use the section for your IdP below.
IdP | Group discovery | Mapping mechanism | Sync trigger |
Microsoft Entra ID | Automatic via filter query per assigned group | Users and Groups assignment + attribute mappings | Scheduled provisioning cycle |
Okta | Explicit Import run | Group Push tab, linked to Okta groups | Manual or scheduled push |
OneLogin | Fetched as Entitlements | Rules tab, mapped from OneLogin roles/attributes | Real-time or scheduled |
Microsoft Entra ID
Entra ID (formerly Azure AD) manages SCIM through its Enterprise Applications framework. There is no explicit import step — matching happens automatically during provisioning cycles.
Create a custom application for BlueConic SCIM. In the Azure Portal, navigate to Entra ID > Enterprise Applications > New Application, choose Create your own application, and select Integrate any other application you don't find in the gallery (Non-gallery). Give it a name such as BlueConic SCIM.
Open the new application, go to Provisioning, and set Provisioning Mode to Automatic. For Authentication, select OAuth 2.0 Client Credentials and enter the Token URL, Client ID, and Client Secret from the BlueConic OAuth Application you created in Step 3 of the setup. Set the Tenant URL to the BlueConic SCIM base URL. Click Test Connection — Entra should be able to fetch BlueConic's discovery endpoints using a freshly exchanged access token.
Create Entra groups with names that exactly match the BlueConic roles and domains they should assign. For example, if your BlueConic roles are Marketeer and Administrator, create Entra groups named Marketeer and Administrator. If your BlueConic domains are US-site and EU-site, create Entra groups named Domain: US-site and Domain: EU-site. The name match (case and whitespace included) is what links the Entra group to the BlueConic role or domain.
Under Users and Groups in the Enterprise Application, assign the Entra groups you just created. Only assigned groups are in scope for provisioning.
Under Provisioning > Mappings, open Provision Azure Active Directory Groups. By default, displayName maps to displayName. When a provisioning cycle runs, Entra ID calls GET /Groups?filter=displayName eq "..." for each assigned group to check whether it already exists in BlueConic before deciding to create or update.
Under Provisioning > Mappings > Provision Azure Active Directory Groups, remove the externalId attribute from the mapping list. Keep only the two mappings BlueConic needs for group membership updates: displayName → displayName, members → members
6. Use Provision on demand to test a specific user or group immediately without waiting for the scheduled cycle.
Note:
|
Okta
Okta offers the most explicit SCIM import-and-map flow of the supported IdPs.
In the Okta Admin Console, navigate to Applications > Applications > Create App Integration, choose SCIM 2.0 as the sign-on method, and enter the BlueConic SCIM base URL. After the app is created, open it and go to Provisioning > Integration > Edit, set Authentication Mode to OAuth 2.0, and enter the Token URL, Client ID, Client Secret, and Scope (USERS) from the BlueConic OAuth Application you created in Step 3 of the setup.
Enable the supported provisioning actions: Push New Users, Push Profile Updates, Push Groups, Deactivate Users.
Open the app's Import tab and click Import Now. Okta calls GET /Groups and GET /Users on BlueConic. Both your BlueConic roles and your BlueConic domains appear in the import review screen as separate groups. Confirm each imported BlueConic role and domain, then link it to an Okta group. Users are assigned to Okta groups, and Okta synchronizes those memberships to the linked BlueConic roles and domains. Users cannot be assigned directly to the imported BlueConic groups.
Open the Push Groups tab. Select the Okta groups you want to push to BlueConic. Okta links each pushed group to the corresponding BlueConic role or domain discovered during import — automatically if displayName matches, otherwise you pick manually.
From this point on, adding or removing a user from an Okta group triggers a SCIM PUT /Groups/{id} to BlueConic that replaces the full membership of the role or domain group. BlueConic handles PUT as a full-replace operation, which Okta uses by default (not PATCH).
Note: Okta does not offer a Delete Users provisioning action; Okta's deprovisioning is always Deactivate Users. The user becomes inactive in BlueConic but the record is retained. Use Deactivate Users for offboarding; permanent removal of an Okta-deactivated user from BlueConic is not possible from Okta.
|
OneLogin
OneLogin models application roles and domains as Entitlements and uses Rules to map OneLogin attributes to those entitlements.
In the OneLogin Admin Portal, go to Applications > Add App and search for a SCIM 2.0 template, or create a custom connector.
In the Configuration tab, enter the BlueConic SCIM base URL and the OAuth 2.0 client-credentials settings (Client ID and Client Secret) from the BlueConic OAuth Application you created in Step 3 of the setup, along with the Token URL if OneLogin's connector requires it as a separate field.
In the Provisioning tab, enable create, update, deactivate, and delete actions. OneLogin does support sending a SCIM DELETE when a user is removed from the app, so enabling delete here allows you to choose between deactivation (active = false) and permanent removal as your offboarding path.
OneLogin calls GET /Groups on BlueConic. Both BlueConic roles and BlueConic domains are surfaced as Entitlements in the app. Open the Entitlements (or Parameters) tab to see them.
In the Rules tab, create rules that map OneLogin conditions to BlueConic entitlements — for example, user's OneLogin role equals Marketing Team → assign Marketeer role + assign US-site domain. Rules are evaluated at provisioning time and can assign multiple entitlements per user.
SCIM capabilities in BlueConic
This section describes what BlueConic's SCIM 2.0 API exposes to your IdP.
Users
Create users. Adding a user to the BlueConic application in your IdP creates a corresponding BlueConic user account.
Update users. Changes to a user's first name, last name, email, or other supported profile attributes in the IdP propagate to BlueConic on the next sync.
Deactivate users. Setting active = false on a user deactivates them in BlueConic. They can no longer log in, but their record and audit history are preserved. Setting active = true reactivates them.
Delete users. When BlueConic receives a SCIM DELETE /Users request, the user record is permanently removed. Whether your IdP sends DELETE requests depends on the IdP and its configuration. Okta deprovisions users by setting active = false and does not send DELETE requests. Microsoft Entra ID typically deprovisions users through active = false but may send a SCIM DELETE when a user is permanently removed. OneLogin can be configured to send DELETE requests.
Read users. The IdP can list and query the BlueConic users it has provisioned.
Note: Most IdPs deprovision users by sending active = false, which BlueConic treats as a deactivation. Some IdPs may additionally send SCIM DELETE requests when a user is permanently removed. BlueConic supports both deactivation and deletion.
Because roles and domains are both managed through the /Groups mechanism, a user's full BlueConic access — which role they have and which domains they can act on — is fully manageable from the IdP. An admin in your IdP can scope a user to any role and domain simply by adding them to the corresponding IdP groups.
Roles
BlueConic roles are exposed through the SCIM /Groups endpoint. Each BlueConic role appears as a SCIM Group entry that your IdP can discover and map to one of its own groups. No new permission primitives are created; the IdP assigns your existing BlueConic roles.
Read roles. Your IdP fetches the list of BlueConic roles via GET /Groups during setup, so the IdP administrator can map IdP groups to the roles that already exist in BlueConic.
Assign and remove roles. Adding a user to a role-mapped IdP group assigns the corresponding BlueConic role to that user. Removing them from the group removes the role.
Multiple roles per user. A user can hold one or more BlueConic roles at a time by adding them to multiple role-mapped IdP groups.
Domains
BlueConic domains are also exposed through the SCIM /Groups endpoint, alongside roles. Each domain appears as a separate SCIM Group entry, distinguishable from role entries, so the IdP administrator can map IdP groups to domains independently of how they map roles.
Read domains. Your IdP fetches the list of BlueConic domains via GET /Groups during setup, in the same call that returns roles. Roles and domain entries are distinguishable by name or type.
Assign and remove domains. Adding a user to a domain-mapped IdP group assigns the corresponding BlueConic domain to that user. Removing them from the group removes the domain.
Multiple domains per user. A user can be granted access to as many domains as needed. Users must have at least one domain or the 'All domains' group assigned.
Other capabilities
Discovery endpoints. BlueConic exposes the standard SCIM ServiceProviderConfig, ResourceTypes, and Schemas endpoints so your IdP can auto-detect what is supported.
OAuth 2.0 client-credentials authentication. Every SCIM call from your IdP is authenticated with a short-lived OAuth 2.0 access token exchanged against BlueConic's token endpoint using a dedicated OAuth application (client ID and client secret). The application's scope (USERS) and run-as user determine which SCIM operations are allowed and who appears as the audit actor.
Unsupported SCIM features
The following capabilities are not supported by BlueConic’s SCIM implementation.
Managing roles or domains from your IdP: Your IdP cannot create, rename, or delete BlueConic roles or domains. These must first be created in BlueConic and can then be mapped to IdP groups.
Bulk migration of existing users: BlueConic does not support automatic bulk migration of existing users when SCIM is enabled. Existing users are linked individually during their first successful SCIM sync.
How SCIM-provisioned users behave in BlueConic
Read-only profile, roles, and domains
After a user is provisioned by SCIM, their account is marked as provisioned and becomes read-only in Access Management > Users. Administrators can view which roles and domains the user has, but cannot change profile fields, role assignments, domain assignments, or active status. All changes must come from the IdP.
Note: Internally, BlueConic tags these users with a generic provisioned flag rather than something SCIM-specific. This is deliberate — it leaves the door open for other provisioning mechanisms in the future without changing the data model.
Non-SCIM users
Users who were not provisioned by SCIM remain fully editable in BlueConic. This includes BlueConic users created manually before SCIM was enabled (and never subsequently provisioned by the IdP), and on-demand and system users (for example, the BlueConic Support user). You can run a mixed environment where some users are SCIM-managed and others are managed manually.
Takeover: provisioning an existing user
If your IdP provisions a user whose email already exists in BlueConic, BlueConic treats this as a takeover:
The existing user is marked as provisioned and becomes read-only.
Their existing role memberships, domain memberships, 'access to all domains' flag, and 'force password change on first login' flag are cleared. The IdP re-populates roles and domains by sending separate SCIM /Groups membership calls, one per IdP group the user belongs to.
Personal preferences (name, phone, locale, dashboards, favorites, saved searches) are preserved and are not part of what SCIM manages.
Important: Takeover clears all existing role and domain memberships before the IdP rebuilds them from group mappings. Fully configure your IdP-to-BlueConic role and domain mappings before enabling provisioning. If a role or domain mapping is missing on the IdP side, it will be cleared from every affected user on the first sync. The same applies to domains. There is no automatic migration of pre-existing role or domain assignments.
User attribute mapping
BlueConic identifies SCIM users by email (userName). Display names are profile information only and are not used to match users.
SCIM attribute | Maps to | Required | Create (POST) | Update (PUT/PATCH) | Notes |
userName | BlueConic user ID (email) | Yes | Set | Change allowed (replace) | Must be a valid email. Normalized to lowercase. |
id | SCIM resource ID | No | — | — | Read-only. Returned by BlueConic. Derived from email. |
active | Account active/inactive | No | Set | replace | Defaults to true if omitted on create. |
name.formatted | Display name | No | Set | replace | Defaults to userName if omitted. BlueConic reads name.formatted when provided; otherwise composes from name.givenName and name.familyName. |
externalId | IdP correlation ID | No | Set | Set once (ignored in PATCH) | Recommended for IdPs that may change email addresses. BlueConic treats externalId as immutable. If included in a PATCH request, the value is ignored rather than rejected. |
Additional notes on attribute behavior:
User identity is determined by userName (email), not by display name.
On Create, BlueConic matches existing users by userName.
On Update or Delete, BlueConic matches by SCIM id or userName.
Email changes: send a SCIM PUT with a new userName. BlueConic renames the same user and roles and preferences are preserved. Email cannot be changed via PATCH.
PATCH replace operations support active, userName, name.formatted, name.givenName, and name.familyName. BlueConic tolerates externalId in PATCH requests but ignores changes to its value.
Troubleshooting
HTTP Status Codes
Code | Meaning in BlueConic SCIM | What to do |
400 invalidSyntax: Invalid JSON body | The request body is missing, empty, or not parseable JSON. | Re-check the IdP's SCIM app configuration. This is typically a misconfigured custom connector; the standard Okta, Entra, and OneLogin connectors do not produce this. |
400 invalidSyntax: Invalid PATCH value | A PATCH payload contained a value BlueConic could not deserialize. | Inspect the IdP's outgoing PATCH payload (visible in most IdP provisioning logs) and verify the value types match the SCIM 2.0 spec for the targeted attribute. |
400 invalidValue: userName must be a valid email | The IdP sent a user without a userName, or with a value that is not a valid email. | In your IdP's user attribute mappings, ensure userName is mapped to the user's primary email and populated for every user in scope. |
400 invalidValue: User could not be created | BlueConic rejected the user during creation — typically because the email collides with an existing on-demand or system user, or because a tenant-side validation failed. | Confirm no BlueConic system user or on-demand user already has this email. If the conflict isn't obvious, contact BlueConic Support with the SCIM payload and tenant name. |
400 invalidValue: PATCH operation invalid | The PATCH request did not contain operations BlueConic accepts — typically because the IdP's PATCH payload was customized (no supported PATCH operations, no membership op, no supported attributes, or unsupported op). | Use the IdP's default mapping. For Okta, this means letting Push Groups build the PATCH body rather than overriding attribute mappings. |
400 invalidPath: Unsupported PATCH path: externalId | Entra sent externalId in a group PATCH. BlueConic does not use externalId for groups, because groups represent existing BlueConic roles and domains. | In the Entra application, go to Provisioning > Mappings > Provision Azure Active Directory Groups and remove the externalId → externalId attribute mapping. Keep only displayName → displayName and members → members. Re-sync. |
400 mutability: Cannot create / rename / delete groups | The IdP tried to create, rename, or delete a SCIM group. BlueConic groups represent existing BlueConic roles and domains and cannot be managed from the IdP. | Create the role or domain in BlueConic first, then map the IdP group to the BlueConic group the IdP discovered via GET /Groups. For Okta, also uncheck "Rename groups in target app when name changes" on each pushed group. |
400 mutability: Updates / PATCH / Deleting not allowed | The IdP tried to update or delete a user that is not SCIM-provisioned (for example, a manually created BlueConic user or a system user). | SCIM only manages users it has provisioned. Either provision the user via the IdP first (so BlueConic recognises them as SCIM-managed), or make the change directly in BlueConic. |
400 mutability: externalId cannot be changed | A PUT /Users/{id} request attempted to change the user's externalId. BlueConic treats externalId as the immutable link back to the IdP's identity record. | If you are migrating between IdPs or consolidating IdP tenants, do not try to remap users in place. Instead, delete the SCIM-provisioned users from the old IdP and re-provision them from the new one (which creates a new externalId mapping). |
400 invalidValue: Unknown member | A group membership update references a user that is not SCIM-provisioned. | Ensure the user is created and provisioned via SCIM before they are added to a role- or domain-mapped IdP group. Most IdPs sequence this automatically; if not, trigger a user sync first, then a group sync. |
401 Unauthorized | The OAuth access token is missing, expired, invalid, or rejected. | In your IdP's BlueConic SCIM app, re-enter the Client ID, Client Secret, and Token URL from the BlueConic OAuth Application. If the secret has been rotated in BlueConic, generate a new one and update the IdP. |
409 uniqueness | The user the IdP is trying to create or rename already exists in BlueConic, either under the same userName or via the same externalId | Make sure the idp is retrieving existing users before provisioning. The idp should recognize that this user already exists, and not try to create it as if it was new. |
FAQ
Can I edit a SCIM-provisioned user's email, name, roles, or domains in BlueConic?
No. Once provisioned by SCIM, identity and access fields (email, name, roles, domains) are read-only for administrators. Change them in your IdP and let them propagate.Personal account settings such as mobile number and locale are not synced from the IdP. BlueConic does not accept those attributes over SCIM. The user edits these on their own account page, and the values persist across syncs.
Are SCIM groups the same as BlueConic groups?
No. In SCIM, groups represent BlueConic roles and domains that are exposed through the /Groups endpoint for provisioning purposes.BlueConic also contains other group concepts, such as profile groups, which may appear in audit logs, activity streams, or elsewhere in the product. These are unrelated to SCIM provisioning.When reviewing audit events, references to SCIM groups correspond to role and domain assignments, not profile group membership.
What happens to a SCIM user if I turn provisioning off in the IdP?
The user remains in BlueConic in their last-synced state but is no longer kept in sync with the IdP. They remain read-only in BlueConic.
What is the difference between deactivating and deleting a user via SCIM?
Deactivating a user (setting active = false) makes them unable to log in, but their record and audit history remain in BlueConic. They can be reactivated later. Deleting a user (a SCIM DELETE /Users call) is a hard delete — the user record is removed permanently. For ordinary offboarding, deactivation is the safer choice; reserve deletion for cases where you intend a permanent removal.
Should I provision BlueConic support users through my IdP?
In most cases, no. Users with @blueconic.com email addresses are typically used for BlueConic support access and are often not managed in a customer's identity provider. Provisioning these users through SCIM generally provides no benefit. Technically, however, BlueConic does not prevent these users from being provisioned. If they are provisioned through SCIM, the same takeover and management rules apply as for any other SCIM-managed user.Note that certain behaviors associated with BlueConic support accounts, such as password-based login support and other platform-specific handling, are independent of SCIM provisioning.
Can I create BlueConic roles or domains from my IdP?
No, Roles and domains must be created in BlueConic before they can be used for SCIM provisioning. Once created, your IdP can discover them through the /Groups endpoint and map them to IdP groups.
What happens if a user's email address changes in the IdP?
BlueConic uses email as the unique identifier for users, while most IdPs use a separate internal user ID that BlueConic stores as externalId.When a user's email address changes in the IdP, BlueConic recreates the user with the new email address while preserving the same externalId, roles, domains, and personal settings. From the IdP's perspective, the user remains the same user and only the email address changes.Internally, BlueConic records this as a user deletion followed by a user creation. As a result, the audit log shows an OBJECT_DELETE and OBJECT_CREATE event, and any active session under the old email address is invalidated, requiring the user to sign in again with the new email address.
Is SCIM communication between my IdP and BlueConic secure?
BlueConic secures all SCIM provisioning traffic with HTTPS and OAuth 2.0 client-credentials authentication.For a secure setup, we recommend using a dedicated OAuth application for SCIM, granting only the required provisioning scope, assigning a run-as user with the necessary user-management permissions, and keeping the client ID and client secret protected according to your organization’s security policies.SCIM is limited to managing user accounts, role assignments, and domain assignments. It does not provide access to customer data stored in BlueConic.