jespa.security

Interface Account

All Superinterfaces:

java.util.Map

All Known Implementing Classes:

LdapAccount, WordPressAccount

public interface Account
extends java.util.Map

A map of attributes representing an account in an identity management system such as Microsoft Active directory, an LDAP server or perhaps an SQL database. The concrete Account implementation is created and managed by the corresponding SecurityProvider implementation. An Account object is usually aquired using the SecurityProvider.getAccount(java.lang.String, java.lang.String[]) method however with some SecurityProviders, an Account may be constructed directly such as for creating an account in the SecurityProvider authority. See the API documentation of the concrete SecurityProvider and Account implementations being used.

The names and corresponding values of attributes that constitute the account depend greatly on the Account implementation. For example, an Active Directory based SecurityProvider may have attributes like sAMAccountName mapped to a String value representing the account name or objectSid mapped to a byte[] array containing the binary representation of the account's SID. An SQL based SecurityProvider would probably have attributes based on database table field names like user_login with a String value representing the account name.

The getProperty and setProperty methods should be favored over the get and set methods of the Map interface. The getProperty and setProperty methods may modify and validate data, perform additional work and throw exceptions whereas the get and set methods may not.

Note: When using the HttpSecurityService, the SecurityProvider used to authenticate a user may be retrieved from within a Servlet or JSP using HttpSecurityServletRequest.getSecurityProvider().

The following example demonstrates how to retrieve Account information from Active Directory using the LdapSecurityProvider from within a JSP. This example assumes that the HttpSecurityService used the NtlmSecurityProvider to authenticate the client as it copies many properties from the NtlmSecurityProvider instance to construct the LdapSecurityProvider.

<%@ page import="jespa.http.HttpSecurityServletRequest" %>
<%@ page import="jespa.security.SecurityProvider" %>
<%@ page import="jespa.security.Account" %>
<%@ page import="jespa.ldap.LdapSecurityProvider" %>
<%
// Get the NtlmSecurityProvider
HttpSecurityServletRequest req = (HttpSecurityServletRequest)request;
NtlmSecurityProvider nsp = (NtlmSecurityProvider)req.getSecurityProvider();

// Create an LdapSecurityProvider based on the NtlmSecurityProvider properties
// Many of the properties have the same meaning, so we can mostly copy them
String[] pnames = new String[] {
    "dns.servers",
    "dns.records.path",
    "dns.cache.ttl",
    "service.acctname",
    "service.password",
    "domain.netbios.name",
    "domain.dns.name",
};
LdapSecurityProvider lsp = new LdapSecurityProvider(nsp, pnames);
// However, we want to 1) use the same domain controller against which the client was
// authenticated and 2) add the LDAP base under which to search for accounts
lsp.setProperty("bindstr", "ldap://" + nsp.getProperty("authority.dns.name") + "/DefaultNamingContext");
// We know the domain controller hostname is correct so we can disable SRV lookups
lsp.setProperty("authority.dns.names.resolve", "false");

// Now we can retrieve any information about an account - in this case just the displayName attribute
Account acct = lsp.getAccount(nsp.getIdentity(), new String[] { "displayName" }); 

out.println("displayName: " + acct.get("displayName"));
%>

Retrieving Account Information from within a JSP using the LdapSecurityProvider

Attributes and Properties

Attributes represent data associated with the account in the SecurityProvider authority such as LDAP entry attributes or SQL table fields. Properties control behavior or perform work that may operate on and generate data or attributes.

Nested Class Summary

Nested classes/interfaces inherited from interface java.util.Map

java.util.Map.Entry<K,V>

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String[]	ALL_ATTRS Used as a parameter with some methods to specify "all attributes".

Method Summary

Modifier and Type	Method and Description
void	changePassword(char[] oldpassword, char[] newpassword) Change the password for this account in the SecurityProvider authority but only if the supplied old password is correct.
void	create() Create a new account in the SecurityProvider with all attribute values of this object.
void	create(java.lang.String[] attrs) Create a new account in the SecurityProvider authority with selected attribute values of this object.
void	delete() Delete an existing account in the SecurityProvider authority.
java.lang.Object	getProperty(java.lang.String name) Retrieve an account attribute or property or throw an exception if it has no value.
java.lang.Object	getProperty(java.lang.String name, java.lang.Object def) Retrieve an account attribute or property.
boolean	isMemberOf(java.lang.String group) Return true only if this Account is a member of the named group.
void	setPassword(char[] password) Set the password for this account to the supplied value in the SecurityProvider authority.
void	setProperty(java.lang.String name, java.lang.Object obj) Set an account attribute or property.
void	update() Update an existing account in the SecurityProvider authority with all attribute values of this object.
void	update(java.lang.String[] attrs) Update an existing account in the SecurityProvider authority with selected attribute values of this object.

Methods inherited from interface java.util.Map

clear, compute, computeIfAbsent, computeIfPresent, containsKey, containsValue, entrySet, equals, forEach, get, getOrDefault, hashCode, isEmpty, keySet, merge, put, putAll, putIfAbsent, remove, remove, replace, replace, replaceAll, size, values

Field Detail

ALL_ATTRS

static final java.lang.String[] ALL_ATTRS

Used as a parameter with some methods to specify "all attributes". The interpretation of this value is defined by the SecurityProvider implementation. This constant can be used with methods like SecurityProvider.getAccount(java.lang.String, java.lang.String[]), create(java.lang.String[]) and update(java.lang.String[]). See the API documentation for these methods for the SecurityProvider and Account implementation being used.

Method Detail

setProperty

void setProperty(java.lang.String name,
                 java.lang.Object obj)
          throws SecurityProviderException

Set an account attribute or property. Account attribute and property names and values are defined by the concrete Account implementation. For details, see the API documentation of the concrete Account implemention being used.

Parameters:

name - the name of the attribute or property

obj - the value of the attribute or property to set

Throws:

SecurityProviderException - if an error occurs setting the attribute or property such as a validation failure

getProperty

java.lang.Object getProperty(java.lang.String name,
                             java.lang.Object def)
                      throws SecurityProviderException

Retrieve an account attribute or property. Account attribute and property names and values are defined by the concrete Account implementation. For details, see the API documentation of the concrete Account implemention being used.

Parameters:

name - the name of the attribute or property to be retrieved

def - the default value to be returned of the named attribute or property has no value

Returns:

the value of the named attribute or property

Throws:

SecurityProviderException - if an error occurs retrieving the attribute or property

getProperty

java.lang.Object getProperty(java.lang.String name)
                      throws SecurityProviderException

Retrieve an account attribute or property or throw an exception if it has no value. Account attribute and property names and values are defined by the concrete Account implementation. For details, see the API documentation of the concrete Account implemention being used.

Parameters:

name - the name of the attribute or property to be retrieved

Returns:

the value of the named attribute or property

Throws:

SecurityProviderException - if the named attribute or property is not mapped to a value or if an error occurs retrieving the value

isMemberOf

boolean isMemberOf(java.lang.String group)
            throws SecurityProviderException

Return true only if this Account is a member of the named group. The format of the group name depends on the Account implementation. For example, if the Account was acquired through the NtlmSecurityProvider, a Windows group name like EXAMPLE\Domain Users might be used.

Parameters:

group - the name of the group to check.

Returns:

true if the Account is in the named group and false otherwise

Throws:

SecurityProviderException - if a catostrophic error occurs trying to check group membership

create

void create(java.lang.String[] attrs)
     throws SecurityProviderException

Create a new account in the SecurityProvider authority with selected attribute values of this object. The implementation may:

• throw an exception if one or more required attributes are not present in this object,
• throw an exception if an attribute value fails validation,
• automatically generate and add additional attributes to this object before creating the account, or
• silently choose not to create an attribute with the account even if it was explicitly requested in the attrs parameter.

For specific implementation details, see the API documentation of the concrete Account class being used.

Parameters:

attrs - an array of attribute names indicating the attributes of this object with which to create the account. If this parameter is the special constant Account.ALL_ATTRS, the account will be created with all attributes of this object. If this parameter is null, the account will be created with an implementation defined set of attributes of this object.

Throws:

SecurityProviderException - if an error occurs creating the account. If an account with the same identity already exists, the implementation should throw a SecurityProviderException with an error code of SecurityProviderException.STATUS_ALREADY_EXISTS.

create

void create()
     throws SecurityProviderException

Create a new account in the SecurityProvider with all attribute values of this object. This method is equivalent to create(Account.ALL_ATTRS). See the create(String[]) method for additional details.

Throws:

SecurityProviderException - if an error occurs creating the account. If an account with the same identity already exists, the implementation should throw a SecurityProviderException with an error code of SecurityProviderException.STATUS_ALREADY_EXISTS.

update

void update(java.lang.String[] attrs)
     throws SecurityProviderException

Update an existing account in the SecurityProvider authority with selected attribute values of this object. At least one attribute representing the identity of the account being updated must be present in this object. The behavior of this method depends greatly on the SecurityProvider implementation. See the API documentation of the concrete Account implementation being used for details.

Note: In practice, this method should not be called on the default Account object obtained through SecurityProvider.getAccount using a null account name. This is because the default Account object is frequently constructed from exported data and therefore it's contents may not be current which, depending on the implementation, can result in unexpected update behavior.

Parameters:

attrs - a list of attribute names indicating the attributes of this object to be updated.

Throws:

SecurityProviderException - if an error occurs updating the account. If the account being updated is not found, the implementation should throw a SecurityProviderException with an error code of SecurityProviderException.STATUS_ACCOUNT_NOT_FOUND.

update

void update()
     throws SecurityProviderException

Update an existing account in the SecurityProvider authority with all attribute values of this object. This method is equivalent to update(Account.ALL_ATTRS). See the update(String[]) method for additional details.

Throws:

SecurityProviderException - if an error occurs updating the account. If the account being updated is not found, the implementation should throw a SecurityProviderException with an error code of SecurityProviderException.STATUS_ACCOUNT_NOT_FOUND.

delete

void delete()
     throws SecurityProviderException

Delete an existing account in the SecurityProvider authority. See the API documentation of the concrete Account implementation being used for details.

Throws:

SecurityProviderException - if an error occurs deleting the account. If the account being deleted is not found, the implementation should throw a SecurityProviderException with an error code of SecurityProviderException.STATUS_ACCOUNT_NOT_FOUND.

setPassword

void setPassword(char[] password)
          throws SecurityProviderException

Set the password for this account to the supplied value in the SecurityProvider authority. See the API documentation of the concrete Account implementation being used for details.

Throws:

SecurityProviderException - if an error occurs setting the account password. If the account being updated is not found, the implementation should throw a SecurityProviderException with an error code of SecurityProviderException.STATUS_ACCOUNT_NOT_FOUND.

changePassword

void changePassword(char[] oldpassword,
                    char[] newpassword)
             throws SecurityProviderException

Change the password for this account in the SecurityProvider authority but only if the supplied old password is correct. See the API documentation of the concrete Account implementation being used for details.

Parameters:

oldpassword - the current password for this account.

newpassword - the new password to be set on this account.

Throws:

SecurityProviderException - if an error occurs validating the old or setting the new password for this account. If the account being updated is not found, the implementation should throw a SecurityProviderException with an error code of SecurityProviderException.STATUS_ACCOUNT_NOT_FOUND.