NAME

TDcal::OAuth —

TDcal Perl programming library

SYNOPSIS

use TDcal::OAuth;

($host, $port) =
oauth_httpd();

$bool =
oauth_auth($calref, $svc);

($httpstatus, $auth_response, $httperr) =
oauth_tokens($calref, $svc, $auth_code);

($httpstatus, $auth_response, $httperr) =
oauth_refresh($calref);

DESCRIPTION

TDcal::OAuth provides functions that enable OAuth authorization in accordance with the RFC6749 OAuth 2.0 authorization framework.

In these functions, the agrument $calref are calendar references as returned by tdcalref().

The argument $svc is a string naming the OAuth service to be used. Currently supported services are documented in the td(5) manual page.

oauth_httpd() returns the hostname and port on which a redirect web server should connect and listen for the OAuth redirect response. Before calling oauth_auth(), the caller should create a server process listening on the TCP address and port indicated and capable of handling a single HTTP GET request. The GET request will be for a URL of the form:

GET /?type=result HTTP/N.N

where ‘type’ is set to ‘code’ for a valid response or to ‘error’ in the case of error, and ‘result’ is either the requested access code or an error message.

oauth_auth() initiates a request for an OAuth authorization code. It does this by opening the user's browser and sending it to the authorization URL for the service. It is anticipated that the service will request that the user logs in, and then that the user approves the request for access. If granted, the service will respond to the browser with an HTTP Redirect which sends the browser to the local HTTPD server with the authorization code. The HTTPD server receives the code as a new HTTP request in the form described above.

oauth_tokens() is used by the HTTPD server to request an OAuth refresh token based on the authorization code. The intent here is for the refresh token to be stored in the TDcal configuration file for the calendar.

oauth_refresh() is used to obtain an OAuth access token based on an OAuth refresh token. The access token has a limited expiration time, and can be used to access the user's data on the service. The type and the aceess token must be returned in the ‘Authorization:’ header of subsequent requests.

RETURN VALUES

The $httpstatus return value is the numeric status of the response from the HTTP server. A value of 200 represents success. Other values can be found by searching the web for HTTP server response codes.

If $httpstatus indicates success, the $auth_response return value is a reference to a hash with the following contents:

$auth_response->{access_token}: the OAuth access token
$auth_response->{expires_in}: the number of seconds for which the access token is valid
$auth_response->{refresh_token}: the OAuth refresh token
$auth_response->{scope}: the OAuth scope(s) for which access was granted
$auth_response->{token_type}: the OAuth token type
$auth_response->{url}: the base URL for accessing the service

If $httpstatus does not indicate success, $httperr is a string containing the HTTP error message. Additional error details will also have been logged to the log file.

STANDARDS

See TDcal(7).

HISTORY