Implementing SCIM with ThingWorx and Azure AD: A Comprehensive Guide

User provisioning and identity management across multiple platforms can be a complex challenge for organizations. This blog post provides a detailed walkthrough for integrating ThingWorx Platform with Azure Active Directory using the System for Cross-domain Identity Management (SCIM) protocol. This setup enables automated user and group provisioning from Azure AD to ThingWorx, streamlining identity management and enhancing security.

What is SCIM?

The System for Cross-domain Identity Management (SCIM) is an open standard designed to simplify user identity management across multiple systems. SCIM enables the automatic provisioning and de-provisioning of user accounts across applications, reducing administrative overhead and security risks.

Architecture Overview

Implementation Process Overview

The integration process consists of three major components:

1. Configuring the SCIM subsystem in ThingWorx
2. Setting up ThingWorx platform for Azure AD integration
3. Configuring Azure AD as a SCIM client

Let’s walk through each of these steps in detail.

Part 1: Configuring the SCIM Subsystem in ThingWorx

ThingWorx’s SCIM subsystem provides the endpoints and processing mechanisms needed to support the SCIM protocol. Here’s how to configure it:

Step 1: Enable the SCIM Subsystem

1. Log in to ThingWorx Composer with administrator privileges
2. Navigate to the “System” menu
3. Select “Subsystems” from the dropdown
4. Locate the “SCIMSubsystem” in the list
5. If the subsystem is not enabled, click the “Enable” button
6. Configure the following parameters:
   • AuthenticationScheme: Set to “Bearer” for Azure AD
   • BearerToken: Generate a strong, unique token to authenticate requests from Azure AD
   • MaxResults: Set the maximum number of entities to return in a response (default: 200)
   • EnableDetailedLogging: Set to “true” for initial setup and troubleshooting

Step 2: Set Up User Creation Security

To ensure that user management is properly handled through SCIM:

1. Navigate to “Security” > “Directory Services”
2. Select the “SSOAuthenticator” service
3. Disable “Allow User Creation” and “Allow User Modification” options
4. Click “Save” to apply changes

This configuration ensures that all user management is handled exclusively through the SCIM protocol, preventing inconsistencies between systems.

Part 2: Configuring ThingWorx Platform Settings for Azure AD

Step 1: Create SCIM Bearer Token

1. Generate a strong, secure token (minimum 32 characters recommended)
2. This token will authenticate Azure AD’s requests to ThingWorx
3. Save this token securely as it will be needed in Azure AD configuration

Step 2: Map Azure AD and ThingWorx User Properties

For proper user provisioning, map the user attributes between systems:

Step 3: Understand ThingWorx SCIM Endpoints

The following endpoints will be used in Azure AD configuration:

• Base URL: https://[your-thingworx-server]/Thingworx/SCIM
• Users endpoint: https://[your-thingworx-server]/Thingworx/SCIM/Users
• Groups endpoint: https://[your-thingworx-server]/Thingworx/SCIM/Groups

Part 3: Configuring SCIM in Azure AD Portal

Step 1: Add Enterprise Application

1. Log in to the Azure portal
2. Navigate to “Azure Active Directory” > “Enterprise applications”
3. Click “New application”
4. Select “Create your own application”
5. Enter a name (e.g., “ThingWorx Platform”)
6. Select “Integrate any other application you don’t find in the gallery (Non-gallery)”
7. Click “Create”

Step 2: Configure Provisioning

1. In the new enterprise application, navigate to “Provisioning”
2. Set “Provisioning Mode” to “Automatic”
3. Under “Admin Credentials”, configure:
   • Tenant URL: Enter the ThingWorx SCIM base URL (https://[your-thingworx-server]/Thingworx/SCIM)
   • Secret Token: Enter the bearer token created in ThingWorx

4. Click “Test Connection” to verify connectivity

4. Upon successful connection, click “Save”

Step 3: Configure Scope and Mappings

1. Under “Settings”, choose what to synchronize:
   • Scope: Select “Sync only assigned users and groups” for controlled provisioning
2. Configure attribute mappings:
   • Navigate to “Mappings” > “Provision Azure Active Directory Users”
   • Verify that Azure AD attributes are correctly mapped to ThingWorx attributes
   • The default mappings should align with the table provided earlier
3. For group provisioning:
   • Navigate to “Mappings” > “Provision Azure Active Directory Groups”
   • Ensure group attributes are correctly mapped
   • Map “displayName” to ThingWorx “displayName”

Step 4: Start Provisioning

1. Navigate back to “Provisioning”
2. Click “Start provisioning”
3. The initial synchronization will begin, which may take several minutes to complete

Verifying the Integration

After configuring both systems, verify that the integration is working correctly:

Step 1: Check Provisioning Logs in Azure AD

1. In Azure AD, navigate to the enterprise application
2. Select “Provisioning” > “Provisioning logs”
3. Review logs for any errors or warnings

Step 2: Verify User Creation in ThingWorx

1. Log in to ThingWorx Composer
2. Navigate to “Security” > “Users”
3. Confirm that Azure AD users have been successfully provisioned
4. Check that user attributes are correctly mapped

Step 3: Test Group Synchronization

1. Create or modify a group in Azure AD
2. Assign users to the group
3. Wait for synchronization to complete (typically within 40 minutes)
4. Verify that the group appears in ThingWorx and has the correct members

Monitoring and Maintenance

To ensure ongoing success with your SCIM integration:

Regular Monitoring

1. Check Azure AD provisioning logs periodically
2. Monitor ThingWorx SCIM subsystem logs for errors
3. Verify that user and group changes in Azure AD are reflected in ThingWorx

Troubleshooting Common Issues

• Connection Failures: Verify the bearer token and endpoint URLs
• Attribute Mapping Issues: Review attribute mappings in Azure AD
• Missing Users/Groups: Check the provisioning scope and assignment status
• Performance Issues: Consider adjusting the MaxResults parameter in the ThingWorx SCIM subsystem

Advanced Configuration

Customizing User and Group Schema

If your organization requires additional attributes to be synchronized:

1. Navigate to the Azure AD enterprise application
2. Select “Provisioning” > “Mappings”
3. Add custom attributes as needed
4. Ensure corresponding properties exist in ThingWorx

Handling Multiple Identity Sources

When ThingWorx connects to multiple identity providers:

1. Implement naming conventions to distinguish users from different sources
2. Consider using scoping filters in Azure AD to control which users are provisioned
3. Regularly audit user accounts to ensure proper synchronization

Security Best Practices

1. Rotate Bearer Tokens: Regularly update the bearer token for enhanced security
2. Use HTTPS: Ensure all SCIM endpoints use HTTPS for secure communication
3. Limit Scope: Only synchronize users and groups that require access to ThingWorx
4. Audit Trail: Maintain logs of all provisioning activities for compliance purposes
5. Role-Based Access: Assign appropriate roles to provisioned users in ThingWorx

Handling Special Cases

Handling User De-provisioning

When a user is disabled or deleted in Azure AD:

1. Azure AD sends a PATCH request to update the user’s status in ThingWorx
2. ThingWorx processes this request and disables the user account
3. For deletions, Azure AD sends a DELETE request to the user’s SCIM endpoint
4. ThingWorx removes or deactivates the user based on your configuration

Group Membership Changes

When group memberships change in Azure AD:

1. Azure AD sends a PATCH request to the Groups endpoint
2. ThingWorx processes the request and updates group memberships
3. Corresponding permissions in ThingWorx are updated accordingly
4. Users gain or lose access based on their group memberships

Disabling User Creation and Modification in ThingWorx SSO Authenticator

To ensure centralized management through SCIM, disable direct user creation and modification:

1. Log in to ThingWorx Composer as an administrator
2. Navigate to “Security” > “Directory Services”
3. Select the “SSOAuthenticator” service
4. Uncheck the “Allow User Creation” checkbox
5. Uncheck the “Allow User Modification” checkbox
6. Click “Save” to apply changes

This ensures that all user management occurs through Azure AD, maintaining a single source of truth for identity management.

SCIM Subsystem Configuration in ThingWorx

The SCIM subsystem in ThingWorx provides the server-side implementation of the SCIM protocol. Here’s a detailed look at its configuration parameters:

The subsystem exposes the following SCIM endpoints:

• /ServiceProviderConfig: Provides info about SCIM capabilities
• /Schemas: Defines the schema for user and group entities
• /ResourceTypes: Defines resource types supported by the server
• /Users: Endpoint for user management operations
• /Groups: Endpoint for group management operations

Common Troubleshooting Issues and Solutions

Conclusion

Implementing SCIM-based user provisioning between Azure AD and ThingWorx provides significant benefits:

• Automated User Management: Eliminates manual user creation and updates
• Single Source of Truth: Azure AD serves as the authoritative identity source
• Enhanced Security: Immediate deprovisioning when users leave the organization
• Reduced Administrative Overhead: Streamlined user lifecycle management
• Improved Compliance: Consistent user management process across systems

By following this comprehensive guide, you’ve established an automated, secure, and efficient user provisioning system between Azure AD and ThingWorx. This integration not only streamlines administrative tasks but also enhances security by ensuring that access management remains consistent across your organization.

Performance Optimization and Scaling

To ensure optimal performance as your organization grows:

Initial Synchronization Optimization

1. Schedule during off-hours
   • Initial sync can be resource-intensive
   • Schedule during periods of low system usage
   • Monitor server performance during synchronization
2. Incremental approach
   • Consider synchronizing users in batches
   • Start with smaller groups before full deployment
   • Validate each batch before proceeding

Ongoing Performance Tuning

1. Sync Cycle Frequency
   • Default: Every 40 minutes
   • Adjust based on your organization’s needs
   • Less frequent cycles reduce server load but increase provisioning delay
2. Logging Levels
   • Use detailed logging during setup and troubleshooting
   • Reduce to standard logging for production to minimize impact
   • Periodically review logs for unexpected errors
3. Resource Allocation
   • Monitor CPU and memory usage during sync cycles
   • Allocate additional resources if performance issues arise
   • Consider database optimization for ThingWorx user entities

Monitoring and Maintenance Best Practices

Regular Health Checks

1. Daily Checks
   • Review provisioning logs for errors
   • Verify recent user provisions completed successfully
   • Check ThingWorx SCIM subsystem status
2. Weekly Checks
   • Full reconciliation between Azure AD and ThingWorx users
   • Group membership verification
   • Performance metrics review
3. Monthly Checks
   • Bearer token rotation
   • Comprehensive audit of user access
   • Review and update documentation as needed

Audit and Compliance

1. Provisioning Reports
   • Generate provisioning reports from Azure AD
   • Document user lifecycle events
   • Maintain these reports for compliance requirements
2. Access Reviews
   • Conduct regular access reviews in Azure AD
   • Validate appropriate ThingWorx access
   • Document review findings and actions taken
3. Security Monitoring
   • Monitor for suspicious provisioning activities
   • Track failed authentication attempts
   • Implement alerts for unexpected changes

Disaster Recovery and Business Continuity

Backup Procedures

1. Configuration Backup
   • Document all SCIM integration settings
   • Export Azure AD enterprise application configuration
   • Backup ThingWorx SCIM subsystem settings
2. User Data Backup
   • Regular backups of ThingWorx user entities
   • Document procedures for rebuilding user access

Recovery Procedures

1. Token Compromise
   • Generate new bearer token in ThingWorx
   • Update token in Azure AD provisioning configuration
   • Verify connectivity after token change
2. Full Resynchronization
   • Document procedure for full user resynchronization
   • Test recovery process periodically
   • Maintain list of key users for priority restoration