PingFederate Server

User authorization endpoint

The user authorization endpoint allows a user to grant authorization to a device client using a browser on a second device, such as a smart phone or a computer.

Based on the OAuth 2.0 Device Authorization Grant specification, the user goes to the user authorization endpoint of the PingFederate authorization server (AS) to complete the authorization process.

This endpoint accepts the HTTP GET and POST methods.

Endpoint: /as/user_authz.oauth2

The following table describes parameter for this endpoint. The required Content-Type value is application/x-www-form-urlencoded when transmitting through the HTTP POST method.

Parameter Description

user_code

(Optional)

This value represents the activation code.

Both the request and the response follow the OAuth 2.0 Device Authorization Grant.

Example request

POST /as/user_authz.oauth2 HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: www.example.com
...

user_code=QQWP-TJ6B

Subsequent responses

Phase 1: Activation code verification

If the verification request does not include an activation code, PingFederate returns the Connect a device (user code prompt) page, prompting the user to enter the activation code shown by the device.If the verification request includes an activation code, PingFederate returns the Connect a device (pre-populated user code prompt) page, prompting the user to confirm the activation code from the verification request matches the activation code shown by the device. PingFederate skips this step if the Bypass Activation Code Confirmation option is enabled globally or individually for that invoking client.PingFederate validates the activation code, prompts the user to enter another activation code if it is invalid, or moves to the next phase.

Phase 2: Authentication

PingFederate prompts the user to fulfill the authentication requirements based on OAuth grant mapping configurations and authentication policies.If the user fulfills the authentication requirements, PingFederate moves to the next phase; otherwise it returns an error message to the user.

Phase 3: Authorization

PingFederate returns the Request for Approval page, prompting the user to approve or deny the requested scopes. PingFederate skips this step if the Bypass Authorization Approval option is enabled globally or individually for that invoking client and the user has granted authorization for the requested scopes previously.PingFederate returns the Connect a device (result) page to the user. The message reflects the authorization status.If the user approves the requested scopes, the next time the device sends a device access token request to PingFederate at its token endpoint, PingFederate returns an access token to the device.When an error occurs, PingFederate returns 400 Bad Request in response to the device access token request.

Example of 400 Bad Request

HTTP/1.1 400 Bad Request

...
{"error_description":"Authorization request is denied","error":"access_denied"}
HTTP/1.1 400 Bad Request

...
{"error_description":"Device code not found, expired or invalid","error":"invalid_grant"}
HTTP/1.1 400 Bad Request

...
{"error_description":"The authorization request has expired.","error":"expired_token"}