Syncope Basics: Manage Microsoft Azure part II

This guide is a sequel of Syncope Basics: Manage Microsoft Azure and explains how to configure Apache Syncope in order to allow the assignment / removal of Azure Licenses to / from Azure AD Users.

As you should have seen from previous guide, it is required to have some of the new Syncope 2.0.9-SNAPSHOT features to be able to make provisioning on Azure AD.

For this tutorial, I've decided to use the 2.0.9-SNAPSHOT version, instead of manually edit 2.0.8.
I will show how to use a SNAPSHOT version from archetype.

Create project from maven archetype

$ mvn org.apache.maven.plugins:maven-archetype-plugin:2.4:generate \
 -DarchetypeGroupId=org.apache.syncope \
 -DarchetypeArtifactId=syncope-archetype \
 -DarchetypeRepository=http://repository.apache.org/content/repositories/snapshots \
 -DarchetypeVersion=2.0.9-SNAPSHOT

As in the previous guide, let's remove all sample 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

Now you just need to add the following code to the root "pom.xml" file:

<repositories>
  <repository>
    <id>apache.snapshots</id>
    <url>https://repository.apache.org/content/repositories/snapshots/</url>
    <snapshots>
      <enabled>true</enabled>
    </snapshots>
  </repository>
</repositories>

this way you will be able to download updated content from "snapshots" repository.

Now, at the time I'm writing this post, the ConnId Azure Bundle version is 1.0.0, but here we need to use latest version 1.0.1-SNAPSHOT, so we need to edit "pom.xml" file to override it.
This step won't be necessary when Syncope 2.0.9 will be released and will include ConnId Azure Bundle version 1.0.1 as default.

Add the following property inside the "<properties></properties>" tag:

<connid.azure.version>1.0.1-SNAPSHOT</connid.azure.version>

Run Syncope and set up an Azure external resource

Still follow previous guide to know how to run Syncope and set up both an Azure connector and external resource.
Then, continue on this one.

Set up Syncope to handle License assignment and removal

Add a new "AnyType"

We need to create a new "AnyType" that represents a License. Go to "Configuration" (left panel) -> "Types" -> "AnyType" (tab), click the "+" button and add a new one:

Define provision rules for LICENSE AnyType

First, it is important to know that Azure requires the "usageLocation" attribute to be populated before assigning / removing a license (see here for more details).

So, in this tutorial, I will create a new Plain Schema that I will use in mapping to refer to related external attribute ("usageLocation"):

Then, we need to add it to existing Azure resource provision rules. It will be something like:

"AzureUsageLocation" -> "usageLocation".

Now, we need to add a new mapping rule for relationships between USER and LICENSE objects.
The correct rule will be:

"relationships[USER_LICENSE][LICENSE].name" -> "azureLicense".

See the Syncope reference guide related section about internal attribute mapping expression models.

Configure an Azure external resource to pull licenses from Azure

I prefer to add a new resource that will be used to pull licenses only. So let's add a new resource from "Topology" section in Admin Console:

We need to define the provision rules for that resource and specific for LICENSE AnyType.
So click on the new resource node and choose "Edit provision rules" from right menu.
For our example it is enough to use:

"name" -> "skuId"

but you could also add other rules. Here is a list of other external attributes you can map:

• objectId (String)
• capabilityStatus (String)
• consumedUnits (Integer)
• skuId (String)
• skuPartNumber (String)
• appliesTo (String)

Important: the only required attribute to map relationships between USER and LICENSE is "skuId".
It will be used to assign or remove licenses, as explained in the official Microsoft Azure API reference .
So you will specify a "skuId", related to a SKU, in order to assign / remove one or more licenses that may contains one or more service plans.

Now, we should add a Pull task in order to pull all licenses from Azure.
Click on the "AzureLicenses" resource node in "Topology" and choose "Pull tasks".
Click on the "+" button and create the Pull task as on the following images:

Click on the just created task and click on "execute" from menu, then on the single gear icon.
It will start pulling license "skuId"s from Azure.

Go to "Realms" (left panel) -> "LICENSE" (tab) and you should see the licenses list (if there were any on you Azure account).
Otherwise, go back to Pull tasks view, select "ImportLicenses" Pull task and click on "view" to see the list of task executions and check the details of the operation.

Configuration test

If you want to test the configuration of the "AzureLicenses" resource you can just try exploring it and Syncope will show all Subscriptions you have in Azure AD.
Just click on the new "AzureLicenses" node from "Topology" and choose "Explore resource" from menu.

A more interesting test would be to link one o more licenses to a user and propagate it to Azure AD.

So, you can create a user and add some relationships with LICENSE objects to it.
E.g. in case you want to create users from Admin Console, here you can see an image showing the "Relationships" wizard step during user edit:

Otherwise, you can create users from REST API, in this case here is an example of user payload to use for
POST /users
endpoint:

{
  "@class": "org.apache.syncope.common.lib.to.UserTO",
  "type": "USER",
  "realm": "/",
  "username": "testUserWithLicenses",
  "creator": "admin",
  "status": "active",
  "password": "Password01",
  "plainAttrs": [
	{
	  "schema": "email",
	  "values": [
		"testUserWithLicenses@YOUR_TENANT"
	  ]
	},
	{
	  "schema": "AzureUsageLocation",
	  "values": [
		"IT"
	  ]
	}
  ],
  "resources": [
	"AzureRes"
  ],
  "relationships": [
	{
	  "type": "USER_LICENSE",
	  "otherEndType": "LICENSE",
	  "otherEndKey": "..."
	}
	// ...
  ]
}

By using the endpoint above, the "testUserWithLicenses" user will be created on Syncope and propagated to Azure AD with the specified license:

Sample project

I have created a new branch on the existing sample project to show the content of this tutorial.
Assuming you have Git and Maven properly configured, run:

$ git clone -b LICENSE_SUPPORT https://github.com/Tirasa/syncopeWithAzure.git
$ cd syncopeWithAzure/
$ 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.

0 VOTINot rated yet