16 May 2018
 

Syncope Basics: Manage SCIM v1.1

Written by malessandroni

We recently developed and released the SCIM v1.1 connector as part of the ConnId project. This bundle is used to connect Apache Syncope to a SCIM v1.1 RESTful service.

The development of this connector's first stable version has been sponsored by iWelcome, the leading European IDaaS provider.

Here I'm going to show how to use it on Syncope 2.0.8.

Create project from maven archetype

The new connector is available by default from Syncope 2.0.9-SNAPSHOT, but in this guide I'll show you how to use it in our Syncope latest stable release (2.0.8); so let's start creating a simple Apache Syncope 2.0.8 project from archetype:

$ mvn archetype:generate \
-DarchetypeGroupId=org.apache.syncope \
-DarchetypeArtifactId=syncope-archetype \
-DarchetypeRepository=http://repo1.maven.org/maven2 \
-DarchetypeVersion=2.0.8

By default, the embedded mode is populated with example data.
In order to be more clear, I'll work on a fresh Syncope instance; so if you want to do the same, you can remove example data by running the following commands: 

$ cd [CREATED_PROJECT_FOLDER]
$ cp core/src/main/resources/domains/MasterContent.xml core/src/test/resources/domains/MasterContent.xml

Add SCIM v1.1 connector dependency to Syncope bundles list (step not required in Syncope >= 2.0.9-SNAPSHOT)

To add the SCIM v1.1 bundle dependency to 2.0.8 project you'll need to edit root "pom.xml" file and add the "net.tirasa.connid.bundles.scimv11" dependency.
So from project main folder, run:

$ vi pom.xml

add:

<properties>
  ...
  <connid.scimv11.version>1.0.0</connid.scimv11.version>
  ...
</properties>

then add the "maven-dependency-plugin" as you can see here and remember to insert that content under:

<pluginManagement>
  <plugins>
	...
  </plugins>
</pluginManagement>

Run Syncope in embedded mode

From the project root dir, run:

$ mvn -P all clean install && cd enduser && mvn -P embedded,all

Open http://localhost:9080/syncope-console and you'll access the Syncope Admin Console.

Login to Admin Console using the default "admin" / "password" credentials.

Set up an SCIM external resource

Go to "Topology" and add a new connector (see image below):

You'll be able to see the new SCIM v1.1 bundle, so choose "net.tirasa.connid.bundles.scimv11" from "Bundle" list and fill the other required fields:

Click on "Next" button and enter the SCIM v1.1 service configuration by filling the required parameters (you can find more info about it on related ConnId SCIM v1.1 connector wiki page):

Click on "Next" button again, select connector Capabilities (AUTHENTICATE and SYNC are not supported as you can see here) and click on "Finish":

Now you are ready to create the SCIM external resource.
Click on the just created connector and choose "Add new resource" from right menu:

Dealing with the "id" attribute, returned by SCIM service upon User creations (step not required in Syncope >= 2.0.9-SNAPSHOT)

At this point, since we are using Syncope 2.0.8, we need to manually add the SCIM PropagationActions to Syncope project (the related file already exists in Syncope project from version 2.0.9-SNAPSHOT by default) in order to let Syncope save the Users ID returned by SCIM Service upon creations.

You need to create the " org.apache.syncope.core.provisioning.java.propagation.SCIMv11PropagationActions" file and link it to the "SCIMv11Res" resource.

So, just run the following commands to create and edit a new file with that name:

$ mkdir -p ./core/src/main/java/org/apache/syncope/core/provisioning/java/propagation/ && vim ./core/src/main/java/org/apache/syncope/core/provisioning/java/propagation/SCIMv11PropagationActions.java

copy & paste the content of the file above ( SCIMv11PropagationActions.java).

Then stop Syncope, re-build and re-start it.
When it'll be ready, you'll be able to add the "SCIMv11PropagationActions" to SCIM resource.
So just click on resource node and select "Edit resource" from menu:

Add some required Plain Schemas

From the Admin Console, go to "Configuration" (left panel) -> "Types" -> "Schemas"; in the "PLAIN" accordion panel click on the "+" icon.
Create the "SCIMUserId" schema:

We must add it to "BaseUser" AnyTypeClass in order to have it available for "USER" AnyType.

To do that, select the "AnyTypeClasses" tab, click on "BaseUser" row and choose "edit" from right menu.
Add "SCIMUserId" to "Selected" sub-panel, in "Plain Schemas" section:

Add provision rules for "USER"

Now we need to set some provision rules to map SCIM v1.1 attributes to Syncope attributes.

Click on the "SCIMv11Res" node in "Topology" and choose "Edit provision rules" from right menu.

From the just opened modal window, click on "+" icon and select "USER", then click "Next" in the wizard until you'll get to "Mapping" step.
Now, you can choose a mapping configuration, e.g.

SCIM v1.1 attributes list

You can take a look at this class to see the list of all possible External attributes you can use in mapping.

Custom attributes

Then, about other "Custom Attributes", you should first take a look at the "info" section at the official SCIM v1.1 Connector wiki
After setting the "customAttributesJSON" connector parameter, you'll see that you can easily use your custom attributes as External Attribute in the mapping.
Besides, the connector will also list your custom attributes in the mapping autocompletion list.

E.g.

  • urn:scim:schemas:extension:1.0.segment
  • urn:scim:schemas:extension:1.0.state
  • urn:scim:schemas:core:1.0.myOtherCustomName
  • ...

Configuration test

You can run a simple basic test by exploring the resource and make Syncope retrieve all Users you have in your SCIM service.

Click on the "SCIMv11Res" node from "Topology" and choose "Explore resource" from menu.

Select "USER" from the dropdown on top of the modal window and you'll see some users, in case you have any on your SCIM service.
Here you can see an example:

Sample project

I have created a sample project according to this guide.
Assuming you have Git and Maven properly configured, run:

$ git clone https://github.com/Tirasa/syncopeWithSCIMv11.git
$ cd syncopeWithSCIMv11/
$ mvn -P all clean install && cd enduser && mvn -P embedded,all

Now you can point your browser to http://localhost:9080/syncope-console and start you tests.

Update Syncope 2.1 - Dealing with the "id" attribute, returned by SCIM service upon User creations

After the release of Syncope 2.1 an improvement was made to the logic for all those connectors that need to save the value of some attribute coming from the specific resource service after creating an entity on it.
All that logic from the PropagationActions classes ("org.apache.syncope.core.provisioning.java.propagation.SCIMv11PropagationActions" for SCIM bundle) was removed.
And, since all the logic in the "SCIMv11PropagationActions" is about that, we removed class from the Syncope 2.1 and you don't need to create or link any PropagationActions for SCIM connector.

So, since the "PropagationActions" files were minimized, what else do I need to do for Syncope 2.1?
Well, it is pretty simple!
You just need to open the resource mapping and you'll see a new field:

Enter the previously created required schema ("SCIMUserId" for "USER" AnyType) in that field, to handle the returned value from the SCIM service.

Done, that's all!
So, to summarize the all process:

  • create schemas to handle the attribute values returned by the service;
  • add those schemas to the new field in resource mapping (Schema to hold values for identifiers generated upon Create by the external Identity Store);
  • add the "[SCHEMA_NAME]" -> "__UID__" mapping item with "Remote Key" flag.
       

« Return