There are three authentication methods that you can use:

  • HTTP Basic authentication (IETF RFC 7617)
  • Certificate authentication (mutual TLS)
  • Custom HTTP header variables (ping.uname and ping.pwd)

When both HTTP Basic authentication and certificate authentication methods are enabled, the application can authenticate by using either authentication method.

If authentication fails, PingFederate responds with a 401 HTTP response to the application.

HTTP Basic authentication

The application encodes the user name and pass phrase together using Base64. It includes the result as the value of the Authorization header in the HTTP request.

Authorization header format:
"Authorization: BASIC " + Base64_Encode( <username> + ":" + <pass phrase> )
"Authorization: BASIC " + Base64_Encode("myportal:q6^&2dR!Vc7PtA")
"Authorization: BASIC c2FtcGxlX2lkOnNhbXBsZV9wYXNzd29yZA=="
Example HTTP request:
POST https://pf.example.com:9031/ext/ref/dropoff HTTP/1.1
Content-Length: 20
Content-Type: application/json
Authorization: BASIC c2FtcGxlX2lkOnNhbXBsZV9wYXNzd29yZA==
ping.instanceId: sample_adapter

{
  "subject":"jsmith"
}

Complete the User Name and Pass Phrase fields in the Reference ID Adapter instance configuration.

Certificate authentication

Authentication relies on a client SSL private key and the corresponding public certificate.

The application sends a request to the Reference ID Adapter endpoints using the back-channel port.

The certificate is transported during the SSL/TLS negotiation and does not appear in the HTTP request.

Example HTTP request:
POST https://pf.example.com:9032/ext/ref/dropoff HTTP/1.1
Content-Length: 20
Content-Type: application/json
ping.instanceId: sample_adapter

{
  "subject":"jsmith"
}

To use this method, complete the steps in Configuring certificate authentication.

Custom HTTP header variables

The application includes the user name and pass phrase as the value of the ping.uname and ping.pwd HTTP headers in the HTTP request.

Use this method if your application does not support Base64 encoding or certificate authentication.

Example HTTP request:

POST https://pf.example.com:9031/ext/ref/dropoff HTTP/1.1
Content-Length: 20
Content-Type: application/json
ping.uname: sample_id
ping.pwd: sample_password
ping.instanceId: sample_adapter

{
  "subject":"jsmith"
}

Complete the User Name and Pass Phrase fields in the Reference ID Adapter instance configuration.