NAME
    PlugAuth::Client - PlugAuth Client

VERSION
    version 0.20

SYNOPSIS
    In a perl program :

     my $r = PlugAuth::Client->new;

     # Check auth server status and version
     my $check = $r->status;
     my $version = $r->version;

     # Authenticate user "alice", pw "sesame"
     $r->login("alice", "sesame");
     if ($r->auth) {
        print "authentication succeeded\n";
     } else {
        print "authentication failed\n";
     }

     # Authorize "alice" to "POST" to "/board"
     if ($r->authz("alice","POST","board")) {
         print "authorization succeeded\n";
     } else {
         print "authorization failed\n";
     }

DESCRIPTION
    This module provides a perl front-end to the PlugAuth API. For a
    stripped down interface to just the authentication and authorization API
    (that is not including the user/group/authorization management
    functions), see PlugAuth::Client::Tiny.

METHODS
  $client->auth
    Returns true if the PlugAuth server can authenticate the user. Username
    and passwords can be specified with the login method or via the
    application's configuration file, see Clustericious::Client for details.

  $client->authz($user $action, $resource)
    Returns true if the given user ($user) is authorized to perform the
    given action ($action) on the given resource ($resource).

  $client->user
    Returns a list reference containing all usernames.

  $client->create_user( \%args )
    Create a user with the given username and password.

    *   user

        The new user's username

        REQUIRED

    *   password

        The new user's password

        REQUIRED

    *   groups

        List of groups as a comma separated string. Using this option
        requires that the server is running PlugAuth 0.21 or better.

  $client->delete_user( $username )
    Delete the user with the given username.

  $client->groups($user)
    Returns a list reference containing the groups that the given user
    ($user) belongs to.

  $client->change_password($user, $password)
    Change the password of the given user ($user) to a new password
    ($password).

  $client->group
    Returns a list reference containing all group names.

  $client->users($group)
    Returns the list of users belonging to the given group ($group).

  $client->create_group( \%args )
    Create a group.

    *   group

        The name of the new group

    *   users

        Comma separated list (as a string) of the users that should
        initially belong to this group.

  $client->update_group( $group, '--users' => $users )
    Update the given group ($group) replacing the existing list with the new
    list ($users), which is a comma separated list as a string.

  $client->delete_group( $group )
    Delete the given group ($group).

  $client->group_add_user( $group, $user )
    Adds the given user ($user) to the given group ($group)

  $client->group_delete_user( $group, $user )
    Delete the given user ($user) from the given group ($group)

  $client->grant( $user, $action, $resource )
    Grants the given user ($user) the authorization to perform the given
    action ($action) on the given resource ($resource).

  $client->revoke( $user, $action, $resource )
    Revokes permission for the give user ($user) to perform the given action
    ($action) on the given resource ($resource).

  $client->granted
    Returns a list of granted permissions

  $client->actions
    Returns a list reference containing the actions that the PlugAuth server
    knows about.

  $client->host_tag($ip_address, $tag)
    Returns true if the host specified by the given IP address ($ip_address)
    has the given host tag ($tag).

  $client->resources( $user, $action, $resource_regex )
    Returns a list reference containing the resources that match the regex
    provided ($resource_regex) that the given user ($user) can perform the
    given action ($action). To see all the resources that the user can
    perform the given action against, pass in '.*' as the regex.

  $client->action_resources( $user )
    Returns a hash reference of all actions and resources that the given
    user ($user) can perform. The keys in the returned hash are the actions
    and the values are list references containing the resources where those
    actions can be performed by the user.

  $client->audit( $year, $month, $day )
    Interface to the Audit plugin, if it is available.

SEE ALSO
    Clustericious::Client, PlugAuth, plugauthclient, plugauthpasswd,
    PlugAuth::Client::Tiny

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.

