authy

A Clojure library designed to provide simple support for OAuth authentication.

Usage

This library provides a simple set of functions that can be used to authenticate to an OAuth 2.0 server. It currently provides functions to get an access token for an authorization code and to obtain a new access token for the current token, assuming that a refresh token is associated with the current access token.

Defining OAuth Server Parameters

The server information is a map of connection details:

(def server-info
 {:token-uri      "https://oauth-server.example.org/oauth/token"
  :redirect-uri   "https://oauth-client.example.org/path/to/auth/redirect"
  :client-key     "some-fake-client-identifier"
  :client-secret  "some-fake-client-passcode"
  :token-callback (fn [token-info] (do-something-with token-info))})

The fields are defined as follows:

Field	Definition
token-uri	The URI of the endpoint used to obtain access tokens
redirect-uri	The redirect URI sent in the authorization request.
client-key	The API key used to identify the client.
client-secret	The API secret used to identify the client.
token-callback	A function that will called when a new token is obtained.

The callback function is intended to be used by the calling service to do something when a new access token is obtained. For example, the caller may wish to cache the token so that it can be reused in future requests. This is helpful in cases where a client library automatically handles retries for expired tokens, preventing the caller from having to handle retries while still allowing the token information to be stored.

Obtaining an Access Token from an Authorization Code

When an authorization code is received, the receiver can obtain an access token by calling get-access-token:

(def token-info (get-access-token server-info authorization-code))

The resulting map contains both the token information and the server information, which keeps all of the information required to obtain a refresh token in one place. In addition to the server information fields, the response contains the following information about the token:

Field	Definition
token-type	The type of the access token.
expires-at	The approximate time the token expires (java.sql.Timestamp).
refresh-token	A token that can be used to obtain a new access token.
access-token	The access token itself.

Refreshing an Access Token

When an access token that has a refresh token associated with it expires, a new token can be obtained by calling refresh-access-token:

(def new-token-info (refresh-access-token token-info))

The resulting map is in the same format as the return value of get-access-token.

Determining if an Access Token is Expired

You can determine if an access token is expired by calling token-expired?:

(def expired? (token-expired? token-info))

License

http://iplantcollaborative.org/sites/default/files/iPLANT-LICENSE.txt