API Walkthrough

Introduction

This walk-through explains the basic functionality of the IdH service. It demonstrates how to link and unlink multiple user identities to a local user identity via the IdH server's RESTful interface.

Linking multiple user identities /link

To link multiple user identities within the connected LDAP directory the service exposes the /link endpoint. This endpoint expects an HTTP POST request with a JSON formatted list of multiple user identities in the SCIM schema as input.

The specification of the SCIM schema can be found here RFC 7643.

Default configuration requires authentication at the endpoint, either HTTP Basic or OpenId Connect. For HTTP Basic please have a look at the Configuration section. For OpenId Connect please have a look at the INDIGO-DataCloud OpenId Connect provider IAM.

The response of the POST call can be used for unlinking the provided identities again.

/link

An example link call might look like the following, with the users.scim user data shown below.

curl -v -k -u restadmin:restadmin -X POST https://localhost/link -H "Content-Type: application/scim+json" [e-mail]

user.scim

[{
  "schemas":["urn:ietf:params:scim:schemas:core:2.0:User"],
  "userName":"primaryUser",
  "externalId":"2abf56d2-9bdc-47d2-a6c7-074c24717879",
  "active":true,
  "name":{
    "formatted":"Primary User",
    "familyName":"User",
    "givenName":"Primary"
  }
},
{
  "schemas":["urn:ietf:params:scim:schemas:core:2.0:User"],
  "userName":"secondaryUser",
  "externalId":"2abf56d2-9bdc-8as1-a6c7-074c24769896",
  "active":false,
  "name":{
    "formatted":"Secondary User",
    "familyName":"User",
    "givenName":"Secondary"
  }
}
]

Unlinking multiple user identities /unlink

To unlink multiple user identities within the connected LDAP directory the service exposes the /unlink endpoint. This endpoint expects an HTTP POST request with a JSON formatted list of multiple user identities in the SCIM schema as input.

The user identity objects need to include the extended meta-data and group information of the linking output explained in the previous section.

The specification of the SCIM schema can be found here RFC 7643.

Default configuration requires authentication at the endpoint, either HTTP Basic or OpenId Connect. For HTTP Basic please have a look at the Configuration section. For OpenId Connect please have a look at the INDIGO-DataCloud OpenId Connect provider IAM.

/unlink

An example unlink call might look like the following, with the users.scim user data shown below.

curl -v -k -u restadmin:restadmin -X POST https://localhost/unlink -H "Content-Type: application/scim+json" [e-mail]

user.scim

[
    {
        "active": false,
        "externalId": "2abf56d2-9bdc-8as1-a6c7-074c24769896",
        "groups": [
            {
                "display": "group1",
                "value": "500079"
            },
            {
                "display": "group2",
                "value": "500080"
            },
            {
                "display": "group3",
                "value": "500097"
            }
        ],
        "meta": {
            "cn": "[e-mail]",
            "gidNumber": "500084",
            "homeDirectory": "/home/secondary",
            "uid": "secondaryUser",
            "uidNumber": "900015"
        },
        "name": {
            "familyName": "User",
            "formatted": "Secondary User",
            "givenName": "Secondary"
        },
        "schemas": [
            "urn:ietf:params:scim:schemas:core:2.0:User"
        ],
        "userName": "secondaryUser"
    },
    {
        "active": true,
        "externalId": "2abf56d2-9bdc-47d2-a6c7-074c24717879",
        "groups": [
            {
                "display": "secondaryUserGroup",
                "$ref": "https://example.com/v2/Groups/e9e30dba-f08f-4109-8486-d5c6a331660",
                "value": "500084"
            }
        ],
        "meta": {
            "cn": "[e-mail]",
            "gidNumber": "500001",
            "homeDirectory": "/home/primary",
            "uid": "primaryUser",
            "uidNumber": "900010"
        },
        "name": {
            "familyName": "User",
            "formatted": "Primary User",
            "givenName": "Primary"
        },
        "schemas": [
            "urn:ietf:params:scim:schemas:core:2.0:User"
        ],
        "userName": "primaryUser"
    }
]