SCIM provisioning with Okta

SCIM provisioning keeps your SqlDBM users in sync with Okta. Users you assign in Okta are invited to SqlDBM automatically, users you unassign lose access, and Okta groups decide each user's roles.

Before you start

• SSO must already be working. Set it up first with Setup SSO with Okta. SCIM uses the same SAML app.
• The SSO username must be the Okta user ID. In the SqlDBM app, open General → SAML Settings → Edit and set:
  • Name ID format: Unspecified
  • Application username: Custom, with the expression user.getInternalProperty("id"). If the editor only accepts the newer expression language, use user.id.
  • Update application username on: Create and update
• Every user needs a primary email in Okta.
• You need an Okta admin with the Application Administrator or Super Administrator role.
• Decide which Okta groups map to SqlDBM roles (optional; see Groups and roles).

Why the username matters: SqlDBM links the person who signs in with SSO to the person Okta provisions by matching the SSO Name ID to the SCIM externalId. Okta always sends its user ID as the externalId, so the Name ID must be that ID too. It never changes, while emails and usernames can.

Already using SSO with Name ID format EmailAddress or Application username Okta username? Contact SqlDBM support before you change it. Users who have already signed in are linked to their email and need to be moved over.

Step 1: Request SCIM from SqlDBM

1. Go to https://support.sqldbm.com/hc/en-us/requests/new and log in.
2. Open a ticket with:
   • Subject: Enable SCIM
   • IdP Admin Email: your Okta admin's email address
   • Description: the Okta group name for each SqlDBM role you want to manage (Modeler, Governance, Alternative admin, AI), and your credential type. OAuth is the usual choice for Okta. A static token also works; give a lifetime in days (1 to 3650).
3. SqlDBM turns on SCIM and sends you these values securely:

The client secret or token can't be retrieved later. Store it in your password manager. If it's lost, SqlDBM issues a new one.

Step 2: Connect Okta to SqlDBM

In the Okta Admin Console, open the SqlDBM app you created for SSO.

1. On the General tab, click App Settings → Edit, set Provisioning to SCIM, and click Save. A Provisioning tab appears.
2. Go to Provisioning → Integration → Edit and set:
   • SCIM connector base URL: the SCIM base URL.
   • Unique identifier field for users: userName.
   • Supported provisioning actions: tick Push New Users, Push Profile Updates and Push Groups. Leave Import off.
   • Authentication Mode for OAuth: OAuth 2, grant type Client Credentials, Token endpoint = OAuth token URL, plus your Client ID and Client secret. Leave the authorization endpoint empty if Okta allows it.
   • Authentication Mode for a static token: HTTP Header, Authorization = Bearer, then your static token.
3. Click Test Connector Configuration. It should detect Create Users, Update User Attributes and Push Groups. Click Save.
4. Go to Provisioning → To App → Edit. Enable Create Users, Update User Attributes and Deactivate Users, then click Save.
5. Under To App → Attribute Mappings, check that the primary email maps to user.email. Okta sends the user ID as externalId automatically, so it isn't listed here.

Step 3: Assign users and push groups

1. On the Assignments tab, assign users directly or by group.
2. On the Push Groups tab, click + Push Groups → Find groups by name.
3. Pick each role group, keep Push group memberships immediately ticked, and click Save. Each group name must match the name you gave SqlDBM exactly.

Forcing a sync

• A group: on the Push Groups tab, click the group's status button, then Push now.
• A user: edit and save their assignment. Unassigning and reassigning also works, but it removes them from SqlDBM first.
• Failed pushes: go to Dashboard → Tasks, then Retry Selected or Retry All.

Groups and roles

Each SqlDBM role is granted through one Okta group, using the name you gave SqlDBM. A role with no group is never granted by SCIM.

• Assigned, in no role group: invited with a Consumer seat and no extra roles.
• Roles add up: a user in both the Modeler and Governance groups gets both. Removing them from a group removes that role at the next push.
• Invite not yet accepted: the invite carries the roles. The user gets them after signing in with SSO and entering a one-time email code.
• Unassigned or deactivated in Okta: the user loses access to your SqlDBM account. Their SqlDBM user and data are kept, and reassigning restores their roles.
• Out of seats: the user waits until a seat is free, then is added automatically.
• Members from before SCIM: they stay members. A Modeler seat granted by hand is kept.
• Your account admin: SCIM never removes the primary account admin.
• Group names must match exactly. Once linked, renaming the group in Okta doesn't break the link. To change which names SqlDBM expects, contact support; this resets the connection and issues new credentials.

While SCIM is on, Add user and the revoke buttons are hidden in the SqlDBM admin console. Make all membership changes in Okta.

Okta note: the "External ID" column on Okta's assignment screens is the ID SqlDBM returned to Okta, not the value Okta sends to SqlDBM.

Verify and troubleshoot

Run these checks with one test user. Allow about a minute after each push.

• Connection: Test Connector Configuration succeeds.
• One user, no role group: after you assign them, the user appears in SqlDBM as a Consumer invite or member.
• Role group: add the user to the Modeler group and push it. The user now shows Modeler.
• Accept the invite: the user signs in with SSO and lands in your account with the right roles.
• Remove a role: take the user out of the group. The role is removed at the next push.
• Confirm with support: reply to your ticket so SqlDBM can confirm each role group is linked and no users failed.

New credentials and turning SCIM off

New credentials: open a support ticket to rotate. You get a new client secret with the same client ID, or a new static token. The old one stops working immediately, so update Okta right away and run Test Connector Configuration again.

Turning SCIM off: open a support ticket, then turn off provisioning in the Okta app.

• Existing members keep their memberships and roles.
• Add user returns to the SqlDBM admin console.
• Turning SCIM back on starts fresh, with new credentials and role group names.

SSO can't be changed or turned off while SCIM is on.