LdapIdentityStoreDefinition (Java(TM) EE 8 Specification APIs)

```
@Retention(value=RUNTIME)
 @Target(value=TYPE)
public @interface LdapIdentityStoreDefinition
```
Annotation used to define a container-provided IdentityStore that stores caller credentials and identity attributes (together caller identities) in an LDAP store, and make that implementation available as an enabled CDI bean.
The container-provided IdentityStore must support validating UsernamePasswordCredential, and may support validating other credential types.

Optional Element Summary

Optional Elements
Modifier and Type	Optional Element and Description
`String`	`bindDn` Distinguished name for the application or administrative user that will be used to make the initial connection to the LDAP and to perform searches and lookups.
`String`	`bindDnPassword` Password for the application/admin user defined by the bindDn member.
`String`	`callerBaseDn` Base distinguished name for callers in the LDAP store (e.g., "`ou=caller,dc=jsr375,dc=net`").
`String`	`callerNameAttribute` Name of the attribute that contains the callers name in the person object (e.g., "`uid`").
`String`	`callerSearchBase` Search base for looking up callers (e.g., "`ou=caller,dc=jsr375,dc=net`").
`String`	`callerSearchFilter` Search filter to find callers when callerSearchBase is set.
`LdapIdentityStoreDefinition.LdapSearchScope`	`callerSearchScope` Search scope for caller searches: determines depth of the search in the LDAP tree.
`String`	`callerSearchScopeExpression` Allow callerSearchScope to be specified as an EL expression.
`String`	`groupMemberAttribute` Name of the attribute in a group object that identifies the members of the group (e.g., "`member`").
`String`	`groupMemberOfAttribute` Name of the attribute in a person object that identifies the groups the caller belongs to (e.g., "`memberOf`").
`String`	`groupNameAttribute` Name of the attribute of a group object that represents the group name (e.g., "`cn`")
`String`	`groupSearchBase` Search base for looking up groups (e.g., "`ou=group,dc=jsr375,dc=net`").
`String`	`groupSearchFilter` Search filter to find groups when groupSearchBase is set.
`LdapIdentityStoreDefinition.LdapSearchScope`	`groupSearchScope` Search scope for group searches, determines depth of the search in the LDAP tree.
`String`	`groupSearchScopeExpression` Allow groupSearchScope to be specified as an EL expression.
`int`	`maxResults` Set the maximum number of results (objects) the server should return in response to a search.
`String`	`maxResultsExpression` Allow maxResults to be specified as an EL expression.
`int`	`priority` Determines the order in case multiple IdentityStores are found.
`String`	`priorityExpression` Allow priority to be specified as an EL expression.
`int`	`readTimeout` Set the timeout value that should be used when waiting for the LDAP server to return results.
`String`	`readTimeoutExpression` Allow readTimeout to be specified as an EL expression.
`String`	`url` URL where the LDAP server can be reached.
`IdentityStore.ValidationType[]`	`useFor` Determines what the identity store is used for
`String`	`useForExpression` Allow useFor to be specified as an EL expression.

- Element Detail
  - url
```
public abstract String url
```
    URL where the LDAP server can be reached.
    E.g.: ldap://localhost:33389
    
    Returns:
    
    URL where the LDAP server can be reached
    
    Default:
    
    ""
- - bindDn
```
public abstract String bindDn
```
    Distinguished name for the application or administrative user that will be used to make the initial connection to the LDAP and to perform searches and lookups.
    This value is needed if caller or group lookup will be done. It is not needed if the store will be used only to authenticate callers using direct binding (see callerBaseDn).
    This user needs search permission in the LDAP for persons and/or groups.
    E.g.: uid=ldap,ou=apps,dc=jsr375,dc=net
    
    Returns:
    
    The distinguished name for the application user.
    
    Default:
    
    ""
- - bindDnPassword
```
public abstract String bindDnPassword
```
    Password for the application/admin user defined by the bindDn member. Only used when the member bindDn is filled in.
    
    Returns:
    
    password for the application user.
    
    Default:
    
    ""
- - callerBaseDn
```
public abstract String callerBaseDn
```
    Base distinguished name for callers in the LDAP store (e.g., "ou=caller,dc=jsr375,dc=net").
    When this member value is specified, and callerSearchBase is not, direct binding is attempted.
    The callerNameAttribute must be specified along with this attribute so that the runtime can create the "leaf" RDN needed to concatenate with the base DN to create the full DN of the caller.
    
    Returns:
    
    The base distinguished name for callers.
    
    Default:
    
    ""
- - callerNameAttribute
```
public abstract String callerNameAttribute
```
    Name of the attribute that contains the callers name in the person object (e.g., "uid").
    This attribute will be used, with callerBaseDn, to construct caller DNs for direct binding. It is also used to retrieve the caller's name when the caller object is instead looked up using search.
    The value of this attribute is returned as the caller principal name for a successful credential validation.
    The following gives an example in ldif format:
```
 
 dn: uid=peter,ou=caller,dc=jsr375,dc=net
 objectclass: top
 objectclass: uidObject
 objectclass: person
 uid: peter
 cn: Peter Smith
 sn: Peter
 userPassword: secret1
 
 
```
    Returns:
    
    Name of the attribute that represents the caller name
    
    Default:
    
    "uid"
- - callerSearchBase
```
public abstract String callerSearchBase
```
    Search base for looking up callers (e.g., "ou=caller,dc=jsr375,dc=net").
    Overrides callerBaseDn, if configured, causing caller search to be used instead of direct binding. Requires that the bindDn member be filled in.
    
    Returns:
    
    Base DN for searching the LDAP tree for callers.
    
    Default:
    
    ""
- - callerSearchFilter
```
public abstract String callerSearchFilter
```
    Search filter to find callers when callerSearchBase is set. The search is performed starting from the callerSearchBase DN with the scope specified by callerSearchScope.
    
    Returns:
    
    Search expression to find callers.
    
    Default:
    
    ""
- - callerSearchScope
```
public abstract LdapIdentityStoreDefinition.LdapSearchScope callerSearchScope
```
    Search scope for caller searches: determines depth of the search in the LDAP tree.
    
    Returns:
    
    The search scope
    
    Default:
    
    javax.security.enterprise.identitystore.LdapIdentityStoreDefinition.LdapSearchScope.SUBTREE
- - callerSearchScopeExpression
```
public abstract String callerSearchScopeExpression
```
    Allow callerSearchScope to be specified as an EL expression. If set, overrides any value set with callerSearchScope.
    
    Returns:
    
    the callerSearchScope EL expression
    
    Default:
    
    ""
- - groupSearchBase
```
public abstract String groupSearchBase
```
    Search base for looking up groups (e.g., "ou=group,dc=jsr375,dc=net").
    Needed only for a store that performs group lookup. Requires that the bindDn member be filled in.
    
    Returns:
    
    Base DN for searching the LDAP tree for groups.
    
    Default:
    
    ""
- - groupSearchFilter
```
public abstract String groupSearchFilter
```
    Search filter to find groups when groupSearchBase is set. The search is performed starting from the groupSearchBase DN with the scope specified by groupSearchScope.
    
    Returns:
    
    Search expression to find groups.
    
    Default:
    
    ""
- - groupSearchScope
```
public abstract LdapIdentityStoreDefinition.LdapSearchScope groupSearchScope
```
    Search scope for group searches, determines depth of the search in the LDAP tree.
    
    Returns:
    
    The search scope
    
    Default:
    
    javax.security.enterprise.identitystore.LdapIdentityStoreDefinition.LdapSearchScope.SUBTREE
- - groupSearchScopeExpression
```
public abstract String groupSearchScopeExpression
```
    Allow groupSearchScope to be specified as an EL expression. If set, overrides any value set with groupSearchScope.
    
    Returns:
    
    the groupSearchScope EL expression
    
    Default:
    
    ""
- - groupNameAttribute
```
public abstract String groupNameAttribute
```
    Name of the attribute of a group object that represents the group name (e.g., "cn")
    
    Returns:
    
    Name of the attribute that represents the group name
    
    Default:
    
    "cn"
- - groupMemberAttribute
```
public abstract String groupMemberAttribute
```
    Name of the attribute in a group object that identifies the members of the group (e.g., "member").
    The value of this attribute must be the full DN of the caller. The following gives an example entry in ldif format:
```
 
 dn: cn=foo,ou=group,dc=jsr375,dc=net
 objectclass: top
 objectclass: groupOfNames
 cn: foo
 member: uid=pete,ou=caller,dc=jsr375,dc=net
 member: uid=john,ou=caller,dc=jsr375,dc=net
 
 
```
    Returns:
    
    Attribute for the group members
    
    Default:
    
    "member"
- - groupMemberOfAttribute
```
public abstract String groupMemberOfAttribute
```
    Name of the attribute in a person object that identifies the groups the caller belongs to (e.g., "memberOf").
    This attribute is used only if: a) group search is not configured (i.e., no groupSearchBase and groupSearchFilter configured); and, b) the caller's DN is available, either because groups are being returned during the credential validation phase by an identity store that performs both validation and group lookup, or because the DN is available in the CredentialValidationResult passed to the IdentityStore.getCallerGroups(CredentialValidationResult) method.
    The value of this attribute must be the full DN of the group. The following gives an example entry in ldif format:
```
 
 dn: uid=peter,ou=caller,dc=jsr375,dc=net
 objectclass: top
 objectclass: uidObject
 objectclass: person
 uid: peter
 cn: Peter Smith
 memberOf: cn=foo,ou=group,dc=jsr375,dc=net
 memberOf: cn=bar,ou=group,dc=jsr375,dc=net
 
 
```
    Returns:
    
    Attribute for group membership
    
    Default:
    
    "memberOf"
- - readTimeout
```
public abstract int readTimeout
```
    Set the timeout value that should be used when waiting for the LDAP server to return results. Note that this is different from the connection timeout for the underlying socket connection;
    The default value of 0 means wait forever (assuming the connection itself does not time out).
    
    Returns:
    
    The readTimeout value.
    
    Default:
    
    0
- - readTimeoutExpression
```
public abstract String readTimeoutExpression
```
    Allow readTimeout to be specified as an EL expression. If set, overrides any value set with readTimeout.
    
    Returns:
    
    The readTimeout EL expression
    
    Default:
    
    ""
- - maxResults
```
public abstract int maxResults
```
    Set the maximum number of results (objects) the server should return in response to a search.
    The default value is set to 1000, which corresponds to the maximum number of results most LDAP servers will return for in a single response. Most LDAP servers support paging through result sets larger than 1000, but doing so should rarely be necessary for normal validation and group lookup use cases. Implementations of the built-in LDAP IdentityStore MAY support paging through larger result sets, but are NOT REQUIRED to.
    
    Returns:
    
    The maximum number of results the LDAP server should return.
    
    Default:
    
    1000
- - maxResultsExpression
```
public abstract String maxResultsExpression
```
    Allow maxResults to be specified as an EL expression. If set, overrides any value set with maxResults.
    
    Returns:
    
    The maxResults EL expression
    
    Default:
    
    ""
- - priority
```
public abstract int priority
```
    Determines the order in case multiple IdentityStores are found.
    
    Returns:
    
    The priority.
    
    Default:
    
    80
- - priorityExpression
```
public abstract String priorityExpression
```
    Allow priority to be specified as an EL expression. If set, overrides any value set with priority.
    
    Returns:
    
    The priority EL expression
    
    Default:
    
    ""
- - useFor
```
public abstract IdentityStore.ValidationType[] useFor
```
    Determines what the identity store is used for
    
    Returns:
    
    The type the identity store is used for
    
    Default:
    
    {javax.security.enterprise.identitystore.IdentityStore.ValidationType.VALIDATE, javax.security.enterprise.identitystore.IdentityStore.ValidationType.PROVIDE_GROUPS}
- - useForExpression
```
public abstract String useForExpression
```
    Allow useFor to be specified as an EL expression. If set, overrides any value set with useFor.
    
    Returns:
    
    The useFor EL expression
    
    Default:
    
    ""

Annotation Type LdapIdentityStoreDefinition

Optional Element Summary

Element Detail

url

bindDn

bindDnPassword

callerBaseDn

callerNameAttribute

callerSearchBase

callerSearchFilter

callerSearchScope

callerSearchScopeExpression

groupSearchBase

groupSearchFilter

groupSearchScope

groupSearchScopeExpression

groupNameAttribute

groupMemberAttribute

groupMemberOfAttribute

readTimeout

readTimeoutExpression

maxResults

maxResultsExpression

priority

priorityExpression

useFor

useForExpression