NAME
CatalystX::OAuth2 - OAuth2 services for Catalyst
VERSION
version 0.001002
SYNOPSIS
package AuthServer::Controller::OAuth2::Provider;
use Moose;
BEGIN { extends 'Catalyst::Controller::ActionRole' }
with 'CatalystX::OAuth2::Controller::Role::Provider';
__PACKAGE__->config(
store => {
class => 'DBIC',
client_model => 'DB::Client'
}
);
sub request : Chained('/') Args(0) Does('OAuth2::RequestAuth') {}
sub grant : Chained('/') Args(0) Does('OAuth2::GrantAuth') {
my ( $self, $c ) = @_;
my $oauth2 = $c->req->oauth2;
$c->user_exists and $oauth2->user_is_valid(1)
or $c->detach('/passthrulogin');
}
sub token : Chained('/') Args(0) Does('OAuth2::AuthToken::ViaAuthGrant') {}
sub refresh : Chained('/') Args(0) Does('OAuth2::AuthToken::ViaRefreshToken') {}
1;
DESCRIPTION
This module implements the authorization grant subset of the <oauth 2
ietf spec draft>. Action roles containing an implementation of each
required endpoint in the specification are provided and should be
applied to a Catalyst::Controller::ActionRole. The authorization grant
flow is defined by the specification as follows:
+--------+ +---------------+
| |--(A)------- Authorization Grant --------->| |
| | | |
| |<-(B)----------- Access Token -------------| |
| | & Refresh Token | |
| | | |
| | +----------+ | |
| |--(C)---- Access Token ---->| | | |
| | | | | |
| |<-(D)- Protected Resource --| Resource | | Authorization |
| Client | | Server | | Server |
| |--(E)---- Access Token ---->| | | |
| | | | | |
| |<-(F)- Invalid Token Error -| | | |
| | +----------+ | |
| | | |
| |--(G)----------- Refresh Token ----------->| |
| | | |
| |<-(H)----------- Access Token -------------| |
+--------+ & Optional Refresh Token +---------------+
The action roles should be applied to actions in a single controller,
and no more than one action of each role type should be present.
Here is an overview of what roles are involved in each of those phases:
A - Catalyst::ActionRole::OAuth2::RequestAuth
Required
This is the action where the authentication grant flow begins, it
validades and sanitizes the request parameters and generates an
authorization code which is used for issuing a valid request to the
GrantAuth action via a redirect. The authorization code is only
generated if all parameters are well-formed and valid, this ensures
that requests to the GrantAuth action can trust the request
parameters if a valid authorization code is presented.
B - Catalyst::ActionRole::OAuth2::GrantAuth
Required
This action checks the request parameters for a valid authorization
code, which should have been generated by a previous request to a
RequestAuth action. This action should be customized to somehow
confirm with the end-user if he wishes to effectively grant the
authorization to the requesting client/app. The user-agent is
redirected automatically to the correct endpoint if the
authorization is granted.
C and D - Catalyst::ActionRole::OAuth2::AuthToken::ViaAuthGrant
Required
This action exchanges a valid authorization grant code and responds
with an authorization token.
G and H - Catalyst::ActionRole::OAuth2::AuthToken::ViaRefreshToken
Optional
This action exchanges a valid refresh token for a new access token
and refresh token.
CONFIGURATION
store
Takes a hashref containing two keys:
class
The store type to use, so far, only DBIC support is provided
client_model
The entity representing the client in your schema
SPONSORSHIP
This module exists due to the wonderful people at Suretec Systems Ltd.
<http://www.suretecsystems.com/> who sponsored its development for its
VoIP division called SureVoIP <http://www.surevoip.co.uk/> for use with
the SureVoIP API -
<http://www.surevoip.co.uk/support/wiki/api_documentation>
AUTHOR
Eden Cardim <edencardim@gmail.com>
COPYRIGHT AND LICENSE
This software is copyright (c) 2012 by Suretec Systems Ltd.
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.