Module loa

OAuth2 Client Implementation.

OAuth 2.0 protocol implementation based on sanction (https://github.com/demianbrecht/sanction).

Info:

  • Copyright: 2014
  • Release: 0.1.0
  • License: MIT
  • Author: Paul Lewis

Functions

new () Create new OAuth2 client.
auth_uri () Generate an authorization URI.
build_request () Build an http request.
request_token () Request an authorization token.
request () Request data.
refresh () Refresh the authorization token.
_catch_redirect () Catch a redirect.


Functions

new (auth_endpoint, token_endpoint, resource_endpoint, client_id, client_secret[, token_transport])
Create new OAuth2 client. Returns a new OAuth2 client for use in authorizing a user against an OAuth2 authorization endpoint and requesting data from a relevent resource endpoint.

Parameters:

  • auth_endpoint string The Authorization URL. This endpoint will be used to generate the authorization URI return by loa.auth_uri.
  • token_endpoint string The Token URL. This endpoint will be used to to retrieve the authorization token when loa.request_token is called.
  • resource_endpoint string The resource endpoint. This URL will be used when requesting resources from the provider.
  • client_id string The client ID given to you by the provider.
  • client_secret string the client secret given to you by the provider. This should not be given to any one, ever.
  • token_transport function A function that will receive a url and insert a token in the necessary manner in any http requests. Default is to add "Authorization: Bearer {token}" to the HTTP headers. See the examples for more info.

Returns:

    userdata The new loa client object.
auth_uri (self, redirect_uri, scope[, state[, options]])
Generate an authorization URI.

Parameters:

  • self
  • redirect_uri string The URL where the provider should return the user after authentication. Usually this redirect will have the authorization code that will be needed to retrieve an authorization token.
  • scope string A string containing the scopes that should be requested from the provider. Typically comma or space delimitted.
  • state string The `state` parameter to pass for authorization. If the provider follows the OAuth 2.0 spec, this will be returned to your `redirect_uri` after authorization. Generally used for CSRF protection.
  • options table A table of any query paramaters that should be included in the authorization URL. i.e.: ?auth_type=offline can be added to the URI by providing this table: {auth_type="offline"}. All keys and values in this table are automatically URL-Encoded.

Returns:

    string The generated authorization endpoint to where the user should be directed to provide authorization.
build_request (url[, data[, method[, headers]]])
Build an http request. Construct an http request table to be provided to socket.http.request. Must be called when providing a token_transport to loa.new.

Parameters:

  • url string The base url for the request.
  • data table A table representing the POST data of this request (ifthere is any). i.e.: auth_type=offline can be added to the URI by providing this table: {auth_type="offline"}. All keys and values in this table are automatically URL-Encoded.
  • method string HTTP method to be used in the request. Defaults to "GET" if data is nil, or "POST" if it is not.
  • headers table A table representing the headers to be included in thisrequest. i.e.: "Content-Length: 8" can be included by providing this table: {["Content-Length"]=8}. Note that Content-Length and Content-type will be automatically provided if data is not nil.

Returns:

  1. table req A table to provide socket.http.request
  2. table rsp A table that will hold the response generated by the request.
request_token (self, parser, redirect_uri[, options])
Request an authorization token. Sends a request to the token endpoint. After success, the token will be a field of the loa object (access_token), and will be automatically included in data requests via loa.request.

Parameters:

  • self
  • parser function A function that can parse the information returned by the provider. This is typically json, though it varies by provider.
  • redirect_uri string Some providers require this parameter in a request. You can include it as this argument or in the options table.
  • options table A table of any query paramaters that should be included in the authorization URL. i.e.: ?auth_type=offline can be added to the URI by providing this table: {auth_type="offline"}. All keys and values in this table are automatically URL-Encoded.

Returns:

  1. boolean true if the http request was completed.
  2. number the status code returned by the token endpoint.
  3. table headers included in the response message.
  4. string the full status code and message returned by the endpoint.
request (self, url[, method[, data[, headers[, parser]]]])
Request data. Requests and returns user data from the resource endpoint.

Parameters:

  • self
  • url string Appended to the end of the resource_endpoint.
  • method string HTTP method to be used in the request. Defaults to "GET" if data is nil, or "POST" if it is not.
  • data table A table representing the POST data of this request (ifthere is any). i.e.: auth_type=offline can be added to the URI by providing this table: {auth_type="offline"}. All keys and values in this table are automatically URL-Encoded.
  • headers table A table representing the headers to be included in thisrequest. i.e.: "Content-Length: 8" can be included by providing this table: {["Content-Length"]=8}. Note that Content-Length and Content-type will be automatically provided if data is not nil.
  • parser function A function that can parse the information returnedby the provider. This is typically json, though it varies by provider.
refresh (parser, options)
Refresh the authorization token. After receiving an initial auth token, this function will send a refresh token request.

Parameters:

  • parser
  • options

See also:

_catch_redirect (redirect_uri[, body[, timeout=2[, hardtimeout=5]]])
Catch a redirect. This is largely a helper function for if you are not actually running a server. This will listen on a socket until it receives data, and then return that data (likely an http request).

Parameters:

  • redirect_uri string The redirect URI provided in an earlier call to loa.auth_uri.
  • body string An optional HTML document that will be returned upon receiving the redirect. A default will be used if not provided.
  • timeout number Timeout value used for the server socket. (default 2)
  • hardtimeout number If a redirect has not been received in this many seconds. The function will return. Use math.huge to disable. (default 5)

Returns:

  1. string captured data.
  2. nil if an error.

Or

  1. nil if no error.
  2. string error message.
generated by LDoc 1.4.2