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 valid

​
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": "{inputs.base_url}/activate",
  "expires_in": 900,
  "interval": 5,
  "verification_uri_complete": "{inputs.base_url}/activate?user_code={user_code}"
}
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}