PingFederate Server

Device authorization endpoint

The device 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.

The OAuth 2.0 Device Authorization Grant defines the device authorization endpoint. Based on the specification, the device sends a device authorization request to PingFederate, the authorization server (AS), at its device authorization endpoint.

Per OAuth specifications, this endpoint accepts only the HTTP POST method.

Endpoint: /as/device_authz.oauth2

The required Content-Type value is application/x-www-form-urlencoded. The following table describes parameters for this endpoint.

Parameter Description

client_id

A unique identifier the client provides to the resource server to identify itself. This identifier is included with every request the client makes

scope

(Optional)

The scope of the access request expressed as a list of space-delimited, case-sensitive strings.

Scopes can also be constrained on a client-to-client basis. For more information about scopes, see Scopes and scope management.

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

Example

Example request

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

client_id=df_client

Example

Response codes and example responses

200 - Success

HTTP/1.1 200 OK

...
{
    "user_code": "YYD6-CD4T",
    "device_code": "4EHsIngavzIPvvqMlFgQlseTCsH7EpU75f9yGvj60T",
    "interval": 5,
    "verification_uri_complete": "https://www.example.com/as/user_authz.oauth2?user_code=YYD6-CD4T",
    "verification_uri": "https://www.example.com/as/user_authz.oauth2",
    "expires_in": 600
}

400 - Bad Request

HTTP/1.1 400 Bad Request

...
{
    "error_description": "The requested scope(s) must be blank or a subset of the provided scopes.",
    "error": "invalid_scope"
}

401 - Unauthorized

HTTP/1.1 401 Unauthorized

...
{
    "error_description": "Invalid client or client credentials.",
    "error": "invalid_client"
}

OAuth client identification and authentication

The authentication requirement of this endpoint depends on the client authentication method configured for the clients.

Authentication method Parameters

Client secret

Clients can present their client identifier and client secret using the HTTP Basic authentication scheme, where the client identifier is the username, and the client secret is the password.

Clients can provide credentials using the request parameters client_id and client_secret.

This is a sensitive parameter. To avoid recording it in web server logs, only pass in this parameter with the HTTP POST method in the message body, or through the HTTP Basic authentication scheme.

Client certificate

Clients must present their client certificate for mutual TLS authentication. The issuer and the subject distinguished name (DN) of the client certificate must match values configured for the clients.

Private key JWT or Client Secret JWT

Clients must include request parameters client_assertion_type and client_assertion in the message body of their requests.

client_assertion_type

The value describes the format of the assertion as defined by the authorization server. For the private_key_jwt and client_secret_jwt client authentication methods, the value is urn:ietf:params:oauth:client-assertion-type:jwt-bearer.

client_assertion

The value is the authentication token.

Example

...
client_assertion_type=
urn%3Aietf%3Aparams%3Aoauth%
3Aclient-assertion-type%3Ajwt-bearer&
client_assertion=
eyJhbGciOiJSUzI1NiIs...LbSWi1YO-TILOd4L7ZCg&
...

For readability, line breaks are inserted and the authentication token is truncated.

Learn more about the private_key_jwt and client_secret_jwt client authentication methods, in Client Authentication and Using Assertions for Client Authentication.

None

Clients must pass in the client_id parameter in a query string or the message body to identify themselves.