org.jboss.seam.security

Interface Identity

public interface Identity

API for authorization and authentication via Seam security.

Author:

Shane Bryzak

Field Summary

Fields

Modifier and Type	Field and Description
static String	RESPONSE_LOGIN_EXCEPTION
static String	RESPONSE_LOGIN_FAILED
static String	RESPONSE_LOGIN_SUCCESS

Method Summary

Methods

Modifier and Type	Method and Description
boolean	addGroup(String name, String groupType) Adds the user to the specified group.
boolean	addRole(String role, String group, String groupType) Adds a role to the authenticated user.
void	checkGroup(String group, String groupType)
void	checkPermission(Object resource, String permission) Checks if the currently authenticated user has the specified permission for the specified resource.
void	checkRestriction(String expr) Performs an authorization check, based on the specified security expression string.
void	checkRole(String role, String group, String groupType) Checks that the current authenticated user is a member of the specified role.
void	filterByPermission(Collection<?> collection, String permission) Filters a collection of objects by a specified action, by removing the objects from the collection for which the user doesn't have the necessary privileges to perform the specified action against that object.
Class<? extends Authenticator>	getAuthenticatorClass()
String	getAuthenticatorName()
Set<org.picketlink.idm.api.Group>	getGroups() Returns an immutable set containing all the current user's group memberships
Set<org.picketlink.idm.api.Role>	getRoles() Returns an immutable set containing all the current user's granted roles
org.picketlink.idm.api.User	getUser() Returns the currently authenticated user
boolean	hasPermission(Object resource, String permission) Checks if the currently authenticated user has the necessary permission for a specific resource.
boolean	hasRole(String role, String group, String groupType) Checks if the authenticated user is a member of the specified role.
boolean	inGroup(String name, String groupType) Checks if the authenticated user is a member of the specified group
boolean	isLoggedIn() Simple check that returns true if the user is logged in, without attempting to authenticate
boolean	isVerified() Returns true if the currently authenticated user has provided their correct credentials within the verification window configured by the application.
String	login() Attempts to authenticate the user.
void	logout() Logs out the currently authenticated user
void	quietLogin() Attempts a quiet login, suppressing any login exceptions and not creating any faces messages.
void	removeGroup(String name, String groupType) Removes the currently authenticated user from the specified group
void	removeRole(String role, String group, String groupType) Removes a role from the authenticated user
void	setAuthenticatorClass(Class<? extends Authenticator> authenticatorClass)
void	setAuthenticatorName(String authenticatorName)
boolean	tryLogin() Will attempt to authenticate quietly if the user's credentials are set and they haven't authenticated already.

Field Detail

RESPONSE_LOGIN_SUCCESS

static final String RESPONSE_LOGIN_SUCCESS

See Also:

Constant Field Values

RESPONSE_LOGIN_FAILED

static final String RESPONSE_LOGIN_FAILED

See Also:

Constant Field Values

RESPONSE_LOGIN_EXCEPTION

static final String RESPONSE_LOGIN_EXCEPTION

See Also:

Constant Field Values

Method Detail

isLoggedIn

@LoggedIn
boolean isLoggedIn()

Simple check that returns true if the user is logged in, without attempting to authenticate

Returns:

true if the user is logged in

isVerified

boolean isVerified()

Returns true if the currently authenticated user has provided their correct credentials within the verification window configured by the application.

Returns:

tryLogin

boolean tryLogin()

Will attempt to authenticate quietly if the user's credentials are set and they haven't authenticated already. A quiet authentication doesn't throw any exceptions if authentication fails.

Returns:

true if the user is logged in, false otherwise

getUser

org.picketlink.idm.api.User getUser()

Returns the currently authenticated user

Returns:

checkRestriction

void checkRestriction(String expr)

Performs an authorization check, based on the specified security expression string.

Parameters:

expr - The security expression string to evaluate

Throws:

NotLoggedInException - Thrown if the authorization check fails and the user is not authenticated

AuthorizationException - Thrown if the authorization check fails and the user is authenticated

login

String login()

Attempts to authenticate the user. This method raises the following events in response to whether authentication is successful or not. The following events may be raised during the call to login():

org.jboss.seam.security.events.LoggedInEvent - raised when authentication is successful org.jboss.seam.security.events.LoginFailedEvent - raised when authentication fails org.jboss.seam.security.events.AlreadyLoggedInEvent - raised if the user is already authenticated

Returns:

String returns RESPONSE_LOGIN_SUCCESS if user is authenticated, RESPONSE_LOGIN_FAILED if authentication failed, or RESPONSE_LOGIN_EXCEPTION if an exception occurred during authentication. These response codes may be used to control user navigation. For deferred authentication methods, such as Open ID the login() method will return an immediate result of RESPONSE_LOGIN_FAILED (and subsequently fire a LoginFailedEvent) however in these conditions it is the responsibility of the Authenticator implementation to take over the authentication process, for example by redirecting the user to another authentication service.

quietLogin

void quietLogin()

Attempts a quiet login, suppressing any login exceptions and not creating any faces messages. This method is intended to be used primarily as an internal API call, however has been made public for convenience.

logout

void logout()

Logs out the currently authenticated user

hasRole

boolean hasRole(String role,
              String group,
              String groupType)

Checks if the authenticated user is a member of the specified role.

Parameters:

role - String The name of the role to check

Returns:

boolean True if the user is a member of the specified role

addRole

boolean addRole(String role,
              String group,
              String groupType)

Adds a role to the authenticated user. If the user is not logged in, the role will be added to a list of roles that will be granted to the user upon successful authentication, but only during the authentication process.

Parameters:

role - The name of the role to add

inGroup

boolean inGroup(String name,
              String groupType)

Checks if the authenticated user is a member of the specified group

Parameters:

name - The name of the group

groupType - The type of the group, e.g. "office", "department", "global role", etc

Returns:

true if the user is a member of the group

addGroup

boolean addGroup(String name,
               String groupType)

Adds the user to the specified group. See hasRole() for semantics in relationship to the authenticated status of the user.

Parameters:

name - The name of the group

groupType - The type of the group

Returns:

true if the group was successfully added

removeGroup

void removeGroup(String name,
               String groupType)

Removes the currently authenticated user from the specified group

Parameters:

name - The name of the group

groupType - The type of the group

removeRole

void removeRole(String role,
              String group,
              String groupType)

Removes a role from the authenticated user

Parameters:

role - The name of the role to remove

checkRole

void checkRole(String role,
             String group,
             String groupType)

Checks that the current authenticated user is a member of the specified role.

Parameters:

role - String The name of the role to check

Throws:

AuthorizationException - if the authenticated user is not a member of the role

checkGroup

void checkGroup(String group,
              String groupType)

Parameters:

group -

groupType -

checkPermission

void checkPermission(Object resource,
                   String permission)

Checks if the currently authenticated user has the specified permission for the specified resource.

Parameters:

resource - The resource for which the user wishes to perform a restricted action

permission - The name of the permission that the user requires to invoke the operation

Throws:

NotLoggedInException - if the current user is not authenticated

AuthorizationException - if the current user does not have the necessary permission for the specified resource object.

filterByPermission

void filterByPermission(Collection<?> collection,
                      String permission)

Filters a collection of objects by a specified action, by removing the objects from the collection for which the user doesn't have the necessary privileges to perform the specified action against that object.

Parameters:

collection - The Collection to filter

action - The name of the action to filter by

hasPermission

boolean hasPermission(Object resource,
                    String permission)

Checks if the currently authenticated user has the necessary permission for a specific resource.

Returns:

true if the user has the required permission, otherwise false

getRoles

Set<org.picketlink.idm.api.Role> getRoles()

Returns an immutable set containing all the current user's granted roles

Returns:

getGroups

Set<org.picketlink.idm.api.Group> getGroups()

Returns an immutable set containing all the current user's group memberships

Returns:

getAuthenticatorClass

Class<? extends Authenticator> getAuthenticatorClass()

setAuthenticatorClass

void setAuthenticatorClass(Class<? extends Authenticator> authenticatorClass)

getAuthenticatorName

String getAuthenticatorName()

setAuthenticatorName

void setAuthenticatorName(String authenticatorName)