Skip to content

Authorization Service API

The Authorization Service API is an OAuth2 protected API used by CERN's Identity Management Infrastructure to manage Identities, Groups, Roles, Applications and more. You may also want to use it, for example to:

  • Query Groups
  • Search for Identities
  • Programmatically create Applications, and Roles

API Endpoints

You can see all the available API endpoints, and test the Authorization Service API using the Swagger Interface Through the API you can manage different resources such as identities, groups, accounts etc. For more details on the different resources and their attributes check here.

How to use the Authorization Service API

For most needs we recommend creating an OIDC client and using your Client Credentials to query the Authorization Service, follow this Guide for API Access. If you want to query the Authorization Service on behalf of a user accessing your own application, i.e. OIDC delegation, follow this Guide for Token Exchange. The Authorization Service's clientID is authorization-service-api, which should be used as the aud or audience in your requests.

Once you have an access token for the Authorization Service, you can include it in the Authorization header of an HTTP request to query the API:

### Call the Authorization Service API using your the exchanged token
API_RESPONSE=$(curl \
    -X GET "https://authorization-service-api.web.cern.ch/api/v1.0/Identity/my" \
    -H "Accept: */*" \
    -H "Authorization: Bearer $API_ACCESS_TOKEN" )
echo $API_RESPONSE

Querying with pagination

For the case that you need to query the API to receive back a big amount of entities you'll need to do it with pagination (receive them in chunks).

For example let's assume one wants to get back all the groups. This means that they'll need to send a post request to the endpoint https://authorization-service-api.web.cern.ch/api/v1.0/Group.

The response they'll receive will contain the following payload: 

{
  "pagination": {
    "total": 72272,
    "offset": 0,
    "limit": 1000,
    "next": "/api/v1.0/Group?token=eyJJZCI6IjA4ZDc4&limit=1000",
    "links": {
      "first": "/api/v1.0/Group?offset=0&limit=1000",
      "previous": null,
      "current": "/api/v1.0/Group?offset=0&limit=1000",
      "next": "/api/v1.0/Group?offset=1000&limit=1000",
      "last": "/api/v1.0/Group?offset=72000&limit=1000"
    },
    "token": "eyJJZCI6IjA4ZDc3OWE2LTE3YjYtOTAzNy01MzQzLTc4"
  },
  "delta": null,
  "request_id": null,
  "message": null,
  "data": [
    {
      "groupIdentifier": "some group" 
    } 
  ....

The pagination field contains all the important information that you need.

  1. The field limit describes the number of groups contained in each page. By default it's 1000 but one can ask up to 5000 groups per page. If you want to set it to a different value you can define it in your initial request like this: https://authorization-service-api.web.cern.ch/api/v1.0/Group?limit=500.
  2. The field total describes the total amount of groups that are stored in the DB.
  3. The field links contains all the links to which the user should post another request to get the the next chunk of groups. In more detail:
    • next: gives the user the next page of groups. If it's null it means there are no more pages to retrieve.
    • previous: gives the user the previous pages of groups. If it's null it means that the user is in the first page.
    • current: link to the current page.
    • last: last page of groups.

Requesting Permissions

Due to privacy factors, certain endpoints require permission to query.
See the "defining the permissions scheme" topic for more information.

Querying computed fields

When making GET requests, for example, when reading an Identity, you will get a default object containing most of the available fields.

GET https://authorization-service-api.web.cern.ch/api/v1.0/Identity/aaguadoc 

{
  "request_id": null,
  "message": null,
  "data": {
    "owner": null,
    "supervisor": null,
    "primaryAccountEmail": null,
    "type": "Person",
    "upn": "aaguadoc",
    "displayName": "Asier Aguado Corman",
    "personId": "806747",
    "supervisorId": "922d1465-59d5-4789-a468-58291c08c812",
    "source": "cern",
    "unconfirmed": false,
    "unconfirmedEmail": null,
    "externalEmail": "asieraguadoc@gmail.com",
    "primaryAccountId": "a8293927-4e84-4090-be61-0152381c7a9a",
    "uid": 96222,
    "gid": 2763,
    "resourceCategory": "Personal",
    "reassignable": false,
    "autoReassign": false,
    "blocked": false,
    "securityIssues": false,
    "blockingReason": null,
    "blockingTime": null,
    "blockingDeadline": null,
    "expirationDeadline": null,
    "ownerId": null,
    "id": "4499f2b8-2bcd-4d0a-bf81-73c119fb7bf9",
    "room": "003",
    "floor": "R",
    "building": "28",
    "lastName": "Aguado Corman",
    "birthDate": "1993-02-01T00:00:00",
    "cernGroup": "CDA",
    "firstName": "Asier",
    "activeUser": true,
    "telephone1": "65228",
    "cernSection": "IC",
    "description": "CERN - IT/CDA",
    "cernPersonId": "806747",
    "instituteName": "CERN",
    "cernDepartment": "IT",
    "eduPersonUniqueID": "4c84ca68be3a4010933b16caf1e030fe",
    "instituteAbbreviation": "CERN",
    "preferredCernLanguage": "EN"
  }
}

You will probably notice that some fields in this default object are null. Some of the fields have an actual null value (e.g. blockingDeadline or expirationDeadline), but others are fields that belong to other child objects, which are not computed by default to make the API more efficient. If you need any of these fields, you can specify them in the request using the field parameter.

For example, for getting primaryAccountEmail:

https://authorization-service-api.web.cern.ch/api/v1.0/Identity/aaguadoc?field=primaryAccountEmail&field=upn

{
  "request_id": null,
  "message": null,
  "data": {
    "primaryAccountEmail": "asier.aguado@cern.ch",
    "upn": "aaguadoc",
    "id": "4499f2b8-2bcd-4d0a-bf81-73c119fb7bf9"
  }
}

As you can see in the example, when specifying fields in the request all the others are ignored in the response (even the default ones). If you also want to get them (e.g. upn) you can include them in your request as well.