WireMock API Device Authorization Flow

Enterprise customers may wish to interact with the WireMock Cloud API from their own clients using OAuth 2.0. WireMock Cloud supports the OAuth 2.0 Device Authorization Flow for these customers.

Requirements

You will need to have requested the creation of a new OAuth Client by WireMock Cloud. You will need to tell us:

The maximum time you allow between interactions before the user has to reauthenticate
The maximum total time you allow between authentications, eve if the user is regularly interacting

Inputs

{client_id}: The OAuth client (in Auth0, the Application id) provided by WireMock Cloud

Initiate the Client

request

GET https://login.wiremock.cloud/.well-known/openid-configuration
Accept: application/json

returns:

`discover_urls`

{
  "token_endpoint": "{fully_qualified_url}",
  "device_authorization_endpoint": "{fully_qualified_url}",
  "revocation_endpoint": "{fully_qualified_url}"
}

Initiate the Device Authorization Flow

request

POST {discover_urls.device_authorization_endpoint}
Content-Type: application/x-www-form-urlencoded

client_id={inputs.client_id}&audience=https%3A%2F%2Fapi.wiremock.cloud&scope=openid+email+offline_access

returns:

`device_authorization`

{
  "device_code": "{random_value}",
  "user_code": "{legible_random_value}",
  "verification_uri": "{fully_qualified_url}",
  "expires_in": 900,
  "interval": 5,
  "verification_uri_complete": "{fully_qualified_url}"
}

expires_in and interval are values in seconds.

Pass control to the user to authenticate

Something like this should be rendered:

Attempting to automatically open the authentication page in your default browser.

Code: {device_authorization.user_code}

If the browser does not open or you wish to use a different device to authorize this request, open the following URL:

{device_authorization.verification_uri_complete}

Waiting for login...

if possible, {device_authorization.verification_uri_complete} should be opened automatically in the user’s browser.

Poll for successful authentication

Every {device_authorization.interval} seconds until {device_authorization.expires_in} seconds have passed you poll as so:

request

POST {discover_urls.token_endpoint}
Content-Type: application/x-www-form-urlencoded

client_id={inputs.client_id}&device_code={device_authorization.device_code}&grant_type=urn:ietf:params:oauth:grant-type:device_code

You should be returned one of these two responses:

response

HTTP/2 403 Forbidden
Content-Type: application/json

{
  "error": "authorization_pending",
  "error_description": "User has yet to authorize device code."
}

which means “poll again in {device_authorization.interval} unless {device_authorization.expires_in} has passed” or

`token_response`

response

HTTP/2 200 OK
Content-Type: application/json

{
  "access_token": "{access_token}",
  "token_type": "{token_type}",
  "expires_in": 300,
  "refresh_token": "{refresh_token}",
  "id_token": {id_token}
}

You can then interact with the API using this request header: Authorization: {token_response.token_type} {token_response.access_token}

Refresh Tokens

WireMock access tokens are JWTs, and cannot be revoked. Consequently they are short-lived (sub 10 minutes). In order to avoid having to authenticate regularly, the client may exchange a refresh token (which can be revoked) for a new access token. A refresh token, once used, becomes invalid - a new one is returned along with the new access token. Any attempt to use an invalid refresh token will also invalidate the current valid refresh token, forcing a reauthentication. Refresh tokens can be explicitly revoked on logout.

Exchanging a refresh token for a new access token

request

POST {discover_urls.token_endpoint}
Content-Type: application/x-www-form-urlencoded

client_id={inputs.client_id}&refresh_token={token_response.refresh_token}&grant_type=refresh_token

returns

`token_response`

{
  "access_token": "{access_token}",
  "token_type": "{token_type}",
  "expires_in": 300,
  "refresh_token": "{refresh_token}"
}

Invalidating a refresh token

request

POST {discover_urls.revocation_endpoint}
Content-Type: application/x-www-form-urlencoded

client_id={inputs.client_id}&token={token_response.refresh_token}

​Requirements

​Inputs

​Initiate the Client

​discover_urls

​Initiate the Device Authorization Flow

​device_authorization

​Pass control to the user to authenticate

​Poll for successful authentication

​token_response

​Refresh Tokens

​Exchanging a refresh token for a new access token

token_response

​Invalidating a refresh token

Requirements

Inputs

Initiate the Client

`discover_urls`

Initiate the Device Authorization Flow

`device_authorization`

Pass control to the user to authenticate

Poll for successful authentication

`token_response`

Refresh Tokens

Exchanging a refresh token for a new access token

`token_response`

Invalidating a refresh token