IAM account API

IAM provides a RESTful API that can be used to manage users, group membership, clients, etc.

IAM implements the following endpoints:

  • /iam/account/{id}/attributes, providing access to user attributes
  • /iam/account/{id}/authorities, providing access to user authorities/roles
  • /iam/account/me/clients, providing access to clients owned by the user
  • /iam/account/find/{option}, searching users by username/label/e-mail/group/certificate subject
  • /iam/account/{id}/groups/{groupId}, providing access to user groups
  • /iam/account/{id}/managed-groups, providing access to groups to which a user is manager
  • /iam/group/{groupId}/group-managers, listing managers of a certain group
  • /iam/account/{id}/labels, providing access to user account labels
  • /iam/account/{id}/endTime, managing user membership end time
  • /iam/account/me/proxycert, managing user proxy certificate
  • /iam/account/search, listing user accounts
  • /iam/group/search, listing all groups

Authentication is required in all the endpoints and the access is based on IAM roles. Remember that there are three roles in Indigo IAM: Amdin, User, Group Manager.

User attributes

GET /iam/account/{id}/attributes

Retrieves user attributes. The {id} refers to the account identifier.

Requires that the user has ROLE_ADMIN, ROLE_GM, or is the one represented by the {id}.

$ curl -s -H "Authorization: Bearer ${AT}" \
  http://localhost:8080/iam/account/80e5fb8d-b7c8-451a-89ba-346ae278a66f/attributes | jq
[
  {
    "name": "Nickname",
    "value": "Test"
  }
]

PUT /iam/account/{id}/attributes

Adds attributes to the user account. It can be done directly through the IAM dashboard by clicking on “Set attribute” button in Attributes section of the user homepage.

Requires ROLE_ADMIN.

$ curl -X PUT -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${AT}" -d @attribute.json \
  http://localhost:8080/iam/account/80e5fb8d-b7c8-451a-89ba-346ae278a66f/attributes

where attribute.json is:

{
   "name":"Nickname",
   "value":"Test"
}

DELETE /iam/account/{id}/attributes

Deletes user attribute by adding the query parameter at the end of the endpoint.

Requires ROLE_ADMIN.

$ curl -X DELETE -H "Authorization: Bearer ${AT}" \
  http://localhost:8080/iam/account/80e5fb8d-b7c8-451a-89ba-346ae278a66f/attributes?name=Nickname

User roles

GET /iam/account/{id}/authorities

Retrieves user roles.

Requires ROLE_ADMIN or ROLE_GM.

$ curl -s -H "Authorization: Bearer ${AT}" \
  http://localhost:8080/iam/account/80e5fb8d-b7c8-451a-89ba-346ae278a66f/authorities | jq
{
  "authorities": [
    "ROLE_GM:c617d586-54e6-411d-8e38-649677980001",
    "ROLE_USER"
  ]
}

The above example shows that the Test User is also a group manager (of group with c617d586-54e6-411d-8e38-649677980001 id).

POST /iam/account/{id}/authorities

Adds an authority to the user.

Requires ROLE_ADMIN.

$ curl -X POST -H "Content-Type: application/x-www-form-urlencoded" \
  -H "Authorization: Bearer ${AT}" -d "authority=ROLE_ADMIN" \
  http://localhost:8080/iam/account/80e5fb8d-b7c8-451a-89ba-346ae278a66f/authorities

DELETE /iam/account/{id}/authorities

Revokes user authority by specifying the query parameter.

Requires ROLE_ADMIN.

$ curl -X DELETE -H "Authorization: Bearer ${AT}" \
  http://localhost:8080/iam/account/80e5fb8d-b7c8-451a-89ba-346ae278a66f/authorities?authority=ROLE_ADMIN

Managed clients

GET /iam/account/me/clients

Retrieves information about clients owned by the currently authenticated user.

$ curl -s -H "Authorization: Bearer ${AT}" \
  http://localhost:8080/iam/account/me/clients | jq
{
  "totalResults": 1,
  "itemsPerPage": 1,
  "startIndex": 1,
  "Resources": [
    {
      "client_id": "client",
      "client_name": "Test Client",
      "redirect_uris": [
        "https://iam.local.io/iam-test-client/openid_connect_login",
        "http://localhost:9090/iam-test-client/openid_connect_login"
      ],
      "scope": "address phone openid profile offline_access read-tasks attr write-tasks email read:/ write:/",
      "created_at": 1658764288643
    }
  ]
}

Account filtering

GET /iam/account/find/{option}

Filters user information by label, e-mail, username, certificate subject or group/notingroup.

Requires ROLE_ADMIN.

Option Attribute Value
byusername username string
bylabel name string
byemail email string
bycertsubject certificateSubject URL-encoded

Examples of the available options:

  • byusername

    $ curl -s -H "Authorization: Bearer ${AT}" \
  http://localhost:8080/iam/account/find/byusername?username=test | jq
{
  "totalResults": 1,
  "itemsPerPage": 10,
  "startIndex": 1,
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:ListResponse"
  ],
  "Resources": [
    {
      "id": "80e5fb8d-b7c8-451a-89ba-346ae278a66f",
      "meta": {
        "created": "2022-07-26T13:48:35.442+02:00",
        "lastModified": "2022-07-26T13:48:35.442+02:00",
        "location": "http://localhost:8080/scim/Users/80e5fb8d-b7c8-451a-89ba-346ae278a66f",
        "resourceType": "User"
      ...
  ]
}

  • bylabel

    $ curl -s -H "Authorization: Bearer ${AT}" \
  http://localhost:8080/iam/account/find/bylabel?name=test

  • byemail

    $ curl -s -H "Authorization: Bearer ${AT}" \
  http://localhost:8080/iam/account/find/byemail?email=test.user@gmail.com

  • bycertsubject

    $ curl -s -H "Authorization: Bearer $AT" \
  http://localhost:8080/iam/account/find/bycertsubject?certificateSubject=CN%3dTest%20User%20test%40infn.it%2cO%3dIstituto%20Nazionale%20di%20Fisica%20Nucleare%2cC%3dIT%2cDC%3dtcs%2cDC%3dterena%2cDC=org

  • bygroup/{groupId}

    $ curl -s -H "Authorization: Bearer ${AT}" \
  http://localhost:8080/iam/account/find/bygroup/6a384bcd-d4b3-4b7f-a2fe-7d897ada0dd1

  • notingroup/{groupId}

    $ curl -H "Authorization: Bearer ${AT}" \
  http://localhost:8080/iam/account/find/notingroup/6a384bcd-d4b3-4b7f-a2fe-7d897ada0dd1

Group members

POST /iam/account/{id}/groups/{groupId}

Adds user to a group. It can be done directly through the IAM dashboard as explained here.

Requires ROLE_ADMIN or ROLE_GM.

$ curl -X POST -H "Content-Type: application/x-www-form-urlencoded" \
  -H "Authorization: Bearer ${AT}" \
  http://localhost:8080/iam/account/80e5fb8d-b7c8-451a-89ba-346ae278a66f/groups/c617d586-54e6-411d-8e38-649677980004

DELETE /iam/account/{id}/groups/{groupId}

Removes user from a specific group.

Requires ROLE_ADMIN or ROLE_GM.

$ curl -X DELETE -H "Authorization: Bearer ${AT}" \
  http://localhost:8080/iam/account/80e5fb8d-b7c8-451a-89ba-346ae278a66f/groups/c617d586-54e6-411d-8e38-649677980004

Group managers

GET /iam/account/{id}/managed-groups

Lists the user’s managed and not managed groups.

Requires that the user has ROLE_ADMIN or is the one represented by the {id}.

$ curl -s -H "Authorization: Bearer ${AT}" \
  http://localhost:8080/iam/account/80e5fb8d-b7c8-451a-89ba-346ae278a66f/managed-groups | jq
{
  "id": "80e5fb8d-b7c8-451a-89ba-346ae278a66f",
  "username": "test",
  "managedGroups": [
    {
      "name": "Test-001",
      "id": "c617d586-54e6-411d-8e38-649677980001",
      "description": null,
      "parent": null
    }
  ],
  "unmanagedGroups": [
    ...
  ]
}

POST /iam/account/{id}/managed-groups/{groupId}

Gives a user represented by {id} ROLE_GM privileges of the group identified by {groupId}.

Requires ROLE_ADMIN.

$ curl -X POST -H "Content-Type: application/x-www-form-urlencoded" \
  -H "Authorization: Bearer ${AT}" \
  http://localhost:8080/iam/account/80e5fb8d-b7c8-451a-89ba-346ae278a66f/managed-groups/c617d586-54e6-411d-8e38-649677980004

DELETE /iam/account/{id}/managed-groups/{groupId}

Removes a group manager from a certain group.

Requires ROLE_ADMIN.

$ curl -X DELETE -H "Authorization: Bearer ${AT}" \
  http://localhost:8080/iam/account/80e5fb8d-b7c8-451a-89ba-346ae278a66f/managed-groups/c617d586-54e6-411d-8e38-649677980004

GET /iam/group/{groupId}/group-managers

Shows the information of managers in a certain group.

Requires ROLE_ADMIN or ROLE_GM privileges of the group identified by {groupId}.

$ curl -s -H "Authorization: Bearer ${AT}" \
  http://localhost:8080/iam/group/c617d586-54e6-411d-8e38-649677980004/group-managers
[
  {
    "id": "80e5fb8d-b7c8-451a-89ba-346ae278a66f",
    "meta": {
      "created": "2022-07-26T13:48:35.442+02:00",
      "lastModified": "2022-07-26T18:19:03.786+02:00",
      "location": "http://localhost:8080/scim/Users/80e5fb8d-b7c8-451a-89ba-346ae278a66f",
      "resourceType": "User"
    },
    "schemas": [
      "urn:ietf:params:scim:schemas:core:2.0:User",
      "urn:indigo-dc:scim:schemas:IndigoUser"
    ],
    "userName": "test",
    "name": {
      "familyName": "User",
      "formatted": "Test User",
      "givenName": "Test"
    },
    ...
  }
]

Account labels

GET /iam/account/{id}/labels

Shows the user account labels.

Requires that the user has ROLE_ADMIN, ROLE_GM, or is the one represented by the {id}.

$ curl -s -H "Authorization: Bearer ${AT}" \
  http://localhost:8080/iam/account/80e5fb8d-b7c8-451a-89ba-346ae278a66f/labels
[
  {
    "prefix": "hr.cern",
    "name": "ignore"
  }
]

PUT /iam/account/{id}/labels

Adds labels to user account.

Requires ROLE_ADMIN.

$ curl -X PUT -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${AT}" -d @labels.json \
  http://localhost:8080/iam/account/80e5fb8d-b7c8-451a-89ba-346ae278a66f/labels

where labels.json is:

{
  "prefix": "hr.cern",
  "name": "ignore"
}

DELETE /iam/account/{id}/labels

Deletes an account label by specifying the label name and the label prefix (if present).

Requires ROLE_ADMIN.

$ curl -X DELETE -H "Authorization: Bearer ${AT}" \
  http://localhost:8080/iam/account/80e5fb8d-b7c8-451a-89ba-346ae278a66f/labels \
  -d name=ignore -d prefix="hr.cern"

User account expiration time

PUT /iam/account/{id}/endTime

Adds/changes the membership end time of the user. It can be done directly through the IAM dashboard by clicking on “Change membership end time” button in the user homepage.

Requires ROLE_ADMIN.

$ curl -X PUT -d @endTime.json \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${AT}" \
  http://localhost:8080/iam/account/80e5fb8d-b7c8-451a-89ba-346ae278a66f/endTime

where endTime.json is:

{
   "endTime":"2022-08-06T02:00:00.000+02:00"
}

Proxy certificate

PUT /iam/account/me/proxycert

Adds user proxy certificate. It can be done directly through the IAM dashboard by clicking on “Add managed proxy certificate” button appearing on the user homepage after uploading the X.509 certificate.

$ curl -i -X PUT -d @proxy.json \
  -H "Authorization: Bearer ${AT}" \
  -H "Content-Type: application" \
  http://localhost:8080/iam/account/me/proxycert

where proxy.json includes only the certificate_chain key:

{"certificate_chain":"-----BEGIN CERTIFICATE-----\nMIIFGT...FlCU=\n-----END CERTIFICATE-----"}

List accounts and groups

GET /iam/account/search

Shows the list of IAM accounts.

Requires ROLE_ADMIN, ROLE_GM or scim:read scope.

$ curl -s -H "Authorization: Bearer ${AT}" \
  http://localhost:8080/iam/account/search
{
  "totalResults": 254,
  "itemsPerPage": 10,
  "startIndex": 1,
  "Resources": [
    {
      "id": "73f16d93-2441-4a50-88ff-85360d78c6b5",
      "meta": {
        "created": "2022-09-21T17:20:14.034+02:00",
        "lastModified": "2022-09-21T17:20:14.034+02:00",
        "location": "http://localhost:8080/scim/Users/73f16d93-2441-4a50-88ff-85360d78c6b5",
        "resourceType": "User"
      },
      "userName": "admin",
      "name": {
        "familyName": "User",
        "formatted": "Admin User",
        "givenName": "Admin"
      },
      "displayName": "admin",
      "active": true,
      "emails": [
        {
          "type": "work",
          "value": "1_admin@iam.test",
          "primary": true
        }
      ]
    },
    ...

GET /iam/group/search

Shows the list of IAM groups.

Access granted to all IAM users or scim:read scope.

$ curl -s -H "Authorization: Bearer ${AT}" \
  http://localhost:8080/iam/group/search
{
  "totalResults": 22,
  "itemsPerPage": 10,
  "startIndex": 1,
  "Resources": [
    {
      "id": "6a384bcd-d4b3-4b7f-a2fe-7d897ada0dd1",
      "meta": {
        "created": "2022-09-21T17:20:15.478+02:00",
        "lastModified": "2022-09-21T17:20:15.478+02:00",
        "location": "http://localhost:8080/scim/Groups/6a384bcd-d4b3-4b7f-a2fe-7d897ada0dd1",
        "resourceType": "Group"
      },
      "displayName": "Analysis",
      "urn:indigo-dc:scim:schemas:IndigoGroup": {
        "parentGroup": null,
        "description": "The analysis group",
        "labels": null
      }
    },
    ...
Last modified May 4, 2023: Fix DELETE label parameters (#75) (418bcb5)