UserManagementState

Introduction and overview

It is sometimes necessary to mutate a directory as a response to some authentication events. The JNDI-based UserManagementState AuthState can modify user attributes and assign roles. The AuthState supports the following features:

• User creation, using one or several configurable objectClasses.
• Attribute modification, supporting list attributes.
• Creation of user groups (roles)
• Assigning of roles and users.

Description

The following table and chapters describe the characteristics of the AuthState.

Topic	Description
Class	ch.nevis.esauth.auth.states.jndi.UserManagementState
Logging	JNDI
Auditing	none
Marker	none
Methods	authenticate, stepup

Properties

• connection1, ..., connection9, searchSizeLimit, userBaseDN, userFilter, loginidField

  For a description of these properties, see UseridPasswordAuthenticateState - Description.

  This AuthState uses the LDAP protocol when it establishes a connection with an LDAP server. The AuthState is thus susceptible to SOCKS proxies, as described in the chapter Configuring proxies.

• dirStyle (enum { SunONE, AD, AD-basic, OpenLDAP, eDirectory }. -)

  The directory style is used to control directory-dependent behavior of the AuthState:

  • SunONE: no special behavior.
  • AD: no special behavior.
  • AD-basic: no special behavior.
  • OpenLDAP: no special behavior.
  • eDirectory: support for eDirectory's groupMembership attribute.

User

• userCN (string, -)

  The CN of the user object.

• userBaseDN (DN, -)

  This property specifies the directory subtree where user profile data needs to be queried. If the user object is created, it will be created in this subtree.

• userObjectClass (string, "user")

  ObjectClass(es) of the user. If the user is created, it will be created with those classes. All mandatory attributes of all userObjectClasses must be filled in userAttributes if the user object is to be created.

• createUser (boolean, false)

  When set to "true", a new user object will be created if none was found.

• userCreateAttributes (string, -)

  Whitespace-separated list of attributes and attribute values to be set on a new user object in the directory.

  Syntax: <attribute-name>:<attribute-value>

  Examples

  givenName:${inargs:givenname}
  description:${notes:user.description}

• userUpdateAttributes (string, -)

  Same as userCreateAttributes but for update operations.

• removeAttributes (boolean, false)

  This parameter signals whether attributes that are defined in the configuration will be removed if the variables they resolve in the configuration are not defined. This only works if an attribute value is configured as only one substitution expression. E.g., attr1:${src:var} is okay, but for attr2:prefix${src:var}_ no removal will ever be made.

Role

• roleCN (string, -)

  This property defines a whitespace-separated or comma-separated list of roleCNs that the user should be assigned to. The roles will be searched individually in the roleBaseDN and if found or created (see createRole), the user will be assigned to each role.

• roleBaseDN (DN, -)

  This property specifies the directory subtree where roles will be queried. If the role object is created, it will be created in this subtree. roleBaseDN is evaluated individually for each role of roleCN. The temporary note role (${notes:role}) may be used to modify the roleBaseDN according to a roleCN.

• roleObjectClass (string, "group")

  ObjectClass of the role object. If the role is created, it will be created with this objectClass.

• roleFilter (JNDI filter, see below)

  Specifying this property allows to customize the role query to apply to the tree, specified by roleBaseDN. If not defined, the role filter will be constructed to match the configured roleObjectClass.

• createRole (boolean, false)

  When set to "true", a new role object will be created if none was found.

• roleWhitelist (whitespace-separated list of roleDNs, -)

  This attribute is used to specify a whitelist of acceptable roles to be stored in the LDAP directory. If the value starts with a ^ and ends with a $, it is treated as a regular expression.

• roleWhitelistMode (enum {allow,block,abort}, block)

  This attribute allows to configure actions on roles that do not match the roleWhiteList configuration. The following actions are possible:

  • allow Accept this role anyway and write it to the directory.
  • block Do not accept the role, but continue as normal
  • abort Do not modify or write the user and abort with result invalidrole

• roleMembershipAttribute (string, "member")

  This attribute allows to configure the attribute name to use for storing role membership references.

• removeRoles (boolean, false)

  If this attribute is set to "true", the user will be removed from any roles that cannot be matched with a roleCN in the roleBaseDN context.

Input

none

Transitions

• ok

  User was created or modified or user's attributes accord with userAttributes. Role created and/or assigned successfully.

• usernotfound

  User was not found in directory (if createUser="false").

Output

none

Errors

• lasterror=1

  lasterrorinfo=invalid input

• lasterror=1

  lasterrorinfo=user not found in root directory

Notes

• userdn

  Directory DN of the user, if found.

Example

<AuthState name="RegisterUser" class="ch.nevis.esauth.auth.states.jndi.UserManagementState" final="false">
    <ResultCond name="ok" next="nextState"/>
    <Response value="AUTH_ERROR" >
        <Gui name="ERRORDialog"/>
    </Response>
    <property name="connection1" value="ldap://192.168.9.207:389"/>
    <property name="dirStyle" value="eDirectory"/>
    <property name="createUser" value="true"/>
    <property name="userObjectClass" value="user, userExtensions"/>
    <property name="userCN" value="${notes:userid}" />
    <property name="userBaseDN" value="ou=${notes:user.ou},ou=USERS,o=COMPANY" />
    <property name="userAttributes" value="language:${notes:user.language}
                                           sn:${notes:user.surname}
                                           lastSeen:${system:time}" />
    <property name="createRoles" value="false"/>
    <property name="roleCN" value="${notes:user.roles}"/>
    <property name="roleBaseDN" value="ou=APPLICATION,ou=ROLES,o=COMPANY"/>
</AuthState>