Getting Started

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=
[source]
```
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...
[source]
```
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.

You can define ACIs in PingDirectory that map to specific scopes. When users make requests to Directory REST API endpoints using OAuth 2.0 bearer tokens that include configured scopes, PingDirectory can apply the ACIs associated with those scopes and grant the appropriate permissions.

Access control

To help isolate access to admin credentials in authentication workflows, you can use OAuth scopes to enforce access control instructions (ACIs) for users authenticating to specific Directory REST API endpoints.

Invoking ACIs using OAuth scopes applies to all REST API endpoints except for the following:

GET /directory/v1/
GET /directory/v1/schemas
GET /directory/v1/schemas/{schema}

Making requests to the Directory REST API with a given user is similar to making an LDAP request with the same user and is 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. In other words, scopes are granted dynamically, and are not explicitly stated in the bearer token. The client sending the bearer token in their request is granted permissions by the access token validator at the time of the request.

To enable this feature, define the ACIs to include the desired OAuth scopes. The following example allows all authenticated users with the OAuth scope example:scope to perform the Get Password Quality Requirements extended operation:

(extop="1.3.6.1.4.1.30221.2.6.43")(version 3.0; acl "Extended op permissions for get password quality requirements"; allow (read) oauthscope="example:scope";)
[source]

Learn more in Managing the Directory REST API and Using OAuth scopes for ACI rules with the REST API in the PingDirectory admin guide.

For security reasons, the PingDirectory REST API never returns the userPassword or authPassword properties in a response. For example, if you set a user’s password using PUT with "userPassword": ["passw0rd"], the response does not show the userPassword property or its value. Likewise, if you run a GET request with includeAttribute = userPassword, the response does not include the userPassword property or its value.

Create the request

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

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...'
[source]

The request header also shows an additional parameter or 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.

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"
}

PingDirectory API Reference