Configuring OAuth 2.0 Device Authorization Grant

Overview

The OAuth 2.0 Device Authorization Grant is designed for devices that are connected to the internet but lacks a browser to perform a user agent based authorization during an authorization flow. It enables devices such as TVs, printers to obtain user authorization to access a protected resource by using a user agent on a separate device.

The authorization flow is also referred to as device flow.

OAuth 2.0 Device Authorization Grant is an OAuth 2.0 extension that enables devices with no browser or limited input capability to obtain an access token.

Configuring provider.yml

The definition configuration defines a new grant_type urn:ietf:params:oauth:grant-type:device_code.
The definition configuration defines a set of device_flow_settings.

Configuration	Description	Default value
device_flow_polling_interval_in_secs	Polling interval in seconds	5 seconds
device_flow_codelifetime_in_secs	Validity of the device code in seconds	300 seconds
device_flow_usercode_length	Length of the user code. Has to be set to a value greater than 6	6
device_flow_usercode_charset	Character set for user code, should be characters that are unique and greater than the code length	ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789
enforce_clientauth_device_authorize	To enforce client authentication at the device authorization endpoint	true

# Copyright contributors to the IBM Security Verify Access OIDC Provider Resources project
version: 24.08
logging:
  level: debug
definition:
  id: 1
  name: OIDC Definition
  grant_types:
    - authorization_code
    - password
    - client_credentials
    - implicit
    - refresh_token
    - urn:ietf:params:oauth:grant-type:token-exchange    
    - urn:ietf:params:oauth:grant-type:jwt-bearer 
    - urn:ietf:params:oauth:grant-type:device_code    
  pre_mappingrule_id: isvaop_pretoken                       # Pre-Token mapping rule ID.
  post_mappingrule_id: isvaop_posttoken  
  base_url: https://isvaop.ibm.com:445/isvaop
  token_settings:                                           # Token Settings
    issuer: https://isvaop.ibm.com                          # OP's issuer URI.
    signing_alg: PS256                                      # Signing algorithm for ID token generated.
    signing_keystore: isvaop_signing                        # Signing keystore name.
    signing_keylabel: jwtsigning                            # Signing key label.
  device_flow_settings:
    device_flow_polling_interval_seconds: 10
    device_flow_codelifetime_seconds: 300
    device_flow_usercode_length: 7
    device_flow_usercode_charset: 'ABCD1234'
    enforce_clientauth_device_authorize: true
  attribute_map:                                            # Attribute mapping to resolve claims. also refer to attributesources.yml
    surname: surname  
  
server:
  ssl:
    key: ks:isvaop_keys/httpserverkey
    certificate: ks:isvaop_keys/httpservercert
jwks:
  signing_keystore: isvaop_signing
secrets:
  obf_key: "ENC:iUt+3MzCntxSL2FPTUuJqER79UaiRSApMz3cbgJm4yzuiv6H7KN8ADsamX6+Qre1oTsATjnb1bJ0Lmi7WWfxWeGT477yqqvgVayFlCDIFzZeNkdINjASfTE3B+/3Sm9YjIYuWtZdySiXeydhJXSiOGU9osdA9g2BZXR4eMrXNutCuaSvFH6MY+TyOH5q15vy6vEWOebJQHrnug0A8rN6NF8G8XaxCe/+yqH57jJpdhm0N7iUydIYOBOQ1wDgCc8nRMWkQqlkcRhDZvLLAIlhoshYvo06ubyryt8/vv/0AvTLq9AIiQoL8CtYLr+SNZlzWe4CnHYZdO9S+AIrUOVORw=="
  enc_key: "@keys/private.pem"

Configuring a confidential client

Enable a new grant type called urn:ietf:params:oauth:grant-type:device_code.
Since it is a confidential client set token_endpoint_auth_method to client_secret_post.

# Copyright contributors to the IBM Security Verify Access OIDC Provider Resources project
clients:  
  - client_id: client01deviceflow
    client_secret: "OBF:U2FsdGVkX19iBhlwc53QkybjO6RjFHhSbz4VRudYHA="                                            # Client secret that is used for client authentication and/or JWT signing/encryption. `OBF:` indicates obfuscated string.
    client_name: TV Console                                                                              # Name of the client.
    client_id_issued_at: 1642399207                                                                             # Timestamp (in seconds) from when the client is created.
    enabled: true                                                                                               # Set to `true` to enable this client
    grant_types:                                                                                                # Grant type that the client is allowed to use at the token endpoint.
      - authorization_code
      - password
      - client_credentials
      - implicit
      - refresh_token
      - urn:openid:params:grant-type:ciba
      - urn:ietf:params:oauth:grant-type:token-exchange 
      - urn:ietf:params:oauth:grant-type:jwt-bearer
    response_types:                                                                                             # Response type that the client is allowed to use at the authorization endpoint.
      - code id_token
      - code
      - code token
      - none
      - code token id_token
    redirect_uris:                                                                                              # Redirection URI strings for use in redirect-based flows such as the authorization code and implicit flows.
      - https://www.rp.com/redirect
    request_uris:                                                                                               # Request URIs that are pre-registered by the Relying Party for use at the OIDC Provider.
      - https://www.rp.com/request/test.jwt
    scopes:                                                                                                     # A list of scope values that the client can use when requesting access tokens.
      - cdr:registration
      - openid
      - profile
    jwks_uri: https://www.rp.com/oidc/endpoint/default/jwks                                                    
    id_token_signed_response_alg: PS512                                                                         
    token_endpoint_auth_method: client_secret_post

Initiating a device authorization request

The TV console client initiates a device_authorization request.

--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id=client01deviceflow' \
--data-urlencode 'client_secret=asfasdfawqdewq'

Client authentication is set to client_secret_post, hence client_id and client_secret are sent in the post payload.
Response

{
    "device_code": "YZiWfi7VRurn7_xv3Yk1zn45Qa3KegWHg-hZcK9es74.bi8TlAok2_9EBnTSOA0mTMX47Wo23ewQSuGIJJtxFpEfkYGvk15DbkoCVxocn8gZAqbTrm6l8GzN6mE7ZJIWDA",
    "expires_in": 300,
    "interval": 5,
    "user_code": "OLZYDQT",
    "verification_uri": "https://isvaop.ibm.com:445/isvaop/oauth2/user_authorization",
    "verification_uri_complete": "https://isvaop.ibm.com:445/isvaop/oauth2/user_authorization?user_code=OLZYDQT"
}

📘
Note
To run device flow, set the user_authorize endpoint to the ACL at Web reverse proxy to anyauth.

User authorization

The end user then launches the verification_uri, and provides the user_code that it receives.
Optionally the verification_uri_complete might be displayed on the TV console as a QR Code.
The user may be asked for consent based on the consent_prompt: ALWAYS_PROMPT.

Polling the token endpoint

The TV console polls the token endpoint to check if the user has authorized the device code.
The polling interval determines the frequency with which token endpoint is called.

curl --location 'https://isvaop.ibm.com:445/isvaop/oauth2/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id=client01deviceflow' \
--data-urlencode 'client_secret=asfasdfawqdewq' \
--data-urlencode 'grant_type=urn:ietf:params:oauth:grant-type:device_code' \
--data-urlencode 'device_code=YZiWfi7VRurn7_xv3Yk1zn45Qa3KegWHg-hZcK9es74.bi8TlAok2_9EBnTSOA0mTMX47Wo23ewQSuGIJJtxFpEfkYGvk15DbkoCVxocn8gZAqbTrm6l8GzN6mE7ZJIWDA'

If the device code is not authorized a authorization_pending error code is received.
Response

{
    "error": "authorization_pending",
    "error_description": "The user has not authorized the request."
}

If the client is polling the token endpoint more frequently than the defined interval slow_down error code is received.

{
    "error": "slow_down",
    "error_description": "The device made an attempt within [5] seconds. This request will not be processed."
}

If the device code is authorized successfully, tokens are returned as a part of response.

{
    "access_token": "dlDKljQrSlBjyTziK0x00XTKG50T_gG2uI9MfWEz3wU.qo_7P4X0qmek2f5G5GXs3UirfeBOfxWpdK8vv7B-phAceUONCC0a3b7Wkpc0ogggRd1ojtXvDEXOQWeRD92-3g",
    "expires_in": 7199,
    "refresh_token": "ukO8SCM8WBxj8cJpmEVzS8ktT0yHdXsdU40B85KhbUM.vx7EoWxAIpYoASSoG4sTMHngA9bnIgcDvdYKaoRhvzyenzigXr0nH25F3ckOOiZiG8FohLFRqmp6fka2kCWLbg",
    "scope": "openid",
    "token_type": "bearer"
}

Overview

Configuring provider.yml

Configuring a confidential client

Initiating a device authorization request

📘Note

User authorization

Polling the token endpoint

📘
Note