ConnID Connector to support System for Cross-domain Identity Management (SCIM2) API for Identify and Access Management (IAM) of Remote Services
This open source connector for the SCIM2 API uses the ConnId Framework for integration with Identity and Access Management (IAM) systems such as Evolveum Midpoint.
The software leverages the Connector Base Framework located at https://github.com/ExclamationLabs/connector-base
This software is Copyright 2024 Exclamation Graphics. Licensed under the Apache License, Version 2.0.
The Scim2 Connector has the following features:
- The connector configuration is specified in the user interface.
- The connector supports Users and Groups.
- A User can be associated with one or more Groups.
- The connector can Create, Update, Delete, and Search Users.
- The connector can Create, Update, Delete, and Search Groups.
- The connector supports automatic pagination for User and Group objects.
- The connector currently supports standard, enterprise, AWS, and Slack.
Note: Dynamic schema support is currently not implemented. It may be implemented in a future release.
The actual method of configuring a connector is largely dependent on the interface(s) provided by your Identity and Access management system. Midpoint provides a convenient user interface method to enter these values. If configuration properties are being read in from a property file, you may also need to know the name of the property.
| Property Name | Required | Description/Notes |
| Service URL | Yes | The base URL of the SCIM2 endpoint. |
| IO Error Retries | No | Number of retries that will be attempted when an IO error occurs. Default is 5. |
| Token | Yes | The token used to authenticate with the SCIM2 endpoint. This is usually a bearer token or an OAuth2 token. The connector will use this token to authenticate all requests to the SCIM2 endpoint. |
| Deep Get Enabled | No | When a search operation is executed and this value is true, the connector will make an individual call to download each User or Group returned. The value should be set to false since a standard SCIM2 service should return all attributes of each record. |
| Deep Import Enabled | No | When an import operation is executed and this value is true the connector will attempt to download all attributes for each individual record returned. The option should be set to false since the SCIM2 connector should return all attributes on the search. |
| Import Batch Size | No | The default number of records to retrieve per page. Import operations will be invoked using the given batch size when it is supplied. Since the SCIM2 API supports paging you can import records one batch/page at a time instead of all at once. |
| Pagination Enabled | No | The SCIM2 Connector supports pagination on User and Group objects. This option should be set to true. |
| Duplicate Record Returns Id | No | When a create is attempted and an AlreadyExistsException is generated, the adapter shall attempt to return the id of the existing record matching the specified userName. |
| Enable Standard Schema | Yes | Uses prebuilt java objects based on the stand schema. Default is false. |
| Enable Enterprise User | Yes | Extend the user schema with enterprise attributes. Default is false. |
| Enable AWS Schema | Yes | Use a pre-built java classes as defined for AWS, as specified here. Default is false. |
| Enable Slack Schema | Yes | Use prebuilt java classes as define for Slack as specified here. Default is false. |
| Enable Dynamic Schema | Yes | Use the Resource Type and/or the Schema defined above for dynamic operations. Default is false. |
| Users Endpoint URL | Yes | Discovered from the resource type or entered manually. Default is /Users. |
| Groups Endpoint URL | Yes | Discovered from the resource type or entered manually. Default is /Groups. |
| UserSchemaIdList | No |
A list of user schemas that define a user. This is discoverable from the Resource Type URL, JSON, or by one of the prebuilt java classes Usually:
|
| GroupSchemaIDList | No | A list of Group schemas that define a Group. This is discoverable from the Resource Type URL or JSON. or by one of the prebuilt java classes. Usually:
|
The following property names can be used when integrating with a Connid system that uses a configuration properties file. It is also used to perform unit tests in the code base.
See src/test/resources/__bcon__development__exclamation_labs__scim2.properties for an example.
| Item | Type | Property Name |
| Service URL | String | service.serviceUrl |
| IO Error Retries | Integer | rest.ioErrorRetries |
| Token | String | security.authenticator.directAccessToken.token |
| Deep Get Enabled | Boolean | results.deepGet |
| Deep Import Enabled | Boolean | results.deepImport |
| Import Batch Size | Integer | results.importBatchSize |
| Pagination Enabled | Boolean | results.pagination |
| Duplicate Record Returns Id | Boolean | service.duplicateErrorReturnsId |
| Enable Standard Schema | Boolean | custom.enableStandardSchema |
| Enable Enterprise User | Boolean | custom.enableEnterpriseUser |
| Enable AWS Schema | Boolean | custom.enableAWSSchema |
| Enable Slack Schema | Boolean | custom.enableSlackSchema |
| Enable Dynamic Schema | Boolean | custom.enableDynamicSchema |
| Users Endpoint URL | String | custom.usersEndpointUrl |
| Groups Endpoint URL | String | custom.groupsEndpointUrl |
| User SchemaId List | String Array | custom.userSchemaIdList |
| Group SchemaId List | String Array | custom.groupSchemaIdList |
The SCIM2 connector implements the following connId SPI operations:
- SchemaOp - Allows the Connector to describe which types of objects the Connector manages on the target resource. This includes the options supported for each type of object.
- TestOp - Allows testing of the resource configuration to verify that the target environment is available (ie. validate the connection to the SCIM2 target system).
- SearchOp - Allows the connector to search the SCIM2 target system for resource objects (most commonly users and groups).
- CreateOp - Allows the connector to create SCIM2 Users and Groups.
- DeleteOp - Allows the connector to delete SCIM2 Users and Groups.
- UpdateDeltaOp - Allows the connector to update SCIM2 Users and Groups. Both PUT (full replacement) and PATCH (partial update) are supported.
- DiscoverConfigurationOp - Allows the connector to suggest configuration values in the user interface at creation time.
Deep Get signifies that a separate HTTP GET is required and automatically executed for each individual resource after a GET request for a list of resources (with or without filters or pagination) is executed. The SCIM2 standard for listing resources has all detail needed, so deep get is not needed for SCIM2 connector and should always be set to false.
Deep Import signifies that a separate HTTP GET is required and automatically executed for each individual resource after a GET request for a full list of resources is executed. The SCIM2 standard for listing resources has all detail needed, so deep import is not needed for SCIM2 connector and should always be set to false.
The duplicate record returns Id configuration option is invoked when an HTTP POST request, used to create a record, returns HTTP 409 (Conflict). This typically indicates that the record we are attempting to create already exists. When this option is true the connector will attempt to get the record by name and return the record’s ID value to the caller. In this way a record can be seamlessly imported when it already exists on the target server. Unfortunately the SCIM2 API does not return HTTP 409 and instead returns HTTP 412. Because this is the case the connector will always do a lookup for an existing object type before creating the type.
The SCIM2 connector supports User and Group objects. The full schemas for these objects, and for all complex types can be found in the schema_doc directory of this project.
| name | type | description |
|---|---|---|
| userName | string | Unique identifier for the User, typically used by the user to directly authenticate to the service provider. Each User MUST include a non-empty userName value. This identifier MUST be unique across the service provider's entire set of Users. REQUIRED. |
| name | complex | The components of the user's real name. Providers MAY return just the full name as a single string in the formatted sub-attribute, or they MAY return just the individual component attributes using the other sub-attributes, or they MAY return both. If both variants are returned, they SHOULD be describing the same name, with the formatted name indicating how the component attributes should be combined. |
| displayName | string | The name of the User, suitable for display to end-users. The name SHOULD be the full name of the User being described, if known. |
| nickName | string | The casual way to address the user in real life, e.g., 'Bob' or 'Bobby' instead of 'Robert'. This attribute SHOULD NOT be used to represent a User's username (e.g., 'bjensen' or 'mpepperidge'). |
| profileUrl | reference | A fully qualified URL pointing to a page representing the User's online profile. |
| title | string | The user's title, such as "Vice President." |
| userType | string | Used to identify the relationship between the organization and the user. Typical values used might be 'Contractor', 'Employee', 'Intern', 'Temp', 'External', and 'Unknown', but any value may be used. |
| preferredLanguage | string | Indicates the User's preferred written or spoken language. Generally used for selecting a localized user interface; e.g., 'en_US' specifies the language English and country US. |
| locale | string | Used to indicate the User's default location for purposes of localizing items such as currency, date time format, or numerical representations. |
| timezone | string | The User's time zone in the 'Olson' time zone database format, e.g., 'America/Los_Angeles'. |
| active | boolean | A Boolean value indicating the User's administrative status. |
| password | string | The User's cleartext password. This attribute is intended to be used as a means to specify an initial password when creating a new User or to reset an existing User's password. |
| emails | complex | Email addresses for the user. The value SHOULD be canonicalized by the service provider, e.g., 'bjensen@example.com' instead of 'bjensen@EXAMPLE.COM'. Canonical type values of 'work', 'home', and 'other'. |
| phoneNumbers | complex | Phone numbers for the User. The value SHOULD be canonicalized by the service provider according to the format specified in RFC 3966, e.g., 'tel:+1-201-555-0123'. Canonical type values of 'work', 'home', 'mobile', 'fax', 'pager', and 'other'. |
| ims | complex | Instant messaging addresses for the User. |
| photos | complex | URLs of photos of the User. |
| addresses | complex | A physical mailing address for this User. Canonical type values of 'work', 'home', and 'other'. This attribute is a complex type with the following sub-attributes. |
| groups | complex | A list of groups to which the user belongs, either through direct membership, through nested groups, or dynamically calculated. |
| groups_value | string | A list of groupId to which the user belongs as multivalued string. This is the value attribute of the groups complex type |
| entitlements | complex | A list of entitlements for the User that represent a thing the User has. |
| roles | complex | A list of roles for the User that collectively represent who the User is, e.g., 'Student', 'Faculty'. |
| x509Certificates | complex | A list of certificates issued to the User. |
- ConnId UID -> SCIM2 id
- ConnId Name -> SCIM2 userName
In addition to all of the above fields, the SCIM2User object for Slack also includes additional fields
(per urn:ietf:params:scim:schemas:extension:slack:guest:2.0:User schema):
| name | type | description |
|---|---|---|
| guestInfo | complex | Guest information for the user
|
| profileInfo | complex | Profile information for the user
|
| name | type | multivalued | description |
| id | string | no | The identifier of the Group. |
| displayName | string | no | A human-readable name, primarily used for display purposes. |
| externalId | string | no | A String that is an identifier for the resource as defined by the provisioning client.t'. |
| members | JSON String | yes | A list of members of the Group as a JSON array. |
| members_value | string | yes | A list Group Identifiers for members of this Group. |
- ConnId UID -> SCIM2 id
- ConnId Name -> SCIM2 displayName
In a SCIM2 Group the members attribute is a multivalued string containing a map of members key/value pairs in JSON format. The following shows the expected return data for member:
{
"value": "9067729b3d-94f1e0b3-c394-48d5-8ab1-2c122a167074",
"$ref": "../Users/9067729b3d-94f1e0b3-c394-48d5-8ab1-2c122a167074",
"type": "User"
}
The SCIM2 Connector supports the following Query Operations
- Get User by id
- Get User by Name (userName)
- Get list of Users using pagination (page number and page size)
- Get all Users
- Create a new user (id is generated by the SCIM2 server and returned)
- Update a user by id (full replacement)
- Delete a user by id
- Get Group by id
- Get Group by name (displayName)
- Get list of Groups using pagination (page number and page size)
- Get all Groups
- Create a new Group (id is generated by the SCIM2 server and returned)
- Update a Group by id (full replacement)
- Delete a Group by id
