2 OAuth 2.0 Client
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.)
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
Returns the base URL for authorization requests presented to the
resource owner, generally used to obtain authorization codes.
Returns the base URL for token requests made automatically by the
client.
Returns the base URL for getting information about granted
tokens. Used by
validate!. This seems to be a
Google extension.
Returns the base URL for revoking a token. Used by
revoke!. This seems to be a Google extension.
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.
Represents a client registered with some authorization
server. Obtain an instance via
oauth2-client.
Returns the client’s ID string.
Returns the client’s secret.
Creates a client object with ID id and secret
secret.
Represents a client with authorizations for some set of resources.
Returns the client ID string.
Returns the currently authorized scopes. If the scopes are unknown,
this method returns
'(). See also
validate!.
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.
Returns the refresh token, if one was provided by the authorization
server, #f otherwise.
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.
Revokes the current refresh token.
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.
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.
Creates an
oauth2<%> object, using a previously granted
(long-lived)
refresh-token to acquire a new short-lived
access token.
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.