Agentless Integration Kit

Authentication methods

When picking up and dropping off attributes, your application has to authenticate with PingFederate. There are four authentication methods that you can use:

  1. Bearer token authentication (IETF RFC 6750)

  2. Certificate authentication (mutual TLS)

  3. Custom HTTP header variables (ping.uname and ping.pwd)

  4. HTTP Basic authentication (IETF RFC 7617)

If you enable both HTTP Basic authentication and certificate authentication methods, the application can authenticate with either.

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

Bearer token authentication

The application depends on the PingFederate authorization server for authentication and authorization. If the adapter is configured for bearer token-based authentication, the resulting OAuth access token is included in the Authorization header of the HTTP requests for the pickup and drop-off APIs.

Authorization header format: 
"Authorization: Bearer " + <access token>
Example HTTP request: 
POST https://pf.example.com:9031/ext/ref/dropoff HTTP/1.1
Content-Length: 20
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6ImsxIiwicGkuYXRtIjoiNnBhYyJ9.eyJzY29wZSI6WyJvcGVuaWQiXSwiYXV0aG9yaXphdGlvbl9kZXRhaWxzIjpbXSwiY2xpZW50X2lkIjoiYWNfb2ljX2NsaWVudCIsImFnaWQiOiJhNjdxUTJnYXBVb3pKc2RUclp6U2VYVEh2T2tpTk01WCIsImp0aSI6IkNOYlp0UUFCZE1kaWVUVHJQR3h0UTAiLCJVc2VybmFtZSI6ImpvZSIsIk9yZ05hbWUiOiJQaW5nIElkZW50aXR5IENvcnBvcmF0aW9uIiwiZXhwIjoxNzQwMTc2OTMyfQ.YwjgJNKAVuwP9qUAPFyE9ag-g0NhLzC03oV0I4-PxMZWffSAn6UhvPyBwlAQ1KH0whdbQm84oSM93u2gffyF9qtf-34PycLIbhiR7syGS-uaTGSnGVKIoOrNp5GeKJ6gBA48sInSKzO9LnqTzvIeN-vDpU3SVb16EBCx5UjJRIHxTPHonzQLld7Au_FAKGpG6eQfzUbPt0DvJyealzWLdBsn4VgdegtZJNQbnF9UhmgS5ead2wn_skAG-g_dekkePUN44LMd5B5Yf0V-xSAJmU8LYMqyB8ZedLwH-9ObUKig4kJZwGGlsGyGALVnU9f60nOfXLUZSPb8H6YGmoy-Fw
ping.instanceId: sample_adapter

{
"subject":"jsmith"
}

To use this method, complete the Access Token Manager, Allowed Bearer Access Token Client IDs, and Required Bearer Access Token Scopes fields in the Reference ID Adapter instance configuration. Learn more in Reference ID IdP Adapter settings reference and Reference ID SP Adapter settings reference.

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

To use this method, complete the User Name and Pass Phrase fields in the Reference ID Adapter instance configuration. Learn more in Reference ID IdP Adapter settings reference and Reference ID SP Adapter settings reference.

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

To use this method, complete the User Name and Pass Phrase fields in the Reference ID Adapter instance configuration. Learn more in Reference ID IdP Adapter settings reference and Reference ID SP Adapter settings reference.