Use PhenixID Server as SCIM Bulk endpoint

Please contact PhenixID if you would like to use this feature.

For an overview of PhenixID an SCIM compatibility, please view this document.

This document is written for PhenixID Server.

The reader should have some basic knowledge about PhenixID Server.

This document describes how to setup PhenixID server as a SCIM Service Provider to receive SCIM Bulk requests and respond with SCIM Bulk response.

The solution contains two steps:

1. Install additional valve and dependencies

2. Configure pipe to act as the SCIM endpoint


It also describes the additional valve needed, SCIMBulkResponseValve, for this setup.

Install additional valve and dependencies

Download

Download dependencies here.

Download valve here.

Install

- Stop PhenixID Server

- Unzip the dependencies zip file. Copy the jar to phenixid_server_root/mods/com.phenixidentity~phenix-pipes~<version>/lib/

- Unzip the valve zip file in phenixid_server_root/mods/com.phenixidentity~phenix-pipes~<version>/com/phenixidentity/pipes/valves/

- This file should have been added phenixid_server_root/mods/com.phenixidentity~phenix-pipes~<version>/com/phenixidentity/pipes/valves/sthlm/scim/SCIMBulkResponseValve.class

- Start PhenixID Server

Configure pipe to act as the SCIM endpoint

- Enable the Pipes module for HTTP by following this instruction.

- Login to Configuration Manager

- Click Advanced

- Add pipe as below. Change this template to suite your environment. Make sure the file path is correct.

{
        "id": "SCIM_REST_PIPE",
        "description": "Receive SCIM BulkRequest, save to file, return SCIM BulkResponse with status 202",
        "http_enabled": "true",
        "http_path_pattern": "POST:/pipes/scim/v2/Bulk",
        "http_response_content_type": "application/scim+json",
        "http_response_body_item_property": "bulk_response",
        "valves": [
            {
                "name": "ItemCreateValve",
                "config": {
                    "dest_id": "dummy_json"
                }
            },
            {
                "name": "PropertyAddValve",
                "config": {
                    "name": "body",
                    "value": "{{request.body}}"
                }
            },
            {
                "name": "PropertyAddDateTimeValve",
                "config": {
                    "name": "time"
                }
            },
            {
                "name": "PropertyAddValve",
                "config": {
                    "name": "file",
                    "value": "{{item.time}}_BulkRequest.json"
                }
            },
            {
                "name": "PropertyStringBase64DecoderValve",
                "config": {
                    "source": "body",
                    "dest": "data_to_export"
                }
            },
            {
                "name": "FileWriteValve",
                "config": {
                    "path": "/opt/PhenixID/Provisioning/import/scim/json/{{item.file}}",
                    "source": "data_to_export",
                    "overwrite_existing": "true"
                }
            },
            {
                "name": "SCIMBulkResponseValve",
                "config": {
                    "scim_bulk_request_input": "{{item.data_to_export}}",
                    "scim_bulk_request_output_property": "bulk_response"
                }
            }
        ]
    }


- Restart PhenixID Server

Test

Use a REST test client, such as Postman, to send in a proper SCIM BulkRequest. 

The response should be 200 OK with a SCIM BulkResponse in the response body. 


Example.

Request

POST /pipes/scim/v2/Bulk HTTP/1.1
Host: myphxidserver.example.org
Content-Type: application/scim+json
Accept: application/scim+json
Cache-Control: no-cache

{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:BulkRequest"
  ],
  "Operations": [
    {
      "method": "PUT",
      "path": "/Users",
      "bulkId": "612deb878bc3407c92873d3505670229",
      "data": {
        "schemas": [
          "urn:ietf:params:scim:schemas:core:2.0:User"
        ],
        "id": "aa11111",
        "externalId": "29EC41FF-4B7D-259A-E044-00306E5F821C",
        "name": {
          "familyName": "Smith",
          "givenName": "Joe",
          "middleName": "Branker",
          "formatted": "Joe Branker Smith"
        },
        "displayName": "Joe Smith",
        "phoneNumbers": [
          {
            "value": "+46 734121234",
            "type": "mobile"
          }
        ],
        "photos": [
          {
            "value": "LzlqLzRBQVFTa1pKUmdBQkFRQUFBUUFCQUFELzJ3",
            "type": "photo"
          }
        ],
        "active": true,
        "meta": {
          "resourceType": "USER",
          "created": "2018-03-26T06:10:07.177+02:00",
          "lastModified": "2018-06-30T06:01:06.523+02:00"
        }
      }
    }
  ]
}


Response

HTTP/1.1 200 OK
connection:Keep-Alive
content-length:157
content-type:application/scim+json
date:Tue, 17 Jul 2018 16:21:12 GMT
keep-alive:timeout=5, max=100
server:Apache/2.4.18 (Ubuntu)

{
    "Operations": [
        {
            "method": "PUT",
            "bulkId": "612deb878bc3407c92873d3505670229",
            "status": "202"
        }
    ],
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:BulkResponse"
    ]
}

SCIMBulkResponseValve description

Creates a SCIM BulkResponse with a SCIM BulkRequest as input. Used in the context of a HTTP enabled pipe.

On successful execution, a SCIM BulkResponse is created with status=202 for every operation in the BulkRequest. The attributes method, path, location, bulkId is taken from the BulkRequest and set on the BulkResponse.

The SCIM BulkResponse is added to an item. The value is Base64 encoded.

Properties

Name Description Default value Mandatory Supports property expansion
scim_bulk_request_input Where to find the BulkRequest data Yes Yes
scim_bulk_request_output_property Item property to populate with the BulkRequest result Yes No

Example configuration

{
                "name": "SCIMBulkResponseValve",
                "config": {
                    "scim_bulk_request_input": "{{item.data_to_export}}",
                    "scim_bulk_request_output_property": "bulk_response"
                }
            }