Why provision principals from Okta
Gateco authorizes every AI retrieval against your identity data. When Okta is the system of record, SCIM provisioning keeps the principal directory in Gateco current automatically: joiners appear, leavers deactivate, and group changes propagate without manual syncs.
Supported features
This integration is push based: Okta is the system of record and sends changes to Gateco. Gateco does not push data back to Okta.
- Push New Users (Create): supported. Assigning a user to the Gateco app in Okta creates or links the matching principal in Gateco.
- Push Profile Updates (Update): supported. Profile changes in Okta update the principal in Gateco.
- Push User Deactivation (Deactivate): supported. Unassigning or deactivating a user in Okta sets the principal to inactive (soft, not deleted); re-assigning reactivates the same principal.
- Push Groups: supported. Pushed Okta groups appear in Gateco so policies can reference them by name.
- Import New Users and Import Profile Updates (from Gateco to Okta): not supported. Gateco is a provisioning destination, not a source of record for Okta.
Gateco reads these SCIM user attributes: userName, name.givenName, name.familyName, displayName, emails, externalId, active, and groups. Any other Okta profile attributes are ignored, so remove them from the app profile (Provisioning, To App, Attribute Mappings) to keep the mapping clean.
Step 1: Create a SCIM-only Okta identity provider
In the Gateco dashboard, open Identity Providers and click Connect Provider. Choose Okta as the type and check "Provisioning only (SCIM)". This mode needs no Okta API token because Okta pushes changes to Gateco.
Step 2: Generate the SCIM bearer token
Open the identity provider you just created and find the SCIM Configuration panel. Click Generate Token and copy the value immediately.
The token is shown exactly once. Store it in a password manager. Generating a new token revokes the previous one immediately.
Step 3: Configure the Okta app
- In the Okta Admin Console, add the Gateco integration from the OIN catalog (or, before the catalog listing is live, a generic SCIM 2.0 test app).
- Open the Provisioning tab, click Configure API Integration, and check Enable API integration.
- If you added Gateco from the OIN catalog, the SCIM base URL and Bearer authentication are already built in, so you only paste the token. For a generic SCIM 2.0 test app, set the SCIM connector base URL to https://api.gateco.ai/api/scim/v2 and choose HTTP Header (Bearer) authentication.
- In the API Token field, paste the token value from Step 2. Paste the raw token only: Okta adds the "Bearer " prefix itself, so do not type it in the field.
- Click Test API Credentials (it should succeed), then Save.
- Under Provisioning To App, enable Create Users, Update User Attributes, and Deactivate Users.
Gateco uses an email address as the SCIM userName. On the Okta app Sign On tab, set Application username format to Email so the userName Okta sends matches each user email.
Step 4: Assign users and push groups
Use the Assignments tab to assign individual users or groups. Use Push Groups to mirror Okta groups into Gateco so your policies can reference them by name.
Where pushed users and groups appear in Gateco
The Directory (Connect, then Directory in the sidebar) is the user directory for everything Okta provisions into your organization.
- Users tab: every provisioned user with name, email, source identity provider, status, group memberships, and last seen. The status filter defaults to All statuses, so users deactivated in Okta stay visible with a Deactivated badge instead of disappearing.
- Groups tab: every pushed Okta group with its source and a live member count. The count reflects active members only. Click a group to see its members on the Users tab.
- User detail: click any user to open a detail view showing the SCIM external ID and provider subject, so you can correlate a Gateco principal with the source record in Okta.
The same data is available programmatically: GET /api/principals lists users (pass status=all to include deactivated ones) and GET /api/groups lists groups. Both are also exposed in the Python and TypeScript SDKs and the MCP server.
Step 5: Verify
- Provisioned users appear on the Directory Users tab with source Okta.
- Pushed groups appear on the Directory Groups tab with the expected member counts.
- Deactivating a test user in Okta flips the user to a Deactivated badge in the Directory, and the group member count drops by one.
- A policy simulation in the Access Simulator resolves the provisioned groups.
Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
Test API Credentials fails with 401 or "invalid authorization header" | Token missing, revoked, pasted with whitespace, or pasted with a "Bearer " prefix (Okta adds that itself) | Paste the raw token value only, with no leading or trailing spaces, or generate a fresh token in Gateco and paste it again |
Test API Credentials fails with 403 | Organization plan below Growth | Upgrade the Gateco organization to Growth or Enterprise |
Users provision but groups are empty | Groups assigned but not pushed | Use Push Groups in the Okta app, not only Assignments |
Duplicate user error in Okta log | A principal with the same external ID already exists | Unassign and re-assign the user in Okta to relink and reactivate the existing principal |
Okta profile attributes do not appear in Gateco | Gateco consumes only userName, name, email, groups, and active; other profile attributes are ignored by design | Expected behavior. Remove the unused attributes from the app profile under Provisioning, To App, Attribute Mappings |
Support
Questions about SCIM provisioning with Gateco? Contact support@gateco.ai.