Getting started with user sync using REST

<< Click to Display Table of Contents >>

Navigation:  Environments identity and access management > Synchronizing users > Synchronizing users using SCIM's REST methods >

Getting started with user sync using REST

Synchronizing users

To synchronize users from an external system, follow these steps:

 

1.Register the external application and create the OAuth 2.0 keys in the Bizagi Work portal of your environment.

2.Get the token that permits invocation of SCIM services.

3.Create the JSON structure needed with the information of the user to be synced.

4.Invoke the service

 

The following procedure uses POSTMAN as the client. However you may use any other client using a different framework, as long as it is compatible with RESTful services using the OAuth 2.0 protocol.

 

Prerequisites

User synchronization using SCIM is only available for Bizagi projects using Automation Service (cloud) or Automation server (on-premises) using an SQL database.

 

Procedure

1. Register an OAuth application

Go to the Work portal. Under the security section of the Admin menu, select the OAuth2 Applications option  to grant access to an external application.

 

SCIM_3

 

This option lists services being accessed by Bizagi devices, and allows you to include additional applications that represent granted access to the services by providing the appropriate access keys.

Click the option to add a new record to this table:

 

SCIM_4

 

The configuration must be like this:

 

SCIM_5

 

Grant type: Client credentials

Allowed Scope: API and USER SYNC

User Name: admon

Token lifetime: This duration depends on your organization's needs or policies.

 

Save the keys in a secure place:

 

SCIM_6

 

2. Authenticate with OAuth

Once you have copied the Client ID and Client Secret, you have to establish authenticated communication through your client.

 

Note that Bizagi expects the credentials as a single string encoded in base64.

 

2.1 To encode the credentials as a single string:

Copy the Client ID append a colon (:), then add the Client secret.

Here is the format, disregarding the [ ] characters:

[Client Id]:[Client Secret]

Encode this string with base64. The result is a string containing the encoded credentials.

 

2.2 Configure a RESTful POST invocation in your client.

To do that make sure that the client invoking the service has the following configuration:

 

URL: [Project_URL]/oauth2/server/token

HTTP Method: POST

Authorization: No Auth

Headers:

 Content-type: application/x-www-form-urlencoded

 Authorization: Provide the Basic keyword, add a blank space and then add the encoded credentials obtained in a previous step.

 Use the following format, disregarding the [ ] characters:

 Basic [encoded credentials]

Body: Send as raw data the following string: grant_type=client_credentials&scope=api

 

SCIM_7

 

SCIM_8

 

The response to this invocation contains the access token:

 

{
"access_token": "aebda3f1adcab6c90653bd1899613e880dc8002d",
"token_type": "bearer",
"expires_in": 1200,
"scope": "api usersync openid",
"http_status_code": 200
}

 

3. Create the JSON structure needed by SCIM

SCIM is a standard in which user information is defined by a schema. You need to recreate this structure in the message to be sent with the information of a user being synchronized. The structure depends on whether you are creating a new user, replacing a user, updating a parameter or deleting (deactivating in Bizagi) a user. See the supported operations in the next section.

 

4. Invoke the service

The next section shows examples of invocation of all possible operations.

 

Create: Service to create one user.

POST [Project_URL]/scim/v2/Users

Read: Get information of a user.

GET [Project_URL]/scim/v2/Users/{userName}

Update: Update the information of a user.

PATCH [Project_URL]/scim/v2/Users/{userName}

Replace: These

PUT [Project_URL]/scim/v2/Users/{userName}

Delete

DEL [Project_URL]/scim/v2/Users/{userName}