Skip to content

Instantly share code, notes, and snippets.

@izhar

izhar/totango_scim_support_v1.md

Last active July 31, 2019 09:12
Show Gist options
  • Star 1 You must be signed in to star a gist
  • Fork 0 You must be signed in to fork a gist
  • Save izhar/1b6921125031578a9974dfee623c95f7 to your computer and use it in GitHub Desktop.
Save izhar/1b6921125031578a9974dfee623c95f7 to your computer and use it in GitHub Desktop.
Download ZIP
Totango User Lifecycle API SCIM support
Raw
totango_scim_support_v1.md

SCIM API

Supported Lifecycle operations

Single User operations only are supported (no bulk)

Endpoints

Create User

$ curl -XPOST <Base URL>/Users -d @user.json -H "Authorization: Bearer <AuthToken>" -H "Content-Type: application/scim+json"

Important: token must belong to a user with Global Totango Admin privileges

user.json

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User",
    "urn:ietf:params:scim:schemas:totango:1.0:User"
  ],
  "userName": "ericd@company.com unique, not null",
  "externalId": "701984 - optional, will be returned as-is by totango",
  "title": "CSM Team Leader",
  "displayName": "Eric Dunn",
  "name": {
    "familyName": "Dunn",
    "givenName": "Eric"    
  },
  "urn:ietf:params:scim:schemas:totango:1.0:User": {
    "isActive" : true,
    "license": ["zoe"],
    "isAdmin": false,
    "managerEmail": "tracyd@work.com",
    "managerExternalId": "optional",
    "teams": [
      {"name": "first team"},
      {"name": "second team"}
    ]
  }
}

custom totango schema notation is defined as per spec here
custom totango schema is defined as per spec here

Create success response

As per spec

HTTP/1.1 201 Created

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User",
    "urn:ietf:params:scim:schemas:totango:1.0:User"
  ],
  "meta": {
    "created": "2019-05-02T10:58:54Z",
    "resourceType": "User"
  },
  "userName": "ericd@company.com",
}

Create error response

As per spec

HTTP/1.1 409 Conflict

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
  "scimType":"uniqueness"
  "detail":"user already exists",
  "status": "409"
}

Or

HTTP/1.1 400 Bad Request

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
  "scimType":"invalidValue"
  "detail":"userName must be an email",
  "status": "400"
}

Update User

Invoke the Users enpoint with the UserID and a PATCH verb, see spec for full details.
Parameters sent will override existing ones, existing User attributes which were not updated will remain unchanged.

$ curl -XPATCH <Base URL>/Users/userID -d @user_update.json -H "Authorization: Bearer <AuthToken>" -H "Content-Type: application/scim+json"

Update parameters

STD & Custom properties

{ 
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:PatchOp",
    "urn:ietf:params:scim:schemas:totango:1.0:User"
  ],
  "Operations":[
    {
      "op":"replace",
      "value":[
        {
          "title": "CSM Director",
          "urn:ietf:params:scim:schemas:totango:1.0:User": {
            "license" : ["zoe","spark"]
          }
        }
      ]
    }
  ]
}
HTTP/1.1 204 No Content

Deactivate a user

{ 
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:PatchOp"
  ],
  "Operations":[
    {
      "op":"replace",
      "value":[
        {
          "urn:ietf:params:scim:schemas:totango:1.0:User": {
            "isActive" : false
          }
        }
      ]
    }
  ]
}
HTTP/1.1 204 No Content

Replace User

Invoke the Users enpoint with the UserID and a PUT verb, see spec for full details.
Parameters sent will override existing ones, existing User attributes which were not sent will be deleted.

curl -XPUT <Base URL>/Users/userID -d @user_replace.json -H "Authorization: Bearer <AuthToken>" -H "Content-Type: application/scim+json"

user_replace.json

{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:PutOp",
    "urn:ietf:params:scim:schemas:totango:1.0:User"
  ],
  "Operations": [
    {
      "op": "replace",
      "value": [
        {
          "name": {
            "familyName": "new_famiy22",
            "givenName": "new_name222"
          },
          "title": "Updated User Title",
          "urn:ietf:params:scim:schemas:totango:1.0:User": {
            "license": [
              "zoe"
            ],
            "teams": [
              {
                "name": "Team_for_SCIM_tests"
              }
            ]
          }
        }
      ]
    }
  ]
}

Response

HTTP/1.1 204 No Content

Endpoints

The SCIM interactions involve two endpoints

  • OAuth: https://{env}.totango.com/oauth2/api/v1/token
  • SCIM: https://{env}.totango.com/api/v2/scim/services/{service-id}/Users/{user-id}

Env: as appears in the main totango application URL
ServiceID: customer (service) ID
UserID: user ID (email) on which we operate

Example flow

A complete flow example of getting the Auth token and using it in the SCIM API

Get Bearer token

Invoke token endpoint with base64 encoded credentials
Credentials must be in the username:password format, for example: joe.green@work.com:passWord123

Important: token must belong to a user with Global Totango Admin privileges

curl -X POST \
  'https://app-test.totango.com/oauth2/api/v1/token?grant_type=client_credentials' \
  -H 'Authorization: Basic dGVzdGluZy51c2VyKzIzNV9hZG1pbkB0b3RhbmdvLmNvbTpUZXN0aW5nVXNlcjEyMzQ='

Response

HTTP/1.1 200 OK
{"access_token":"607d378d7f794b3f1cdb525ec694687239f5e5a2","token_type":"Bearer","expires_in":86400,"scope":""}

Create User

Use above access_token in the Bearer Header

curl -X POST \
  https://app-test.totango.com/api/v2/scim/services/235/Users \
  -H 'Authorization: Bearer 607d378d7f794b3f1cdb525ec694687239f5e5a2' \
  -H 'Content-Type: application/scim+json' \
  -d '{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User",
    "urn:ietf:params:scim:schemas:totango:1.0:User"
  ],
  "userName": "e2e_user023@totango.com",
  "externalId": "701984",
  "title": "CSM Team Leader",
  "displayName": "E2e User",
  "name": {
    "familyName": "E2E",
    "givenName": "User"
  },
  "urn:ietf:params:scim:schemas:totango:1.0:User": {
    "isActive" : true,
    "license": ["zoe"],
    "isAdmin": false,
    "managerEmail": "tracyd@work.com",
    "managerExternalId": "1234585",
    "teams": [
      {"name": "Team_for_SCIM_tests"}
    ]
  }
}'

Response

When successful

HTTP/1.1 201 Created
{
    "url": "https://app-test.totango.com/api/v2/scim/services/235/Users",
    "reason": "Created",
    "status_code": 201,
    "json": {
        "schemas": [
            "urn:ietf:params:scim:schemas:core:2.0:User",
            "urn:ietf:params:scim:schemas:totango:1.0:User"
        ],
        "meta": {
            "created": "2019-07-31T01:10:01.564Z",
            "resourceType": "User"
        },
        "userName": "e2e_user_ttwvr@company.com"
    }
}

When user already exists

HTTP/1.1 409 Conflict
{"schemas":["urn:ietf:params:scim:api:messages:2.0:Error"],"scimType":"uniqueness","detail":"user already exists","status":409}
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment