2 OAuth 2.0 Client
(require webapi/oauth2) | package: webapi |
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.
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.
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
|
method
(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"
method
(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"
method
(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.
method
(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.
method
(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.
procedure
(oauth2-auth-server #:auth-url auth-url #:token-url token-url) → (is-a?/c oauth2-auth-server<%>) auth-url : string? token-url : string?
|
Returns the client’s ID string.
method
(send an-oauth2-client get-secret) → (or/c string? #f)
Returns the client’s secret.
procedure
(oauth2-client #:id id [#:secret secret])
→ (is-a?/c oauth2-client<%>) id : string? secret : (or/c string? #f) = #f
|
method
(send an-oauth2 get-client-id) → string?
Returns the client ID string.
method
(send an-oauth2 get-scopes) → (listof string?)
Returns the currently authorized scopes. If the scopes are unknown, this method returns '(). See also validate!.
method
(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.
method
(send an-oauth2 get-refresh-token) → (or/c string? #f)
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.
procedure
(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"
procedure
(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?
procedure
(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?)
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.