On this page:
1.1 Module oauth2.
OAUTH-SPEC-VERSION
OAUTH-RFC
OAUTH-DISPLAY-NAME
oauth2-logger
log-oauth2-debug
log-oauth2-info
log-oauth2-warning
log-oauth2-error
log-oauth2-fatal
1.1.1 Structure Types
client
token
1.1.2 Exceptions
exn:  fail:  http
exn:  fail:  oauth2
exn:  fail:  oauth2-error-description
7.8

1 Common Definitions

This section describes the common constants, structs, and exceptions across both the client and server implementations.

1.1 Module oauth2.

 (require oauth2) package: simple-oauth2

value

OAUTH-SPEC-VERSION : number? = 2.0

The current OAuth specification version supported by the package.

The current OAuth specification RFC supported by the package.

value

OAUTH-DISPLAY-NAME : string? = "OAuth {{version}} (RCF{{rfc}})"

A display string formatting the version of OAuth supported by the package.

value

oauth2-logger : logger?

syntax

(log-oauth2-debug string-expr)

(log-oauth2-debug format-string-expr v ...)

syntax

(log-oauth2-info string-expr)

(log-oauth2-info format-string-expr v ...)

syntax

(log-oauth2-warning string-expr)

(log-oauth2-warning format-string-expr v ...)

syntax

(log-oauth2-error string-expr)

(log-oauth2-error format-string-expr v ...)

syntax

(log-oauth2-fatal string-expr)

(log-oauth2-fatal format-string-expr v ...)
The logger instance, and logging procedures, used internally by the package. This is provided for tools to be ablt to log OAuth specific interactions with the same topic, but also to adjust the level of logging performed by the library.

1.1.1 Structure Types

struct

(struct client (service-name
    authorization-uri
    token-uri
    revoke-uri
    introspect-uri
    id
    secret)
    #:extra-constructor-name make-client
    #:prefab)
  service-name : string?
  authorization-uri : string?
  token-uri : string?
  revoke-uri : (or/c string? #f)
  introspect-uri : (or/c string? #f)
  id : (or/c string? #f)
  secret : (or/c bytes? #f)
This is the basic details of a registered client for an OAuth protected resource server where service-name is the display name for the service. Both authorization-uri and token-uri are required values and are the published endpoints.

The id and secret are the values provided by the service to you, the client, for authentication. The client id should uniquely identify your client and the secret is used in certain token grant flows. Note that the secret value should always be stored securely, see Module oauth2/storage/clients. for details on persistence of client details.

The revoke-uri and introspect-uri fields are both optional as it may be that the service does not support revoking or introspecting tokens.

struct

(struct token (access-token
    type
    refresh-token
    audience
    scopes
    expires)
    #:extra-constructor-name make-token
    #:prefab)
  access-token : bytes?
  type : string?
  refresh-token : bytes?
  audience : (or/c string? #f)
  scopes : (listof string?)
  expires : exact-positive-integer?
This represents the details of tokens granted by the service to your client.

The value of expires denotes the time, in seconds, at which the access-token will expire and no longer be valid for use. This is stored as an absolute value so that the is expired? test is simply:

(define (token-expired? t)
  (> (current-seconds) (token-expires t)))

Note that the access-token and refresh-token values should always be stored securely, see Module oauth2/storage/tokens. for details on persistence of token details.

1.1.2 Exceptions

struct

(struct exn:fail:http exn:fail (code headers body)
    #:extra-constructor-name make-exn:fail:http
    #:transparent)
  code : integer?
  headers : list?
  body : bytes?
Raised on receipt of an HTTP error and contains the HTTP status code, any headers and body content from the response.

struct

(struct exn:fail:oauth2 exn:fail (error error-uri state)
    #:extra-constructor-name make-exn:fail:oauth2
    #:transparent)
  error : symbol?
  error-uri : (or/c string? #f)
  state : (or/c string? #f)
Raised on receipt of an OAuth specific error (usually an error indicated by the redirect server) and contains values as specified in the OAuth specification.

Return the error description part of the exception (reusing message from the standard exn:fail exception).