The OAuth 2.0 Device Authorization Grant specification 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 specification, the device sends a device authorization request to PingFederate, the authorization server (AS), at its device authorization endpoint.

Note:

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

Endpoint: /as/device_authz.oauth2

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

Parameter Description
client_id A unique identifier the client provides to the resource server (RS) 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.

Scope values are globally defined on the OAuth Server > Scope Management screen. Scopes can also be constrained on a client-to-client basis. For detailed information about scopes, see Scopes and scope management.

Both the request and the response follow the specification.

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

client_id=df_client
Response codes and sample responses
  • 200 - Success; for example: 
    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; for example: 
    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; for example: 
    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.

Alternatively, clients can provide credentials using these request parameters: client_id and client_secret.

Important:

This is a sensitive parameter. To avoid recording it in web server logs, we recommend to only pass in this parameter (via the HTTP POST method) in the message body or through the use of the HTTP Basic authentication scheme, instead of in a query string.
Client certificate Clients must present their client certificate for mutual TLS authentication. The issuer and the subject DN of the client certificate must match values configured for the clients.
Private key 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 client authentication method, 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&
...
Note:

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

For more information about the private_key_jwt client authentication method, see Client Authentication in the OpenID Connect specification (openid.net/specs/openid-connect-core-1_0.html#ClientAuthentication) and Using Assertions for Client Authentication in RFC7521 (tools.ietf.org/html/rfc7521#section-4.2).
None Clients must pass in the client_id parameter in a query string or the message body to identify themselves.