Purpose

The purpose of this module is to show you how to use the CustomerID REST API to do basic query functions for integration to external services.

Requirements

CustomerID installed
POSTMAN

Overview

We will use CustomerID REST API interface to query organisation and user information.

Refer to the API reference documentation at APIs - CustomerID.

There are several versions of CustomerID REST API. Note that each version adds functionality and does not replace the older ones. So you can use operations of all REST API versions when appropriate.

Preliminary tasks

For this lab, we first temporarily set a simple REST API password. Add following to eidm2.properties and then restart Wildfly:

# REST API credentials
rest.username = restuser
rest.password = restpass

In this lab we specify the API credential in query parameters. In production environments if password authentication is used, we recommend using HTTP Basic Auth to avoid credentials written in log files. Instead of password authentication, Ubisecure recommends OAuth2 Bearer Tokens as explained in the product documentation.

Instructions

List users

https://login.smartplan.com:7443/customerid-rest/services/2.1/users/?username=restuser&password=restpass

This operation shows all users IDs of CustomerID, for example:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Users xmlns="http://schema.ubisecure.com/customerid/api" inResponseTo="/2.1/users/" method="GET">
<Id>6225612a-02c4-4f5c-b875-bbb23379a6f2</Id>
<Id>1f216754-e009-4153-9e58-f6dd1ccdfefb</Id>
<Id>980a4aa3-8dac-4365-af75-58028d2353eb</Id>
<Id>d6cb9cea-b807-49a6-9746-99608591d89e</Id>
<Id>d69ce890-76a2-40be-8677-3ec951954b25</Id>
<Id>9bfba31b-5047-4baf-941c-e88ce15707e3</Id>
</Users>

Query user info

Pick one user ID from the output of previous step, such as 6225612a-02c4-4f5c-b875-bbb23379a6f2, and use it in the query user command below:

https://login.smartplan.com:7443/customerid-rest/services/2.1/users/6225612a-02c4-4f5c-b875-bbb23379a6f2?username=restuser&password=restpass

The individual user information will be shown:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<User xmlns="http://schema.ubisecure.com/customerid/api" inResponseTo="/2.1/users/6225612a-02c4-4f5c-b875-bbb23379a6f2" method="GET" type="user">
<Attribute name="id">
    <Value>6225612a-02c4-4f5c-b875-bbb23379a6f2</Value>
</Attribute>
<Attribute name="firstname">
    <Value>Leena</Value>
</Attribute>
<Attribute name="surname">
    <Value>Laine</Value>
</Attribute>
<Attribute name="cn">
    <Value>cd4b6658-b4c5-4e39-82e9-aa19e73bb42f</Value>
</Attribute>
<Attribute name="login">
    <Value>leena.laine</Value>
</Attribute>
<Attribute name="email">
    <Value>leena.laine@example.com</Value>
</Attribute>
<Attribute name="organization">
    <Value>Users</Value>
</Attribute>
<Attribute name="status">
    <Value>Enabled</Value>
</Attribute>
</User>

Query user by email address

https://login.smartplan.com:7443/eidm2/services/user/Users?username=restuser&password=restpass&email=leena.laine%40example.com

<user>
   <id>https://login.smartplan.com:7443/eidm2/services/user/Users/a3cf6833-f3dd-4a24-ba38-cebc55191571</id>
   <organization>https://login.smartplan.com:7443/eidm2/services/org/Users</organization>
   <organizationFriendlyName>Users</organizationFriendlyName>
   <status>Enabled</status>
   <attributes>
      <uid>leena.laine</uid>
      <firstname>Leena</firstname>
      <surname>Laine</surname>
      <email>leena.laine@example.com</email>
      <cn>a3cf6833-f3dd-4a24-ba38-cebc55191571</cn>
      <organization>Users</organization>
   </attributes>
</user>

Query users by role membership

https://login.smartplan.com:7443/eidm2/services/role/2184053-5/mainuser?username=restuser&password=restpass&assignments=true&assignmentEntities=true

List organisations

https://login.smartplan.com:7443/eidm2/services/orgs/?username=restuser&password=restpass&assignments=true&assignmentEntities=true

Create new user

For this exercise, you have to use Postman (instead of your browser) and POST calls.

Create a new user to "Users" organisation

Please read the documentation for "Create User" on Ubisecure Developer Portal. The direct link for the call is: REST API 1.0 - CustomerID#CustomerID-MOD009CreateUser

The format of the URL is:

MOD009 Create User

https://HOSTNAME/eidm2/services/users/ORGANIZATION/

The parameters you need in this API call are:

uid, email, firstname and surname.

If you also want to enable password, you must include parameters pwd and pwd.activated.

Parameter	Accepted values	value

Parameter	Accepted values	value
uid	String
email	String
firstname	String
surname	String
pwd.activated	Boolean	true
pwd	String

Open Postman

As you don't have any collections, you will use the Scratch Pad

Click on "New" button and next select "HTTP Request"

On the right side you will see a request, which by default appears as GET. Now you can edit this request to fit your task.

Hints:

The URL for this HTTP request becomes https://login.smartplan.com:7443/eidm2/services/users/Users/

Use email address as both uid and email parameters. Choose any email, for instance hi@me.com
In Postman settings, set SSL certificate verification OFF.
On Authorization, select "Basic Auth"

Once the call is successful, you will see a response like this:

Finally, you can verify the new user was created. Log in to CustomerID administrative interface (using Scott Long user).
Go to the "Users" tab and you will find the new user at he bottom.

Additional Exercise (Optional): Enable CustomerID REST API access with OAuth2 Client Credentials grant

As mentioned above, several authentication methods can be used for accessing the CustomerID REST API. Ubisecure recommends using OAuth2 Bearer Tokens as the most secure alternative. Here you can learn how to configure OAuth2 authentication for the CustomerID REST API with OAuth2 Password Grant: Configuring OAuth2 authentication for REST API

Since CustomerID version 6.3, OAuth2 Client Credentials Grant can be used instead. It allows fetching the OAuth2 access tokens without using a technical user ID. In this lab you’ll learn how to configure an OAuth2 client for that.

Step 1. Create OAuth2 Client Credentials Grant authentication method

On Global Method Settings tab, click on New Method
Create and enable a new authentication method:
o Title: OAuth2 Client Credentials
o Name: client.credentials.1
o Method Type: OAuth2 Client Credentials Grant
o Directory: Ubilogin Directory
Add the new method to the Site Methods of sites SmartPlan and eIDM Services.
Allow the new method for the application CustomerID API
Copy the client_id of the CustomerID API application, you will need it in the next step:

Step 2. Create an API client

On the SmartPlan site, create and enable a new OAuth2 application “CustomerID API Client”.
Upload the following as client metadata. As the scope value, use the CustomerID API client_id you copied in the previous step.
{ "scope": "5700f86b-0cf4-4923-8c77-9df0bed7c538", "grant_types": [ "client_credentials" ] }
Activate the application and save the generated client_id and client_secret. You will need them for using the API.
As Allowed Methods, select “OAuth2 Client Credentials”
As Allowed To, select the group “CustomerID API Users” from the “eIDM Services” site.

Step 3. Create a technical user account

For the Client Credentials access, we need a technical user account that defines the desired access rights for the client. This is a one-time server side configuration and the user account is not needed in token requests, unlike with OAuth2 Password Grant.

On the SmartPlan site, create a new user:
Add required definitions on the Methods, Member Of and Impersonated By tabs as follows

The ImpersonatedBy configuration gives the API client the required access rights “through” the user cid-api-user and the group CustomerID API Users.

Step 4. Test the REST API with OAuth2 Client Credentials Grant

Fetch access token

curl --basic -u <client_id>:<client_secret> https://sso.example.com/uas/oauth2/token -d grant_type=client_credentials -d "scope=5700f86b-0cf4-4923-8c77-9df0bed7c538"
{"access_token":"eyJjdHkiOiJKV1QiLCJhbGci....""token_type":"Bearer","expires_in":3600}

Use the API

curl --header "Authorization: Bearer eyJjdHkiOiJKV1QiLCJhbGci...." -X GET https://login.smartplan.com:7443/customerid-rest/services/2.1/users/
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Users xmlns="http://schema.ubisecure.com/customerid/api" inResponseTo="/2.1/users/" method="GET">
<Id>6225612a-02c4-4f5c-b875-bbb23379a6f2</Id>
<Id>1f216754-e009-4153-9e58-f6dd1ccdfefb</Id>
<Id>980a4aa3-8dac-4365-af75-58028d2353eb</Id>
<Id>d6cb9cea-b807-49a6-9746-99608591d89e</Id>
<Id>d69ce890-76a2-40be-8677-3ec951954b25</Id>
<Id>9bfba31b-5047-4baf-941c-e88ce15707e3</Id>
</Users>

Lab 2.3: Using the CustomerID REST API