/ 
CatalystX-OAuth2-0.001008
River stage zero No dependents
/ CatalystX::OAuth2

NAME

CatalystX::OAuth2 - OAuth2 services for Catalyst

VERSION

version 0.001008

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) 2017 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.