Getting started


Authentication and authorization

Requesters can authenticate using any of two authentication types, and the requester may have either a privileged or unprivileged identity that determines the activity scope.

Authentication types

The Directory REST API supports the following authentication types:

  • Basic authentication

    Requests are authenticated using a username and password or an encoded API token contained in the Authorization header. The user credentials can be collected interactively from the user, or they can represent the client itself.

    Here is a sample of a request using an API token:

    GET /directory/v1/uid=lindajones,ou=people,dc=example,dc=com HTTP/1.1
    Authorization: Basic dWlkPXVzZXIuMCxvdT1wZW9wbGUsZGM9ZXhhbXBsZSxkYz1jb206cGFzc3dvcmQ=
  • Bearer token

    Requests are authenticated using an access token contained in the Authorization header. The access token is obtained through an authorization server, such as PingFederate. Here is a sample:

    GET /directory/v1/uid=lindajones,ou=people,dc=example,dc=com HTTP/1.1
    Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtp...

When bearer token authentication is used, the access token used must include a scope that the directory service is configured to accept. Additionally, the directory service may be configured to require that the access token include a specific audience claim.

Access control

Requests to the Directory REST API with a given user is identical to making an LDAP request with the same user, which are subject to the same ACI restrictions. Authenticated users can have full or partial access to the Directory service based on the permissions allowed for that user.

Test your authorization type

The following information illustrates how to construct a typical API request.

Create the API request header

The API request header contains the authentication information you must provide to make a call to any Directory REST API resource. The Authorization parameter takes the user credentials or the full bearer token as its value, which contains the authorization information needed to access the requested resource.

The following sample shows the API request header (-H 'Authorization: Bearer) with a base64url-encoded bearer token as its parameter value.

curl -X "GET" "https://<server>/directory/v1/{dn}" \
     -H 'Content-Type: application/json' \
     -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...'

This request header also shows an additional parameter of note:

  • Content-Type

    In the header of a PATCH, PUT, or POST request, this parameter identifies the media type of the request data sent to the server. For most Directory API calls, the Content-Type is application/json.

Create the API request body

The API request body for POST, PATCH, or PUT requests provides the attribute values needed to complete the create or update operation. For example, to update an LDAP entry, the PUT operation requires values for the attr1 and attr2 attributes in the request body:

{
  "attr1": "value1",
  "attr2": "value2"
}

Run the API test

You can use the Directory REST API to return a specified record from the directory.

The following sample shows the GET /directory/v1/{dn} operation to return a specific directory record and its associated attributes. The distinguished name {dn} of the entry is specified in the request URL.

curl -X GET "/directory/v1/uid=lindajones,ou=people,dc=example,dc=com" \
-H "Content-type: application/json" \
-H "Authorization: Bearer jwtToken"

In the request header, the Bearer jwtToken value is your full base64url-encoded token generated by the authentication service. If your token is valid, the API request returns a 200 OK message, and the response data shows the directory data for Linda Jones.

This GET request does not require a request body. The response returns the entry data.

{
  "_dn": "uid=lindajones,ou=people,dc=example,dc=com",
  "objectClass": [ "top", "ubidPerson" ],
  "uid": ["lindajones"],
  "cn": ["Linda Jones"],
  "sn": ["Jones"],
  "ubidEmailJSON": [
    {
      "type": "work",
      "value": "ljones@example.com"
    },
  ],
  "_links": {
    "schemas": [
      {
        "href": "https://ds.example.com/directory/v1/schemas/ubidPerson"
      }
    ],
    "self": {
      "href": "https://ds.example.com/directory/v1/uid=lindajones,ou=people,dc=example,dc=com"
    }
  }
}