Building Custom midPoint Connectors for REST APIs: A Practical Guide

Most enterprises have at least one system that does not have a pre-built midPoint connector. REST APIs are the most common integration target for custom connector development. This guide explains how midPoint connectors work and what to consider when building one for a REST API.

Understanding the ConnId Framework

midPoint does not communicate with target systems directly. Instead, it uses the ConnId connector framework (originally developed as part of the Sun Identity Manager project, later adopted by the open-source community). ConnId provides a standardized Java API that all connectors implement.

This means every connector, whether it targets Active Directory, a database, or a REST API, follows the same interface contract: Create, Read, Update, Delete, and Search operations on accounts and groups.

When Do You Need a Custom Connector?

You need a custom connector when:

• Your target system exposes a REST API but has no pre-built ConnId connector
• The existing generic REST connector does not support your API’s authentication or pagination model
• You need complex transformation logic between midPoint schema and the API’s data model
• Your system uses a proprietary protocol that the generic connectors cannot handle

Common examples: custom HR systems, homegrown CRM platforms, SaaS applications without SCIM support, legacy billing systems with REST facades.

Connector Architecture for REST APIs

A REST API connector typically consists of:

• Configuration class: Defines connection parameters (base URL, authentication credentials, timeout values)
• Connection management: Handles HTTP client setup, OAuth token refresh, or API key injection
• Schema discovery: Maps the API’s data model to ConnId’s account and group object classes
• CRUD operations: Implements Create (POST), Read (GET), Update (PUT/PATCH), and Delete (DELETE) against the API endpoints
• Search/filter translation: Converts ConnId filter queries into API query parameters or OData filters
• Pagination handling: Manages cursor-based, offset-based, or link-based pagination for large result sets

Authentication Patterns

REST APIs use various authentication methods. Your connector must handle:

• API key: Static key passed as header or query parameter
• Basic auth: Username/password encoded in the Authorization header
• OAuth 2.0 client credentials: Token acquisition and automatic refresh before expiry
• OAuth 2.0 authorization code: For APIs requiring user-delegated access (less common for backend integration)
• Certificate-based (mTLS): Mutual TLS for high-security environments

Error Handling and Resilience

Production connectors must handle real-world API behavior:

• Rate limiting: Respect HTTP 429 responses with exponential backoff
• Transient failures: Retry on 5xx errors and network timeouts
• Partial failures: Handle batch operations where some items succeed and others fail
• Schema changes: Gracefully handle unexpected fields or missing required fields
• Logging: Comprehensive logging at appropriate levels for debugging without exposing sensitive data

Testing Your Connector

Before deploying to production:

• Unit test each operation against mock API responses
• Integration test against a sandbox/staging instance of the target system
• Load test with realistic identity volumes to verify pagination and performance
• Test error scenarios: API downtime, expired credentials, rate limiting
• Validate schema mapping with midPoint’s resource definition

Deployment and Maintenance

Once built, the connector JAR is deployed to midPoint’s connector directory. Version the connector alongside your midPoint configuration in Git. Plan for ongoing maintenance:

• API version upgrades may require connector updates
• New attributes or operations may need schema extensions
• Authentication method changes (e.g., API key to OAuth) require connector reconfiguration

Let Us Build It For You

WeKnowIdentity has built custom midPoint connectors for REST APIs, SOAP services, databases, CSV feeds, and proprietary platforms. Every connector is built to ConnId standards, fully tested, and documented. Contact us to discuss your integration requirements.

Related Resources

• Custom Connector Development services
• midPoint consulting and implementation
• See our connector work in action