Authentication Endpoint

The authentication endpoint can be configured to be any URI you would like. The HTTP inputs and outputs also vary depending on the protocol plug-in that is configured.

Because the actual URI can vary, example/auth is used below as a placeholder.

PingFederate Protocol Plug-in

With PingFederate, there are two ways of initiating an authentication request:

  1. Direct Access
    An authentication transaction can begin by sending the request directly to the Authentication Service. (This is the preferred model, as certain parameters cannot be provided using the indirect access model.) You can think of direct access like IdP-initiated SSO in SAML if you are familiar with that message exchange.
  2. Indirect Access
    An authentication transaction can also begin by sending a request to PingFederate (e.g., a SAML authentication request or a request to PingFederate’s OAuth authorize endpoint). In this case, users will be redirected to the Authentication Server after first hitting PingFederate. You can think of indirect access as SP-initiated SSO in SAML or the flow that you would find in WS-Federation and OAuth where communication is initiated with the SP/RP.

Direct Access

When using the PingFederate protocol plug-in and the direct access interaction mode, the authenticate endpoint will accept the following parameters:

GET /example/auth

Initiates the interactive authentication process for an end user where the PingFederate protocol plug-in is used to handle the incoming message. (Line breaks are added for readability only.)

Request:

GET /example/auth?client_id=abc&state=123&acr=html1&acr=html2&auth_fresh=500&forceAuthN=true HTTP/1.1
Host: localhost
Cookie: _authnSSO ...

Response:

HTTP/1.1 200 OK
Content-Type: text/html

...
Query Parameters:
 
  • client_id – The identifier of the OAuth client that initiated the user authentication process
  • acr – The requested Authentication Class Context Reference (ACR) of a configured authenticator that the user may login with
  • state – An opaque token that is to be used by the OAuth client to identify itself when receiving the response from the PingFederate OAuth server
  • auth_fresh – An non-negative integer value indicating the number of seconds since the user last logged in for which SSO should be allowed. If the time at which the user previously logged in is before the current time minus this value, the SSO cookie will not be sufficient and the user will have to login anew
  • forceAuthN – A boolean flag indicating that the user should be required to login regardless of whether or not they have an SSO cookie. If true, the user will unconditionally be required to login, irrespective of any previously saved SSO state. Using this flag is effectively the same as sending an auth_fresh value of 0.
Status Codes:
  • 200 OK – The HTML of the list of configured authenticators, the default one, or a specific one depending
Request Headers:
 
  • Cookie – _authnSSO The previously set SSO cookie that may allow the user to be automatically logged in

Indirect Access

When using the PingFederate protocol and routing authentication requests through PingFederate rather than directly through the Authentication Service, the authentication endpoint will accept the following parameters:

POST /example/auth

Initiates the interactive authentication process for an end user where the PingFederate protocol plug-in is used to handle the incoming message. (Line breaks are added for readability only.)

Request

POST /example/auth HTTP/1.1
HOST: localhost
Cookie: _authSSO ...
Content-Type: application/x-www-form-urlencoded

resumePath=...
Form Parameters:
 
  • resumePath – The URI where the Authentication Service should redirect the user to after authentication.

Note

The resumePath will not be a complete URL. The protocol, server name, and port will be take from the configuration of the PingFederate protocol plug-in.

Status Codes:
  • 200 OK – The HTML of the list of configured authenticators, the default one, or a specific one depending
Request Headers:
 
  • Cookie – _authnSSO The previously set SSO cookie that may allow the user to be automatically logged in