Creating and Configuring a SCIM 2.0 Entity Push System of Record

SCIM 2.0 Entity Push Systems of Record enable real-time entity synchronization by exposing a SCIM 2.0 compliant API endpoint that external systems can use to push User, Group, and Group Member entities directly to SGNL. This integration allows external systems to maintain real-time synchronization with SGNL’s graph, ensuring that access control decisions are based on the most current entity data.

SCIM 2.0 Entity Push accepts real-time entity updates through standardized SCIM 2.0 API calls. This makes it ideal for identity providers, HR systems, and other applications that need to maintain immediate synchronization with SGNL’s access control decisions.

SCIM 2.0 Entity Push is particularly valuable for organizations that require real-time identity synchronization and want to leverage the standardized SCIM 2.0 protocol for entity management. When user accounts, group memberships, or organizational changes occur in source systems, they can be pushed to SGNL to update the graph and trigger downstream access control decisions.

Prerequisites

Understanding of SCIM 2.0 protocol and entity structure
Systems capable of making SCIM 2.0 compliant API calls, such as Okta or Entra ID
Administrative access to configure SCIM 2.0 Entity Push Systems of Record in SGNL
Understanding of User, Group, and Group Member entity relationships

Understanding SCIM 2.0 Entity Push Architecture

SCIM 2.0 Entity Push Systems of Record operate by exposing a SCIM 2.0 compliant API endpoint that external systems can use to push entity changes. Instead of SGNL periodically requesting data from external systems, external systems actively push entity updates to SGNL when they occur.

Supported Entity Types

SCIM 2.0 Entity Push supports the following entity types as defined by the SCIM 2.0 specification:

User Entities: Individual user accounts with attributes such as username, email, display name, and custom attributes
Group Entities: Collections of users with attributes such as group name, description, and membership information
Group Member Entities: Relationships between users and groups, representing group memberships

SCIM 2.0 API Operations

The exposed endpoint supports standard SCIM 2.0 operations:

POST /Users: Create new user entities
PUT /Users/{id}: Replace entire user entity
PATCH /Users/{id}: Partial update of user entity
DELETE /Users/{id}: Remove user entity
POST /Groups: Create new group entities
PUT /Groups/{id}: Replace entire group entity
PATCH /Groups/{id}: Partial update of group entity
DELETE /Groups/{id}: Remove group entity
POST /Groups/{id}/members: Add members to a group
DELETE /Groups/{id}/members/{memberId}: Remove members from a group

Authentication and Security

SCIM 2.0 Entity Push Systems of Record support Bearer Token Authentication:

Bearer Token Authentication: SGNL generates authentication tokens that external systems must include in the Authorization header when making SCIM API calls. This method provides secure authentication for entity push operations and is managed through SGNL’s token generation system.

Configuring SGNL

Creating a SCIM 2.0 Entity Push System of Record

Access SGNL Console: Login to the SGNL Console privileges
Navigate to Identity Data Fabric: From the left menu, select “Identity Data Fabric”
Add New System of Record: Click “Add System of Record” or “Add” to open the SoR catalog
Select SCIM 2.0 Push: Choose “SCIM 2.0 Push” from the available System of Record types

System Configuration

After selecting SCIM 2.0 Push, configure the system-level settings:

Display Name: Enter a descriptive name for your SCIM 2.0 Entity Push System of Record

Description: Provide a description explaining the purpose and scope of this SCIM 2.0 Entity Push integration

Hostname: Enter sgnl.ai

Authentication Configuration: Configure authentication credentials if your Entity Push implementation requires specific authentication beyond the push endpoint security.

Endpoint Configuration

Save Configuration: Click “Continue” to save your SCIM 2.0 Entity Push System of Record configuration
Obtain SCIM Endpoint: SGNL will provide a specific SCIM 2.0 compliant endpoint URL where external systems should deliver entity updates. The endpoint follows the format:
```
https://{clientName}.sgnlapis.cloud/scim/v2/{systemOfRecordId}
```
Generate Authentication Token: Generate a new authentication token from the system settings for bearer token authentication

Testing SCIM 2.0 Entity Push Integration

Creating Test Entities

Using HTTP Tools

Prepare Test Request: Use a tool like Postman or curl to send SCIM 2.0 requests to your endpoint
Configure Headers: Set the following headers:
- Content-Type: application/scim+json
- Authorization: Bearer {authenticationToken}

Send Entity Creation: POST a SCIM 2.0 User entity to your endpoint:

curl -X POST \
  https://{clientName}.sgnlapis.cloud/scim/v2/{systemOfRecordId}/Users \
  -H 'Content-Type: application/scim+json' \
  -H 'Authorization: Bearer {authenticationToken}' \
  -d '{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
    "userName": "[email protected]",
    "name": {
      "givenName": "Test",
      "familyName": "User"
    },
    "displayName": "Test User",
    "emails": [
      {
        "value": "[email protected]",
        "type": "work",
        "primary": true
      }
    ],
    "active": true
  }'

Verify Response: A successful request should return a 201 Created response with the created entity, including the assigned SGNL ID

Integrating a Okta SCIM 2.0 App with SGNL

Okta provides robust SCIM 2.0 support that can be used to with your SCIM 2.0 Entity Push System of Record. This section covers how to configure Okta to push user and group data to your SGNL SCIM endpoint.

Prerequisites for Okta

Okta administrator access
Okta Developer Console access (for API token generation)
SGNL SCIM 2.0 Entity Push System of Record configured and active
SGNL authentication token for the SCIM endpoint

Configuring Okta SCIM App Integration

Create SCIM App in Okta:
- Login to your Okta Admin Console
- Navigate to Applications → Applications
- Click Create App Integration
- Select SWA
- Fill in the required information
- Click Finish
Configure SCIM App Settings:
- Go into General settings, click Edit, and enabled SCIM in the Provisioning section
- Click Save
- After saving, a Provisioning Tab will be available, click Provisioning
- Click Edit
- SCIM connector base URL: Enter your SGNL SCIM 2.0 endpoint URL. This can be found on the Settings tab of your SCIM 2.0 Push System of Record, under Delivery Method:
```
https://{clientName}.sgnlapis.cloud/scim/v2/{systemOfRecordId}
```
- Unique identifier field for users: Select userName or id
- Supported provisioning actions: Select the actions you want to test:
  - Push Users
  - Push Group
  - Push Profile Updates
Configure Authentication:
- Authentication Mode: Select “HTTP Token”
- HTTP Bearer Token: Enter your SGNL authentication token
- Test API Connection: Click “Test API Connection” to verify connectivity
Enable Provisioning
- If not selected, click the Provisioning tab
- Click Edit
- Select:
  - Create Users
  - Update User Attributes
  - Deactivate Users
Configure Attribute Mapping:
- User Attribute Mappings: Map Okta user attributes to SCIM 2.0 attributes:
  - userName → userName
  - firstName → name.givenName
  - lastName → name.familyName
  - email → emails[0].value
  - login → userName

Testing User Provisioning

Assign Users to the SCIM App:
- Navigate to your SCIM app in Okta
- Go to Assignments tab
- Click Assign → Assign to People
- Select users to assign to the SCIM app
- Click Assign and Save
Verify in SGNL:
- Use DataLens to query for the provisioned users
- Check that user attributes are correctly mapped and synchronized
- Verify that user status changes (active/inactive) are reflected

Entity Processing Logs

SCIM 2.0 Entity Push provides comprehensive entity logging through Logs → Systems of Record in the SGNL console

Using DataLens for Verification

Use DataLens to explore your SCIM 2.0 Entity Push data:

Query Recent Entities: Search for recently created or updated entities to verify that SCIM operations are being processed correctly
Validate Entity Attributes: Confirm that entity attributes are being correctly synchronized from SCIM payloads
Verify Entity Relationships: Check that group memberships and other relationships are being created properly
Test Entity Operations: Confirm that entities can be queried and used in policies as expected

Troubleshooting

Entity Delivery Issues

Entities Not Received: If SGNL is not receiving entity updates, verify that external systems are configured with the correct SGNL SCIM endpoint URL and that network connectivity exists. Check firewall rules, proxy configurations, and DNS resolution between external systems and SGNL endpoints.

Authentication Failures: If entity operations are being rejected due to authentication errors, verify that bearer tokens are valid and properly included in the Authorization header.

Entity Format Errors: If entity operations are being rejected due to format issues, verify that external systems are generating properly formatted SCIM 2.0 payloads. Check that required fields and schemas are present and correctly formatted.

Schema Validation: Ensure that all SCIM 2.0 requests include the appropriate schema URIs and follow the SCIM 2.0 specification for entity structure.

Integration with SGNL Policies

Once your SCIM 2.0 Entity Push integration is successfully configured and receiving entity updates, you can leverage real-time entity data in dynamic SGNL policies that respond immediately to organizational changes.

Real-Time User Management: Use SCIM 2.0 Entity Push to create policies that immediately respond to user account changes such as new hires, departures, or role modifications that affect access decisions.

Dynamic Group-Based Access Control: Leverage group membership changes from SCIM 2.0 Entity Push to create policies that adjust access based on real-time organizational changes, ensuring that access changes take effect immediately when group memberships are updated.

Cross-System Coordination: Use SCIM 2.0 Entity Push to coordinate access changes across multiple systems in real-time. When entity changes occur in one system, SCIM 2.0 Entity Push can immediately update the SGNL graph, triggering actions in related systems and changing the outcome of policy decisions.

Action Triggering: Use SCIM 2.0 Entity Push events to trigger SGNL Actions that can propagate access changes to downstream systems, creating a comprehensive real-time access orchestration workflow.

For comprehensive guidance on creating policies with SCIM 2.0 Entity Push data, refer to the SGNL Policy Management documentation. For advanced entity modeling and relationship configuration, review the Entities and Relationships guide.

Systems of Record Templates - Comprehensive guide to SoR template structure and customization
SCIM 2.0 Specification - Official SCIM 2.0 protocol specification
DataLens - Exploring and validating your SCIM 2.0 Entity Push data
Policy Management - Creating dynamic access policies using SCIM 2.0 Entity Push data
CAEP Hub Actions - Triggering downstream actions from SCIM 2.0 Entity Push events