PingID® is a cloud-based strong authentication solution that enables software applications to authenticate users according to multiple factors. This means that in addition to entering a user name and password, the user must perform another authentication step using a mobile device. This could be swiping a button on the device, or entering a one-time password that the PingID mobile app generates. Since in addition to supplying the (potentially hackable) user credentials, users must perform a physical action on their own mobile device, which is registered on the PingID platform, a much higher level of security is enforced than the user credentials alone can provide.
PingID authentication can protect both services offered to the enterprise’s customers, such as online banking, and services used by the enterprise’s employees, such as email, CRM systems.
The PingID API set consists of two web API's that enable you to access the PingID service, in order to perform the following types of functions:
This document describes version 4.9 of the PingID API. It is intended for software developers who want to integrate PingID into their own application.
These are the entities involved in the PingID authentication workflow:
Organization - A company or other type of organization using the PingID platform to protect its software services. Examples of organizations are: banks offering online services, call centers, companies that want to protect the online service their employees access, and so on.
Service Provider - A web service, whether cloud-based or installed on-site, proprietary to the organization or offered by a 3rd-party, which the organization allows its users (employees or customers) to access.
User - A consumer of the service provided by the service provider. The user may be either an employee or a customer of the organization.
The following diagram shows the entities involved in the PingID authentication workflow and the interactions between them:
To ensure the security of your users' data, PingID enforces the following security features to protect its API calls, in addition to the high security standards applied throughout the entire system:
PingID is part of Ping Identity's PingOne product suite. Before you integrate PingID into your application, your company will need to set up a PingOne account. Please visit the Ping Identity contact page to submit your contact details. A Ping Identity security expert will get in touch with you to discuss the best solution for your company’s needs.
You can also register for a PingOne developer account at https://developer.pingidentity.com/en/connect.html.
Each PingID account must have at least one user with administrator rights. In addition to managing PingID users, the administrator can edit company account details, configure PingID account settings and view statistical reports about PingID usage.
Note: There are different types of PingOne account administrators, with different sets of permissions. To act as PingID administrator, you must have the Global Administrator type. If you set up the account, you are automatically assigned the role of Global Administrator. This role has full permissions to manage and configure all aspects of the account and the admin portal, including the ability to manage all group and role assignments.
The PingID account administrator will need to download the account’s settings file. This file contains several account-specific settings, including these values that you’ll need to use when creating a PingID API request message:
|token||A unique identifier of the PingID client.|
|org_alias||The name of the PingID client organization.
|use_base64_key||A key that you’ll use to create a signature value for each message.|
For security purposes, all PingID requests are validated using the token and use_base64_key values, and rejected if these values are invalid.
Here is an example of the contents of a settings file:
#Generated by PingOne, downloaded by id= email=[firstname.lastname@example.org]
#Tue Jul 14 04:29:15 MDT 2015
To download the account settings file, the PingID account administrator must:
The administrator is prompted to save the settings file to a local folder.
In order to enable your application to call the PingID API, your PingID account administrator must configure the Enable Third Party Clients setting in the PingOne administration console.
To enable the Enable Third Party Clients setting, the PingID account administrator must:
To make a call to the PingID API, you must construct an API request token. The request token is a JSON Web Token (JWT) signed with a JSON Web Signature (JWS) which is sent to the PingID API endpoint.
A JWS consists of three components:
These three components are base64url-encoded and concatenated, with a period ('.') character between each, to form the token. This API request token is sent via an HTTP POST command to the appropriate API endpoint. The response is another JWS token that the calling application must validate and process.
Note: For more information about JWTs and signing tokens using JWS, visit: https://developer.pingidentity.com/en/resources/jwt-and-jose.html
The header consists of three parameters in a JSON structure:
|alg||The signing algorithm (must be "HS256")|
|org_alias||A unique identifier of the organization, found in the org_alias value in the settings file|
|token||A unique ID of the calling client (there can be several per organization), also found in the settings file as the token value|
An example of an API token header is below:
Note: The header is identical for all API calls described in this document.
The request token payload is a JSON object containing two child objects: a request header object (reqHeader) and a request body object (reqBody). The reqHeader object is constructed with the following parameters in the JSON:
|locale||A code indicating the caller’s preferred language. Error and status messages are returned in this language.|
|orgAlias||A unique identifier of the organization, found in the org_alias value in the settings file.|
|secretKey||A unique ID of the calling client (can be several per organization). Found in the token value in the settings file.|
|timestamp||The date and time the request was sent. The datetime format is: "yyyy-MM-dd HH:mm:ss.SSS" (SSS = 3-digit millisecond value), using the UTC timezone.|
|version||The version of the PingID API package.|
Note: The reqHeader object is identical for all API calls described in this document.
The reqBody object will vary for each API operation (see the API documentation for details).
The example below describes a request token payload that is used to add the new user "Meredith Archer" to the PingID user list:
Before sending the request token to the API endpoint, the contents must be signed using the use_base64_key retrieved from the PingID account settings file.
To create the signed token:
Create the signed data by concatentaing the base64-encoded header and payload.
<signed data> = base64UrlEncode(<header>) + "." + base64UrlEncode(<payload>)
Generate a HMAC with SHA-256 hash of the <signed data> using the use_base64_key.
<signature> = base64UrlEncode( HMACSHA256( <signed data> ,<use_base64_key> ) )
Append the signature to the signed data, with a period character ('.') beween the two values.
API request JWS = <signed data> + "." + <signature>
Note: For more information about signing a JWT, visit https://developer.pingidentity.com/en/resources/jwt-and-jose.html.
After creating the API request token, send it to the appropriate API endpoint via HTTP POST with a content type of application/json. For this example, the JWT described above will be sent to the AddUser endpoint, as follows:
POST https://idpxnyl3m.pingidentity.com/pingid/rest/4/adduser/do HTTP/1.1
The response from the API request is a similarly signed JWT as the API request token. As with the request token, the response token contains a header, a payload (consisting of a responseHeader object and a responseBody object) and the digital signature.
The API request and response are sent over a secure HTTPS channel, therefore validation of the digital signature in the response token is not mandatory. However the token may be validated by checking the digital signature using the use_base64_key value found in the PingID account settings file.
Note: For detailed information about decoding a JWS, refer to the JOSE and JWT guide at https://developer.pingidentity.com/en/resources/jwt-and-jose.html.
The response token header has the same format as the request token header. The token value and the org_alias value must match the values from your PingID account settings file.
The header also includes the algorithm used to sign the token, which is HS256.
The response payload contains a JSON structure with the results of the API operation. Although the response payload varies for each API operation, the following attributes will be returned in every response:
|clientData||The value sent in the request’s clientData field.|
|errorId||A numeric error code (see error codes for more information)|
|errorMsg||A textual description of the error, if there was one.|
|uniqueMsgId||A unique ID for the response message. This is logged and used to track the specific transaction for troubleshooting purposes.|
An example of a successful response to the AddUser operation is included below: