++ed by:
KEEDI

1 PAUSE user
1 non-PAUSE user.

Graham Ollis

NAME

PlugAuth::Routes - routes for plugauth

VERSION

version 0.30

DESCRIPTION

This module defines the HTTP URL routes provided by PlugAuth. This document uses Mojolicious conventions to describe routes, see Mojolicious::Guides::Routing for details.

ROUTES

Public routes

These routes work for unauthenticated and unauthorized users.

GET /

Returns the string "welcome to plug auth"

GET /auth

  • if username and password provided using BASIC authentication and are correct

    Return 200 ok

  • if username and password provided using BASIC authentication but are not correct

    Return 403 not ok

  • if username and password are not provided using BASIC authentication

    Return 401 please authenticate

GET /authz/user/#user/#action/(*resource)

  • if the given user (#user) is permitted to perform the given action (#action) on the given resource (*resource)

    Return 200 ok

  • otherwise

    Return 403 "unauthorized : $user cannot $action $resource"

GET /authz/resources/#user/#action/(*resourceregex)

Returns a list of resources that the given user (#user) is permitted to perform action (#action) on. The regex is used to filter the results (*resourceregex).

GET /actions

Return a list of actions that PlugAuth knows about.

GET /groups/#user

Return a list of groups that the given user (#user) belongs to.

Returns 404 not ok if the user does not exist.

GET /host/#host/:tag

  • if the given host (#host) has the given tag (:tag)

    return 200 ok

  • otherwise

    return 403 not ok

GET /user

Returns a list of all users that PlugAuth knows about.

GET /group

Returns a list of all groups that PlugAuth knows about.

GET /users/:group

Returns the list of users that belong to the given group (:group)

Accounts Routes

These routes are available to users authenticates and authorized to perform the 'accounts' action. They will return

  • 401

    If no credentials are provided

  • 403

    If the user is unauthorized.

  • 503

    If the PlugAuth server cannot reach itself or the delegated PlugAuth server.

POST /user

Create a user. The username and password are provided autodata arguments (JSON, YAML, form data, etc).

If supported by your authentication plugin (requires create_user_cb to be implemented see PlugAuth::Plugin::Auth for details) You may also optionally include groups as an autodata argument, which specifies the list of groups to which the new user should belong. groups should be a comma separated list stored as a string.

Emits event 'create_user' on success

 $app->on(create_user => sub {
   my($event, $hash) = @_;
   my $admin    = $hash->{admin};  # user who created the group
   my $user     = $hash->{user};
 });

DELETE /user/#user

Delete the given user (#user). Returns 200 ok on success, 404 not ok on failure.

Emits event 'delete_user' on success

 $app->on(delete_user => sub {
   my($event, $hash) = @_;
   my $admin    = $hash->{admin};  # user who created the group
   my $user     = $hash->{user};
 });

POST /group

Create a group. The group name and list of users are provided as autodata arguments (JSON, YAML, form data etc). Returns 200 ok on success, 403 not ok on failure.

Emits event 'create_group' on success

 $app->on(create_group => sub {
   my($event, $hash) = @_;
   my $admin    = $hash->{admin};  # user who created the group
   my $group    = $hash->{group};
   my $users    = $hash->{users};
 });

DELETE /group/:group

Delete the given group (:group). Returns 200 ok on success, 403 not ok on failure.

Emits event 'delete_group' on success

 $app->on(delete_group => sub {
   my($event, $hash) = @_;
   my $admin    = $hash->{admin};  # user who deleted the group
   my $group    = $hash->{group};
 });

POST /group/:group

Update the list of users belonging to the given group (:group). The list of users is provided as an autodata argument (JSON, YAML, form data etc.). Returns 200 ok on success, 404 not ok on failure.

Emits event 'update_group' on success

 $app->on(update_group => sub {
   my($event, $hash) = @_;
   my $admin    = $hash->{admin};  # user who updated the group
   my $group    = $hash->{group};
   my $users    = $hash->{users};
 });

POST /group/:group/#username

Add the given user (#username) to the given group (:group). Returns 200 ok on success, 404 not ok on failure.

Emits event 'update_group' (see route for POST /group/:group for an example).

DELETE /group/:group/#username

Remove the given user (#username) from the given group (:group). Returns 200 ok on success, 404 not ok on failure.

Emits event 'update_group' (see route for POST /group/:group for an example).

POST /grant/#group/:action1/(*resource)

Grant access to the given group (#group) so they can perform the given action (:action1) on the given resource (*resource). Returns 200 ok on success, 404 not ok on failure.

Emits event 'grant' on success

 $app->on(grant => sub {
   my($event, $hash) = @_;
   my $admin    = $hash->{admin};  # user who did the granting
   my $group    = $hash->{group};
   my $action   = $hash->{action};
   my $resource = $hash->{resource};
 });

DELETE /grant/#group/:action1/(*resource)

Revoke permission to the given group (#group) to perform the given action (:action1) on the given resource (*resource). Returns 200 ok on success, 404 not ok on failure.

(the action is specified in the route as action1 because action is reserved by Mojolicious).

Emits event 'revoke' on success

 $app->on(revoke => sub {
   my($event, $hash) = @_;
   my $admin    = $hash->{admin};  # user who did the revoking
   my $group    = $hash->{group};
   my $action   = $hash->{action};
   my $resource = $hash->{resource};
 });

GET /grant

Get the list of granted permissions.

Change Password routes

These routes are available to users authenticates and authorized to perform the 'change_password' action. They will return

  • 401

    If no credentials are provided

  • 403

    If the user is unauthorized.

  • 503

    If the PlugAuth server cannot reach itself or the delegated PlugAuth server.

POST /user/#user

Change the password of the given user (#user). The password is provided as an autodata argument (JSON, YAML, form data, etc.). Returns 200 ok on success, 403 not ok on failure.

Emits event 'change_password' on success

 $app->on(change_password => sub {
   my($event, $hash) = @_;
   my $admin = $hash->{admin};  # user who changed the password
   my $user  = $hash->{user};   # user whos password is changed
 });

SEE ALSO

PlugAuth

AUTHOR

Graham Ollis <gollis@sesda3.com>

COPYRIGHT AND LICENSE

This software is copyright (c) 2012 by NASA GSFC.

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