NAME

   Dancer2::Plugin::OAuth2::Server - Easier implementation of an OAuth2
   Authorization Server / Resource Server with Dancer2 Port of Mojolicious
   implementation :
   https://github.com/G3S/mojolicious-plugin-oauth2-server

SYNOPSIS

     use Dancer2::Plugin::OAuth2::Server;

     To protect a route, declare it like following:

     get '/protected' => oauth_scopes 'desired_scope' => sub { ... }

DESCRIPTION

   Dancer2::Plugin::OAuth2::Server is a port of Mojolicious plugin for
   OAuth2 server With this plugin, you can implement an OAuth2
   Authorization server and Resource server without too much hassle. The
   Basic flows are implemented, authorization code, access token, refresh
   token, ...

   A "simple" implementation is provided with a "in memory" session
   management, however, it will not work on multi process persistent
   environment, as each restart will loose all the access/refrest tokens.
   Token will also not be shared between processes.

   For a usable implementation in a realistic context, you will need to
   create a class implementing the Role
   Dancer2::Plugin::OAuth2::Server::Role, and configure the server_class
   option in configuration of the plugin. The following methods needs to
   be implemented:

           login_resource_owner
           confirm_by_resource_owner
           verify_client
           store_auth_code
           generate_token
           verify_auth_code
           store_access_token
           verify_access_token

   On the resource server side, to protect a resource, just use the dsl
   keyword oauth_scopes with either one scope or the list of scope needed.
   In case the authorization header provided is not correct, a 400 http
   code is returned with an erro message. If the Authorization header is
   correct and the access is granted, the access token information are
   stored within the var keyword, in oauth_access_token, for the time of
   the request. You can access the access token information through
   var('oauth_access_token') within the route code itself.

CONFIGURATION

authorize_route

   The route that the Client calls to get an authorization code. Defaults
   to /oauth/authorize The route is accessible through http GET method

access_token_route

   The route the the Client calls to get an access token. Defaults
   to/oauth/access_token The route is accessible through http POST method

auth_code_ttl

   The validity period of the generated authorization code in seconds.
   Defaults to 600 seconds (10 minutes)

access_token_ttl

   The validity period of the generated access token in seconds. Defaults
   to 3600 seconds (1 hour)

clients

   list of clients for the simple default implementation

       clients:
         client1:
           client_secret: secret
           scopes:
             identity: 1
             other: 0
         client2:
           client_secret: secret2
           scopes:
             identity: 1
             other: 1

   Note the clients config is not required if you add the verify_client
   callback, but is necessary for running the plugin in its simplest form
   (when no server class is provided)

state_required

   State is optional in the sepcifications, however using state is really
   recommended to have a safe implementation on client side. Client should
   send state and verify it, switching state_required to 1 make state a
   required parameter when trying to get the authorization code

server_class

   Package name of the server class for customizing the OAuth server
   behavior. Defaults to Dancer2::Plugin::OAuth2::Server::Simple, the
   provided simple implementation

Server Class implementation

   To customize the implementation in a more realistic way, the user needs
   to create a class implementing the role
   Dancer2::Plugin::OAuth2::Server::Role , and provide the Class name in
   the configuration key server_class. That role ensures that all the
   required functions are implemented. All the function will receive the
   dsl and settings as first 2 parameters: $dsl, $settings Those
   parameters will for instance allows user to access session, are plugin
   configuration

login_resource_owner

   Function that tells if the Resource owner is logged in. It should
   return 1 if the user is logged in, return 0 if not. That function is
   expected to redirect the user to login page if needed.

confirm_by_resource_owner

   Function to tell the plugin if the Resource Owner allowed or denied
   access to the Resource Server by the Client. Function receives the
   client_id and the list of scopes requested by the client. It should
   return 1 if access is allowed, 0 if access is not allowed, otherwise it
   should redirect the user and return undef

verify_client

   Reference: http://tools.ietf.org/html/rfc6749#section-4.1.1

   Function to verify if the client asking for an authorization code is
   known to the Resource Server and allowed to get an authorization code
   for the passed scopes. The function receives the client id, and an
   array reference of request scopes. The callback should return a list
   with two elements. The first element is either 1 or 0 to say that the
   client is allowed or disallowed, the second element should be the error
   message in the case of the client being disallowed.

store_auth_code

   Function to allow you to store the generated authorization code. After
   the 2 common parameters, The Function is passed the generated auth
   code, the client id, the auth code validity period in seconds, the
   Client redirect URI, and a list of the scopes requested by the Client.
   You should save the information to your data store, it can then be
   retrieved by the verify_auth_code function for verification

generate_token

   Function to generate a token. After the 2 common parameters, dsl and
   settings, that function receives the validity period in seconds, the
   client id, the list of scopes, the type of token and the redirect url.
   That function should return the token that it generates, and should be
   unique.

verify_auth_code

   Reference: http://tools.ietf.org/html/rfc6749#section-4.1.3

   Function to verify the authorization code passed from the Client to the
   Authorization Server. The function is passed the dsl, the settings, and
   then the client_id, the client_secret, the authorization code, and the
   redirect uri. The Function should verify the authorization code using
   the rules defined in the reference RFC above, and return a list with 4
   elements. The first element should be a client identifier (a scalar, or
   reference) in the case of a valid authorization code or 0 in the case
   of an invalid authorization code. The second element should be the
   error message in the case of an invalid authorization code. The third
   element should be a hash reference of scopes as requested by the client
   in the original call for an authorization code. The fourth element
   should be a user identifier

store_access_token

   Function to allow you to store the generated access and refresh tokens.
   The function is passed the dsl, the settings, and then the client
   identifier as returned from the verify_auth_code callback, the
   authorization code, the access token, the refresh_token, the validity
   period in seconds, the scope returned from the verify_auth_code
   callback, and the old refresh token,

   Note that the passed authorization code could be undefined, in which
   case the access token and refresh tokens were requested by the Client
   by the use of an existing refresh token, which will be passed as the
   old refresh token variable. In this case you should use the old refresh
   token to find out the previous access token and revoke the previous
   access and refresh tokens (this is *not* a hard requirement according
   to the OAuth spec, but i would recommend it). That functions does not
   need to return anything. You should save the information to your data
   store, it can then be retrieved by the verify_access_token callback for
   verification

verify_access_token

   Reference: http://tools.ietf.org/html/rfc6749#section-7

   Function to verify the access token. The function is passed the dsl,
   the settings and then the access token, an optional reference to a list
   of the scopes and if the access_token is actually a refresh token. Note
   that the access token could be the refresh token, as this method is
   also called when the Client uses the refresh token to get a new access
   token (in which case the value of the $is_refresh_token variable will
   be true).

   The function should verify the access code using the rules defined in
   the reference RFC above, and return false if the access token is not
   valid otherwise it should return something useful if the access token
   is valid - since this method is called by the call to oauth_scopes you
   probably need to return a hash of details that the access token relates
   to (client id, user id, etc). In the event of an invalid, expired, etc,
   access or refresh token you should return a list where the first
   element is 0 and the second contains the error message (almost
   certainly 'invalid_grant' in this case)

AUTHOR

   Pierre Vigier <[email protected]>

COPYRIGHT

   Copyright 2016- Pierre Vigier

LICENSE

   This library is free software; you can redistribute it and/or modify it
   under the same terms as Perl itself.

SEE ALSO

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.