On this page:
2.1 OAuth 2.0 Overview
2.1.1 OAuth 2.0 for Installed Applications
2.1.2 OAuth 2.0 for User-Agent-Based Applications
2.1.3 OAuth 2.0 for Web Applications
2.2 OAuth 2.0 Reference
oauth2-auth-server<%>
get-auth-url
get-token-url
get-tokeninfo-url
get-revoke-url
get-auth-request-url
oauth2-auth-server
google-auth-server
oauth2-client<%>
get-id
get-secret
oauth2-client
oauth2<%>
get-client-id
get-scopes
get-access-token
get-refresh-token
validate!
revoke!
headers
oauth2/ auth-code
oauth2/ refresh-token
oauth2/ request-auth-code/ browser
2.3 OAuth 2.0 Security Notes

2 OAuth 2.0 Client

 (require (planet ryanc/webapi:1:=1/oauth2))

This library is an incomplete implementation of an unfinished standard; use with care. It is certain to evolve as features are added and as the standard solidifies.

This library supports a subset of the OAuth 2.0 authorization protocol. The OAuth 2.0 specification is currently in draft state; this library is based on draft 25 (released 8-Mar-2012, expires 9-Sep-2012). The implementation is currently designed to work with the requirements of the Google authorization server (as of 28-Mar-2012); it may not work yet in other contexts.

2.1 OAuth 2.0 Overview

The protocol involves four parties: resource owner, resource server(s), client, and authorization server. This library may be used by clients to talk to resource servers and authorization servers; it provides no support for implementors of resource servers or authorization servers.

An OAuth 2.0 authorization is represented by an object implementing the oauth2<%> interface. It consists of a client, an authorization server, the access “scopes” granted, and the tokens issued by the authorization server. Clients are represented by objects implementing oauth2-client<%>, and authorization servers are represented by objects implementing oauth2-auth-server<%>. Scopes and tokens are represented as strings.

A client (oauth2-client<%>) contains a client ID and optionally a client secret, both obtained by registering a client application with an authorization server. The client object represents only the ID and credentials of a registered client, not its behavior.

An authorization server (oauth2-auth-server<%>) contains the URLs used to serve client authorization requests. These URLs have nothing to do with the URLs used to access protected resources.

Resource servers are not represented directly in this library; instead, a client program makes HTTP requests directly to a resource server including HTTP headers generated by a oauth2<%> object. Currently only bearer tokens are supported; see OAuth 2.0 Security Notes.

The following subsections outline the support for various usage scenarios.

2.1.1 OAuth 2.0 for Installed Applications

This scenario applies to clients that are Racket programs running on the resource owner’s machine. (The OAuth 2.0 draft calls these “native applications,” but “installed application” seems a better description.) Since the client is under the control of the resource owner, its credentials, including the “client secret,” should not be considered secret.

An installed application can obtain an oauth2<%> object in the following ways:
  • Use oauth2/request-auth-code/browser to open a web browser with an authorization code request to the authorization server. If the request is granted, the browser is redirected to a localhost URL, where a web server created specifically for the request acquires the authorization code, uses it to create the oauth2<%> object, and shuts down.

  • Use get-auth-request-url to generate an authorization request URL. The user must visit the URL, grant access, and call oauth2/auth-code with the resulting authorization code. Use this process when either automatically opening a web browser or starting a local web server is not desirable.

  • Use oauth2/refresh-token with a long-lived “refresh token” obtained from an earlier authorization grant. (See get-refresh-token.)

A client program may wish to use oauth2/request-auth-code/browser for the initial request and then store the refresh code for future runs of the program. Or the client program may just use oauth2/request-auth-code/browser at the beginning of each run, if it has no access to reasonably secure persistent storage.

2.1.2 OAuth 2.0 for User-Agent-Based Applications

Not applicable. In practice, this scenario applies only to Javascript clients running in a web browser (“user agent”).

2.1.3 OAuth 2.0 for Web Applications

This scenario applies to clients that are web applications running on a server not under the resource owner’s control. In contrast to the installed application scenario, the client may keep secrets, such as its credentials, from the resource owner.

A web application can obtain an oauth2<%> object in the following ways:
  • Forward the user to the URL generated by get-auth-request-url; use the state argument to represent the current session/context. After granting authorization, the user will be redirected to the redirect-uri with the authorization code and user state in the code and state query arguments, respectively. Call oauth2/auth-code with the authorization code.

  • Use oauth2/refresh-token with a long-lived “refresh token” obtained from an earlier authorization grant. (See get-refresh-token.)

2.2 OAuth 2.0 Reference

Represents an authorization server. Obtain an instance via oauth2-auth-server, or use the google-auth-server instance.

(send an-oauth2-auth-server get-auth-url)  string?
Returns the base URL for authorization requests presented to the resource owner, generally used to obtain authorization codes.

Example:

> (send google-auth-server get-auth-url)

"https://accounts.google.com/o/oauth2/auth"

(send an-oauth2-auth-server get-token-url)  string?
Returns the base URL for token requests made automatically by the client.

Example:

> (send google-auth-server get-token-url)

"https://accounts.google.com/o/oauth2/token"

(send an-oauth2-auth-server get-tokeninfo-url)
  (or/c string? #f)
Returns the base URL for getting information about granted tokens. Used by validate!. This seems to be a Google extension.
(send an-oauth2-auth-server get-revoke-url)
  (or/c string? #f)
Returns the base URL for revoking a token. Used by revoke!. This seems to be a Google extension.

(send an-oauth2-auth-server get-auth-request-url 
  #:client client 
  #:scopes scopes 
  [#:redirect-uri redirect-uri 
  #:state state 
  #:extra-parameters extra-parameters]) 
  string?
  client : (is-a?/c oauth2-client<%>)
  scopes : (listof string?)
  redirect-uri : string? = "urn:ietf:wg:oauth:2.0:oob"
  state : (or/c string? #f) = #f
  extra-parameters : (listof (cons/c symbol? string?)) = null
Returns a URL (as a string) that can be visited in a browser to request authorization for client to access resources in the given scopes.

The default redirect-uri is a special URI indicating that the authorization server should redirect to a page of its own displaying the authorization code, rather than sending it via redirection to a page under the client’s control.

(oauth2-auth-server #:auth-url auth-url 
  #:token-url token-url) 
  (is-a?/c oauth2-auth-server<%>)
  auth-url : string?
  token-url : string?
Creates an oauth2-auth-server<%> representation, given its endpoint URLs.

Represents the authorization server for Google APIs.

Represents a client registered with some authorization server. Obtain an instance via oauth2-client.

(send an-oauth2-client get-id)  string?
Returns the client’s ID string.
(send an-oauth2-client get-secret)  (or/c string? #f)
Returns the client’s secret.

(oauth2-client #:id id [#:secret secret])
  (is-a?/c oauth2-client<%>)
  id : string?
  secret : (or/c string? #f) = #f
Creates a client object with ID id and secret secret.

Represents a client with authorizations for some set of resources.

(send an-oauth2 get-client-id)  string?
Returns the client ID string.
(send an-oauth2 get-scopes)  (listof string?)
Returns the currently authorized scopes. If the scopes are unknown, this method returns '(). See also validate!.
(send an-oauth2 get-access-token #:re-acquire? re-acquire?)
  (or/c string? #f)
  re-acquire? : #t
Returns the current access token, if one is available and has not expired.

If there is no current access token and re-acquire? is #f, the method returns #f. Otherwise, if there is no current access token and re-acquire? is true, the object attempts to acquire a new access token—such as by using a long-lived refresh token, if one was provided by the authorization server.
(send an-oauth2 get-refresh-token)  (or/c string? #f)
Returns the refresh token, if one was provided by the authorization server, #f otherwise.
(send an-oauth2 validate!)  void?
Validates the current tokens with the auth server. If the auth server does not support token validation, an exception is raised.

As a side effect of validation, the scope information returned by get-scopes is updated.
(send an-oauth2 revoke!)  void?
Revokes the current refresh token.
(send an-oauth2 headers)  (listof string?)
Returns a list of HTTP headers to be used in HTTP requests to resource servers. Currently only bearer tokens are supported; see OAuth 2.0 Security Notes.

(oauth2/auth-code auth-server 
  client 
  auth-code 
  [#:redirect-uri redirect-uri]) 
  (is-a?/c oauth2<%>)
  auth-server : (is-a?/c oauth2-auth-server<%>)
  client : (is-a?/c oauth2-client<%>)
  auth-code : string?
  redirect-uri : string? = "urn:ietf:wg:oauth:2.0:oob"
Creates an oauth2<%> object, using the given auth-code to request an access token from auth-server; a refresh token may or may not be granted as well. The redirect-uri argument must match the redirection URI used to request the authorization code.

(oauth2/refresh-token auth-server    
  client    
  refresh-token)  (is-a?/c oauth2<%>)
  auth-server : (is-a?/c oauth2-auth-server<%>)
  client : (is-a?/c oauth2-client<%>)
  refresh-token : string?
Creates an oauth2<%> object, using a previously granted (long-lived) refresh-token to acquire a new short-lived access token.

(oauth2/request-auth-code/browser auth-server 
  client 
  scopes) 
  (is-a?/c oauth2<%>)
  auth-server : (is-a?/c oauth2-auth-server<%>)
  client : (is-a?/c oauth2-client<%>)
  scopes : (listof string?)
Automates the combination of get-auth-request-url and oauth2/auth-code by opening a browser window and creating an ad hoc web server running on localhost:8000 and supplying a redirection URL of "http://localhost:8000/oauth2/response" in the authorization code request to auth-server.

2.3 OAuth 2.0 Security Notes

This library currently only supports bearer access tokens, because the Google authorization server only issues bearer tokens. A bearer token is used by directly including in an “Authorization” HTTP header; consequently, any request that uses a bearer token must use transport-level security such as SSL/TLS.