Poco::OSP::Auth

class AuthAdminService

File Information

Library: OSP/Auth
Package: Auth
Header: Poco/OSP/Auth/AuthAdminService.h

Description

This service interface extends the basic AuthService interface with methods for administrating users, roles and their permissions.

Users can have assigned permissions and roles. Roles have assigned permissions as well. The effective permissions of a user are his directly assigned permissions plus the permissions assigned through the roles has has been assigned. Use of roles is thus optional.

Each user can have an arbitrary number of attributes.

Inheritance

Direct Base Classes: AuthService

All Base Classes: AuthService, Poco::OSP::Service, Poco::RefCountedObject

Known Derived Classes: PooledAuthAdminService, AbstractLDAPAuthAdminService

Member Summary

Member Functions: addRole, addUser, assignRoleToUser, attributesForUser, changePassword, effectivePermissionsForUser, findUsersByAttribute, getUserAttribute, grantPermissionsToRole, grantPermissionsToUser, invalidateCaches, isA, isExternalUser, isUserLockedOut, lockOutUser, permissionsForRole, permissionsForUser, removeRole, removeRoleFromUser, removeUser, removeUserAttribute, replacePermissionsForRole, replacePermissionsForUser, replaceRolesForUser, replaceUserAttributes, reset, revokePermission, revokePermissionsFromRole, revokePermissionsFromUser, roleExists, roles, rolesForUser, setUserAttribute, type, uncacheUser, unlockOutUser, updateUserAttributes, userEnabled, users, usersWithAttribute, usersWithName, usersWithPermission, usersWithRole

Inherited Functions: authenticate, authorize, duplicate, isA, referenceCount, release, type, userExists

Nested Classes

struct ValidateUserEvent

 

Types Aliases

Ptr

using Ptr = Poco::AutoPtr < AuthAdminService >;

Enumerations

Anonymous

INVALIDATE_CACHED_PASSWORDS = 1

INVALIDATE_CACHED_PERMISSIONS = 2

INVALIDATE_ALL = INVALIDATE_CACHED_PASSWORDS | INVALIDATE_CACHED_PASSWORDS

Member Functions

addRole virtual

virtual void addRole(
    const std::string & rolename
) = 0;

Adds a new role to the database.

Throws a Poco::ExistsException if a role with the given name already exists.

addUser virtual

virtual void addUser(
    const std::string & username,
    const std::string & password
) = 0;

Adds a new user to the database.

Throws a Poco::ExistsException if an user with the given username already exists.

assignRoleToUser virtual

virtual void assignRoleToUser(
    const std::string & username,
    const std::string & rolename
) = 0;

Assigns a role to an user.

Throws a Poco::NotFoundException if the user or role does not exist. Does nothing if the user already has the role.

attributesForUser virtual

virtual void attributesForUser(
    const std::string & username,
    std::set < std::string > & attributes
) const = 0;

Returns the names of all attributes set for the given username.

attributesForUser virtual

virtual void attributesForUser(
    const std::string & username,
    std::map < std::string, std::string > & attributes
) const = 0;

Returns the names and values of all attributes set for the given username.

changePassword virtual

virtual void changePassword(
    const std::string & username,
    const std::string & password
) = 0;

Changes the password for the user with the given username.

effectivePermissionsForUser virtual

virtual void effectivePermissionsForUser(
    const std::string & username,
    std::set < std::string > & permissions
) const = 0;

Returns a set of permissions for the user given by username. Both permissions directly granted to the user and permissions granted indirectly through roles will be included in the result.

Throws a Poco::NotFoundException if the user does not exist.

findUsersByAttribute virtual

virtual std::vector < std::string > findUsersByAttribute(
    const std::string & attribute,
    const std::string & value
) const = 0;

Returns the names of all users having an attribute with the given value.

getUserAttribute virtual

virtual std::string getUserAttribute(
    const std::string & username,
    const std::string & attribute,
    const std::string & deflt = std::string ()
) const = 0;

Returns the value of a user attribute, or the specified default value if the user attribute does not exist.

grantPermissionsToRole virtual

virtual void grantPermissionsToRole(
    const std::string & rolename,
    const std::set < std::string > & permissions
) = 0;

Grants the given permissions to the role identified by rolename.

Throws a Poco::NotFoundException if the role does not exist.

grantPermissionsToUser virtual

virtual void grantPermissionsToUser(
    const std::string & username,
    const std::set < std::string > & permissions
) = 0;

Grants the given permissions to the user identified by username.

Throws a Poco::NotFoundException if the user does not exist.

invalidateCaches virtual

virtual void invalidateCaches(
    int what = INVALIDATE_ALL
) = 0;

Invalidates cached data. The parameter specifies which caches to invalidate.

isA virtual

bool isA(
    const std::type_info & otherType
) const;

See also: Poco::OSP::Auth::AuthService::isA()

isExternalUser virtual

virtual bool isExternalUser(
    const std::string & username
) const = 0;

Returns true if the given username is managed externally, e.g. by and LDAP server.

isUserLockedOut virtual

virtual bool isUserLockedOut(
    const std::string & username
) const = 0;

Returns true if the given username has been locked out, otherwise false.

lockOutUser virtual

virtual void lockOutUser(
    const std::string & username,
    const Poco::DateTime & lockOutUntil
) = 0;

Locks out the given username until the given date/time.

permissionsForRole virtual

virtual void permissionsForRole(
    const std::string & rolename,
    std::set < std::string > & permissions
) const = 0;

Returns a set of permissions for the role given by rolename.

Throws a Poco::NotFoundException if the role does not exist.

permissionsForUser virtual

virtual void permissionsForUser(
    const std::string & username,
    std::set < std::string > & permissions
) const = 0;

Returns a set of permissions for the user given by username. Only permissions directly granted to the user will be returned. Permissions granted indirectly through roles will not be included.

Throws a Poco::NotFoundException if the user does not exist.

removeRole virtual

virtual void removeRole(
    const std::string & rolename
) = 0;

Removes the role identified by name from the database.

Throws a Poco::NotFoundException if the role does not exist.

removeRoleFromUser virtual

virtual void removeRoleFromUser(
    const std::string & username,
    const std::string & rolename
) = 0;

Removes a role from an user.

Throws a Poco::NotFoundException if the user does not exist. Does nothing if the user does not have the role.

removeUser virtual

virtual void removeUser(
    const std::string & username
) = 0;

Removes the user identified by username from the database.

Throws a Poco::NotFoundException if the user does not exist.

removeUserAttribute virtual

virtual void removeUserAttribute(
    const std::string & username,
    const std::string & attribute
) = 0;

Removes the given attribute from username.

replacePermissionsForRole virtual

virtual void replacePermissionsForRole(
    const std::string & rolename,
    const std::set < std::string > & permissions
) = 0;

Removes all previously granted permissions and grants the given permissions to the role identified by rolename.

Throws a Poco::NotFoundException if the role does not exist.

replacePermissionsForUser virtual

virtual void replacePermissionsForUser(
    const std::string & username,
    const std::set < std::string > & permissions
) = 0;

Removes all previously granted permissions and grants the given permissions to the user identified by username.

Throws a Poco::NotFoundException if the user does not exist.

replaceRolesForUser virtual

virtual void replaceRolesForUser(
    const std::string & username,
    const std::set < std::string > & roles
) = 0;

Unassignes all roles from the user, then assigns the given roles.

Throws a Poco::NotFoundException if the user does not exist.

replaceUserAttributes virtual

virtual void replaceUserAttributes(
    const std::string & username,
    const std::map < std::string, std::string > & attributes
) = 0;

Replaces the attributes of the given user. Will also remove all other attributes.

reset virtual

virtual void reset() = 0;

Resets the service, clearing the cache and re-connecting the database.

revokePermission virtual

virtual void revokePermission(
    const std::string & permission
) = 0;

Revokes the given permission from all users and roles.

revokePermissionsFromRole virtual

virtual void revokePermissionsFromRole(
    const std::string & rolename,
    const std::set < std::string > & permissions
) = 0;

Revokes the given permissions from the role identified by rolename.

Throws a Poco::NotFoundException if the role does not exist.

revokePermissionsFromUser virtual

virtual void revokePermissionsFromUser(
    const std::string & username,
    const std::set < std::string > & permissions
) = 0;

Revokes the given permissions from the user identified by username.

Throws a Poco::NotFoundException if the user does not exist.

roleExists virtual

virtual bool roleExists(
    const std::string & rolename
) const = 0;

Returns true if and only if a role with the given rolename exists.

roles virtual

virtual void roles(
    std::set < std::string > & roles
) const = 0;

Returns a set of all roles in the database.

rolesForUser virtual

virtual void rolesForUser(
    const std::string & username,
    std::set < std::string > & roles
) const = 0;

Returns the set of roles assigned to the user identified by username.

setUserAttribute virtual

virtual void setUserAttribute(
    const std::string & username,
    const std::string & attribute,
    const std::string & value
) = 0;

Sets the value of a user attribute.

type virtual

const std::type_info & type() const;

See also: Poco::OSP::Auth::AuthService::type()

uncacheUser virtual

virtual void uncacheUser(
    const std::string & username
) = 0;

Removes all cached data for the user with the given name.

Should be done when a user logs out of an application.

unlockOutUser virtual

virtual void unlockOutUser(
    const std::string & username
) = 0;

Unlocks out the given username.

updateUserAttributes virtual

virtual void updateUserAttributes(
    const std::string & username,
    const std::map < std::string, std::string > & attributes
) = 0;

Updates the attributes of the given user.

userEnabled virtual

virtual bool userEnabled(
    const std::string & username
) const = 0;

Returns true if the user with the given username is enabled.

If the implementation has no concept of disabling user accounts, this should just return true.

users virtual

virtual int users(
    std::set < std::string > & users,
    int first = 0,
    int limit = 0
) const = 0;

Returns a list of all users in the database.

This method supports "paged" retrieval. First specifies the index of the first user to be returned. Limit specifies the maximum number of users to return.

Returns the total number of users.

usersWithAttribute virtual

virtual int usersWithAttribute(
    std::set < std::string > & users,
    const std::string & attribute,
    const std::string & value,
    int first = 0,
    int limit = 0
) const = 0;

Returns a list of all users in the database having the given attribute.

This method supports "paged" retrieval. First specifies the index of the first user to be returned. Limit specifies the maximum number of users to return.

Returns the total number of users with the given attribute.

usersWithName virtual

virtual int usersWithName(
    std::set < std::string > & users,
    const std::string & pattern,
    int first = 0,
    int limit = 0
) const = 0;

Returns a list of all users in the database matching the given pattern.

An asterisk '*' in the expression matches any sequence of characters, even an empty sequence. A question mark '?' matches any single character.

This method supports "paged" retrieval. First specifies the index of the first user to be returned. Limit specifies the maximum number of users to return.

Returns the total number of users.

usersWithPermission virtual

virtual int usersWithPermission(
    std::set < std::string > & users,
    const std::string & permission,
    int first = 0,
    int limit = 0
) const = 0;

Returns a list of all users in the database having the given permission.

Only users having the given permission granted explicitly are returned. Users having a permission only granted implicitly via a role are ignored.

This method supports "paged" retrieval. First specifies the index of the first user to be returned. Limit specifies the maximum number of users to return.

Returns the total number of users with the given permission.

usersWithRole virtual

virtual int usersWithRole(
    std::set < std::string > & users,
    const std::string & role,
    int first = 0,
    int limit = 0
) const = 0;

Returns a list of all users in the database having the given role.

Only users having been explicitly assigned the role are returned.

This method supports "paged" retrieval. First specifies the index of the first user to be returned. Limit specifies the maximum number of users to return.

Returns the total number of users with the given role.

Variables

SERVICE_NAME static

static const std::string SERVICE_NAME;

roleAdded

Poco::BasicEvent < const std::string > roleAdded;

Fired when a new role has been created.

roleRemoved

Poco::BasicEvent < const std::string > roleRemoved;

Fired when a role has been removed.

userAdded

Poco::BasicEvent < const std::string > userAdded;

Fired when a new user account has been created.

userRemoved

Poco::BasicEvent < const std::string > userRemoved;

Fired when a user account has been removed.

validateUser

Poco::BasicEvent < ValidateUserEvent > validateUser;

Fired during authenticate() or userEnabled() to perform application-specific validation of a user account. This can be used to check if a user account has expired or otherwise disabled at the application level.