guile-oauth is an OAuth client module for Guile. It supports the following features:
-
OAuth 1.0a: HMAC-SHA1 and PLAINTEXT signatures.
-
OAuth 2.0: Authorization Code and Client Credentials grant types.
It depends on the following Guile version and modules:
- Guile >= 2.2.0.
- GnuTLS Guile bindings (for HTTPS support).
- guile-gcrypt >= 0.3.0.
- guile-json >= 4.5.0.
Download the latest tarball and untar it:
If you are cloning the repository make sure you run this first:
$ autoreconf -vif
Then, run the typical sequence:
$ ./configure --prefix=<guile-prefix>
$ make
$ sudo make install
Where <guile-prefix> should preferably be the same as your system Guile
installation directory (e.g. /usr).
If everything installed successfully you should be up and running:
$ guile
scheme@(guile-user)> (use-modules (oauth oauth2))
scheme@(guile-user)>
It might be that you installed guile-oauth somewhere differently than your system's Guile. If so, you need to indicate Guile where to find guile-oauth, for example:
$ GUILE_LOAD_PATH=/usr/local/share/guile/site guile
-
(oauth1-client-request-token url credentials [callback] #:method #:params #:params-location #:signature #:http-proc) : Obtain a request token from the server url for the given client credentials.
-
url : server URL to obtain a request token from.
-
credentials : client credentials (see make-oauth1-credentials).
-
callback : optional callback URL that the server will redirect to after authorization is completed (defaults to oob, no redirection).
-
#:method : the HTTP method to request the access token (defaults to 'POST).
-
#:params : a list of additional parameters.
-
#:params-location : location where OAuth protocol parameters will be sent, 'header (default), 'query or 'body.
-
#:signature : the signature algorithm to use (defaults to oauth1-signature-hmac-sha1).
-
#:http-proc : a procedure to provide an HTTP request implementation (defaults to (http-request).
Returns : a service reponse that includes the request token.
Throws
- oauth-invalid-response : if an unexpected response was returned from the server. It includes the response and body as arguments.
-
-
(oauth1-client-authorization-url url [request-token] #:params) : Returns a complete authorization URL given the server url and the previously obtained request-token response.
-
url : server URL to get the authorization URL from.
-
request-token : optional previously obtained request token response (defaults to #f).
-
#:params : a list of additional parameters.
Returns : an authorization URL the client should connect to in order to grant permissions and obtain a verification code.
-
-
(oauth1-client-access-token url credentials request-token verifier #:method #:extra-headers #:params-location #:signature #:http-proc) : Obtain an access token from the server url for the given client credentials, request-token response and verifier.
-
url : server URL to obtain an access token from.
-
credentials : client credentials (see make-oauth1-credentials).
-
request-token : this is the request token obtained with oauth1-client-request-token.
-
verifier : the verification code obtained from authorization URL.
-
#:method : the HTTP method to request the access token (defaults to 'POST).
-
#:extra-headers : a list of additional HTTP headers.
-
#:params-location : location where OAuth protocol parameters will be sent, 'header (default), 'query or 'body.
-
#:signature : the signature algorithm to use (defaults to oauth1-signature-hmac-sha1).
-
#:http-proc : a procedure to provide an HTTP request implementation (defaults to (http-request).
Returns : a service response that includes the access token.
Throws
- oauth-invalid-response : if an unexpected response was returned from the server. It includes the response and body as arguments.
-
-
(oauth1-client-http-request url credentials access-token #:method #:body #:params #:params-location #:extra-headers #:signature #:http-proc) : Access a server's protected resource url with the given client credentials and the previously obtained access-token response.
-
url : server URL resource to access.
-
credentials : client credentials (see make-oauth1-credentials).
-
access-token : the access token to access the protected resource.
-
#:method : the HTTP method to request the access token (defaults to 'GET).
-
#:body : the request body (defaults to #f).
-
#:params : a list of additional parameters.
-
#:params-location : location where OAuth protocol parameters will be sent, 'header (default), 'query or 'body.
-
#:extra-headers : a list of additional HTTP headers.
-
#:signature : the signature algorithm to use (defaults to oauth1-signature-hmac-sha1).
-
#:http-proc : a procedure to provide an HTTP request implementation (defaults to (http-request).
Returns : a couple of values, the response and the body (as a string).
-
-
(oauth2-client-authorization-url url client-id #:redirect-uri #:scopes #:params) : Returns a complete authorization URL given the server url and the client-id.
-
url : server URL to get the authorization URL from.
-
client-id: the client public identifier.
-
#:redirect-uri : the URL the user should be redirected after the user authorizes the application.
-
#:scopes : a list of scopes (given as strings).
-
#:params : a list of additional query parameters.
Returns : Returns a couple of values: the complete authorization URL and the internally auto-generated state. The authorization URL is the URL the client should connect to in order to grant permissions and obtain an authorization code.
-
-
(oauth2-client-access-token-from-code url code #:client-id #:redirect-uri #:auth #:extra-headers #:http-proc) : Obtain an access token from the server url for the given code using an Authorization Code grant.
-
url : server URL to obtain an access token from.
-
code : the authorization code obtained after connecting to the authorization URL.
-
#:client-id : the client public identifier.
-
#:redirect-uri : the URL the user was redirected after the user authorizes the application.
-
#:auth : an authorization header (see oauth-http-basic-auth).
-
#:extra-headers : a list of additional HTTP headers.
-
#:http-proc : a procedure to provide an HTTP request implementation (defaults to (http-request).
Returns : an access token.
Throws
- oauth-invalid-response : if an unexpected response was returned from the server. It includes the response and body as arguments.
-
-
(oauth2-client-access-token-from-credentials url client-id client-secret #:auth-type #:extra-headers #:http-proc) : Obtain an access token from the server url using a Client Credentials grant.
-
url : server URL to obtain an access token from.
-
#:client-id : the client public identifier.
-
client-secret : the client secret.
-
#:auth-type : the authentication method to use ('header or 'params, defaults to 'header).
-
#:extra-headers : a list of additional HTTP headers.
-
#:http-proc : a procedure to provide an HTTP request implementation (defaults to (http-request).
Returns : an access token.
Throws
- oauth-invalid-response : if an unexpected response was returned from the server. It includes the response and body as arguments.
-
-
(oauth2-client-refresh-token url token #:client-id #:client-secret #:auth-type #:extra-headers #:http-proc) : Refresh an access token from the server url with the previously obtained access token. If needed, client-id and client-secret can be specified to authenticate this request.
-
url : server URL to obtain a refreshed access token from.
-
#:client-id : the client public identifier.
-
#:client-secret : the client secret.
-
#:auth-type : the authentication method to use ('header or 'params, defaults to 'header).
-
#:extra-headers : a list of additional HTTP headers.
-
#:http-proc : a procedure to provide an HTTP request implementation (defaults to (http-request).
Returns : a new access token.
Throws
- oauth-invalid-response : if an unexpected response was returned from the server. It includes the response and body as arguments.
-
-
(oauth2-client-http-request url access-token #:method #:body #:params #:extra-headers #:http-proc) : Access a server's protected resource @var{url} with the @var{access-token} previously obtained.
-
url : server URL resource to access.
-
access-token : the access token to access the protected resource.
-
#:method : the HTTP method to request the access token (defaults to 'GET).
-
#:body : the request body (defaults to #f).
-
#:params : a list of additional query parameters.
-
#:extra-headers : a list of additional HTTP headers.
-
#:http-proc : a procedure to provide an HTTP request implementation (defaults to (http-request).
Returns : a couple of values, the response and the body (as a string).
-
-
(oauth-www-form-urlencoded params) : Returns an application/x-www-form-urlencoded string (key1=value1&key2=value2...) for the given params association list. Both keys and values will be encoded.
-
(oauth-parse-www-form-urlencoded str #:optional charset) : Parses the given str string of name/value pairs as defined by the content type application/x-www-form-urlencoded and returns and association list. The keys and values in the association list are strings.
-
(oauth-http-basic-auth username password) : Create an HTTP basic authorization credentials header. If username or password are false returns nil.
-
(make-oauth1-credentials key secret) : Creates new client credentials.
-
(oauth1-credentials-key credentials) : Returns the client key.
-
(oauth1-credentials-secret credentials) : Returns the client secret.
-
(make-oauth1-response token token-secret params) : Creates a new service provider response for the given token, token secret and additional service parameters.
-
(oauth1-response-token response) : Returns the token from a service provider response.
-
(oauth1-response-token-secret response) : Returns the token secret from a service provider response.
-
(oauth1-response-params response) : Returns additional parameters returns by the service provider.
The following example details how to obtain the tweets of your Twitter home timeline. A complete example is available as a web application under the examples directory.
- Load the OAuth 1.0a module:
> (use-modules (oauth oauth1))
- Define our Twitter URLs and application credentials:
> (define *request-url* "https://api.twitter.com/oauth/request_token")
> (define *auth-url* "https://api.twitter.com/oauth/authorize")
> (define *access-url* "https://api.twitter.com/oauth/access_token")
> (define *home-timeline* "https://api.twitter.com/1.1/statuses/home_timeline.json")
> (define *credentials* (make-oauth1-credentials "key" "secret"))
The key and secret are provided by Twitter once you register a new application at https://developer.twitter.com.
- Obtain a request token:
> (define request-token (oauth1-client-request-token *request-url* *credentials*))
- Connect to the following returned URL for authorizing the request token:
> (oauth1-client-authorization-url *auth-url* request-token)
Here you will need to login to Twitter or simply authorize your application if you are already logged in.
- Obtain the access token that will allow us to access protected resources:
> (define access-token
(oauth1-client-access-token *access-url* *credentials* request-token "verifier"))
The verifier is the string given by Twitter in the previous step.
- Get your tweets:
> (oauth1-client-http-request *home-timeline* *credentials* access-token)
The following example details how to obtain a Reddit feed. A complete example is available as a web application under the examples directory.
- Load the OAuth 2.0 module:
> (use-modules (oauth oauth2))
- Define Reddit URLs:
> (define *user-agent* "guile:guile-oauth:1.0.0 (by /u/aconchillo)")
> (define *access-url* "https://www.reddit.com/api/v1/access_token")
> (define *reddit-feed-url* "https://oauth.reddit.com/r/scheme/new")
- Obtain the access token that will allow us to access protected resources using Client Credentials grant:
> (define access-token
(oauth2-client-access-token-from-credentials *access-url* "client-id" "secret"))
The client-id and secret are provided by Reddit once you register a new application at https://www.reddit.com/prefs/apps.
- Get your reddit feed:
> (oauth2-client-http-request *reddit-feed-url* access-token
#:extra-headers `((user-agent . ,*user-agent*)))
The user-agent is a header required by Reddit.
Copyright (C) 2013-2022 Aleix Conchillo Flaqué [email protected]
guile-oauth is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.
guile-oauth is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with guile-oauth. If not, see https://www.gnu.org/licenses/.