OAuth Two

Installation

This project is under active development, and has yet to reach 1.0. As such the API may change.

Getting started

Require the library with a convenient alias that we can make use of later.

(require '[oauth.two :as two])

Create a client using the credentials provided by (in this example) Vimeo. The client holds on to important URLs, and tokens. We’ll pull our client ID and secret from environment variablesa to avoid adding sensitive credentials to our repository.

(def client
  (two/make-client
   {:access-uri "https://api.vimeo.com/oauth/access_token"
    :authorize-uri "https://api.vimeo.com/oauth/authorize"
    :id (System/getenv "VIMEO_CLIENT_ID")
    :secret (System/getenv "VIMEO_CLIENT_SECRET")}))

The :access-uri is where we get access tokens, and the `:authorize-uri` is where we redirect users to show them the provider’s site.

Generate provider-specific redirect URL

To kick off the OAuth dance we need to create a URL to send the user to. This URL is owned by the OAuth provider, and it’s where the provider asks the user if they want to grant us access.

To generate the authorisation URL we use the authorization-url function like so:

(two/authorization-url client)

We can pass in additional parameters to include in the OAuth authorisation URL by providing an optional map as the second argument.

(two/authorization-url client {:state "hello world"})

A third optional argument allows you to pass additional query parameters, like Google’s “prompt” parameter.

(two/authorization-url client
                       {:state "hello world"}
                       {:prompt "select_account"})

Handle response from provider

When the user decides to accept our request to access his or her account we receive a GET request by virtue of the provider redirecting the user to us.

Query parameters are appended to our :callback-uri that inform us if the authorisation request was successful or not.

Success

This redirect includes an authorisation code, and any local state provided previously.

Field	Required	Description
code	REQUIRED	The auth code generated by the Auth server
state	REQUIRED	Whatever value we passed previously

The authorization code generated by the authorization server. The authorization code MUST expire shortly after it is issued to mitigate the risk of leaks. A maximum authorization code lifetime of 10 minutes is RECOMMENDED. The client MUST NOT use the authorization code more than once. If an authorization code is used more than once, the authorization server MUST deny the request and SHOULD revoke (when possible) all tokens previously issued based on that authorization code. The authorization code is bound to the client identifier and redirection URI.

Failure

If something goes wrong the Auth server redirects back to the client with the following parameters:

Field	Required	Description
error	REQUIRED	A single ASCII error code
error_description	OPTIONAL	Human-readable ASCII error description
error_uri	OPTIONAL	A URI with more human-readable error info
state	REQUIRED	Whatever value we passed previously

Error codes are as follows:

Error	Description
unauthorized_client	The client is not authorized to request an authorization code using this method.
access_denied	The resource owner or authorization server denied the request.
unsupported_response_type	The authorization server does not support obtaining an authorization code using this method.
invalid_scope	The requested scope is invalid, unknown, or malformed.
server_error	The authorization server encountered an unexpected condition that prevented it from fulfilling the request. (This error code is needed because a 500 Internal Server Error HTTP status code cannot be returned to the client via an HTTP redirect.)
temporarily_unavailable	The authorization server is currently unable to handle the request due to a temporary overloading or maintenance of the server. (This error code is needed because a 503 Service Unavailable HTTP status code cannot be returned to the client via an HTTP redirect.)

HTTP/1.1 302 Found
Location: https://client.example.com/cb?error=access_denied&state=xyz

Request access token

With the code from the provider we can generate a request map for getting our access token via the access-token-request.

(two/access-token-request
 (make-client {:access-uri "http://example.com/oauth/access-token"
               :id "id"
               :secret "secret"})
 {:code "abc"})

This will produce a request map with Basic authentication via the client’s ID and secret in addition to the code.

{:request-method :post,
 :url "http://example.com/oauth/access-token",
 :headers
 {"authorization" "Basic aWQ6c2VjcmV0",
  "content-type" "application/x-www-form-urlencoded"},
 :body "client_id=id&code=abc&grant_type=authorization_code"}

You can then issue this request using your favourite HTTP client, with any error handling, JSON response parsing, metrics etc.

All OAuth 2.0 providers will return a custom response to the access token request. The spec provides the following JSON as an example response:

{
  "access_token": "2YotnFZFEjr1zCsicMWpAA",
  "token_type": "example",
  "expires_in": 3600,
  "refresh_token": "tGzv3JOkF0XG5Qx2TlKWIA",
  "example_parameter": "example_value"
}

https://tools.ietf.org/html/rfc6749#section-4.1.4

The spec goes on to define how these attributes should be used in other flows.

access_token
      REQUIRED.  The access token issued by the authorization server.

token_type
      REQUIRED.  The type of the token issued as described in
      Section 7.1.  Value is case insensitive.

expires_in
      RECOMMENDED.  The lifetime in seconds of the access token.  For
      example, the value "3600" denotes that the access token will
      expire in one hour from the time the response was generated.
      If omitted, the authorization server SHOULD provide the
      expiration time via other means or document the default value.

scope
      OPTIONAL, if identical to the scope requested by the client;
      otherwise, REQUIRED.  The scope of the access token as
      described by Section 3.3.

state
      REQUIRED if the "state" parameter was present in the client
      authorization request.  The exact value received from the
      client.