Package org.apache.shiro.realm.ldap

Class DefaultLdapRealm

  • All Implemented Interfaces:
    LogoutAware, Authorizer, PermissionResolverAware, RolePermissionResolverAware, org.apache.shiro.cache.CacheManagerAware, Realm, org.apache.shiro.util.Initializable, org.apache.shiro.util.Nameable
    Direct Known Subclasses:
    JndiLdapRealm
    public class DefaultLdapRealm
extends AuthorizingRealm
    An LDAP Realm implementation utilizing Sun's/Oracle's JNDI API as an LDAP API. This is Shiro's default implementation for supporting LDAP, as using the JNDI API has been a common approach for Java LDAP support for many years.

    This realm implementation and its backing JndiLdapContextFactory should cover 99% of all Shiro-related LDAP authentication and authorization needs. However, if it does not suit your needs, you might want to look into creating your own realm using an alternative, perhaps more robust, LDAP communication API, such as the Apache LDAP API.

    Authentication

    During an authentication attempt, if the submitted AuthenticationToken's principal is a simple username, but the LDAP directory expects a complete User Distinguished Name (User DN) to establish a connection, the userDnTemplate property must be configured. If not configured, the property will pass the simple username directly as the User DN, which is often incorrect in most LDAP environments (maybe Microsoft ActiveDirectory being the exception).

    Authorization

    By default, authorization is effectively disabled due to the default doGetAuthorizationInfo(org.apache.shiro.subject.PrincipalCollection) implementation returning null. If you wish to perform authorization based on an LDAP schema, you must subclass this one and override that method to reflect your organization's data model.

    Configuration

    This class primarily provides the userDnTemplate property to allow you to specify the your LDAP server's User DN format. Most other configuration is performed via the nested contextFactory property.

    For example, defining this realm in Shiro .ini: 
     [main]
 ldapRealm = org.apache.shiro.realm.ldap.DefaultLdapRealm
 ldapRealm.userDnTemplate = uid={0},ou=users,dc=mycompany,dc=com
 ldapRealm.contextFactory.url = ldap://ldapHost:389
 ldapRealm.contextFactory.authenticationMechanism = DIGEST-MD5
 ldapRealm.contextFactory.environment[some.obscure.jndi.key] = some value
 ...
    The default contextFactory instance is a JndiLdapContextFactory. See that class's JavaDoc for more information on configuring the LDAP connection as well as specifying JNDI environment properties as necessary.
    Since:
    1.3
    See Also:
    JndiLdapContextFactory

    • Method Detail

      • getUserDnPrefix

        protected String getUserDnPrefix()
        Returns the User DN prefix to use when building a runtime User DN value or null if no userDnTemplate has been configured. If configured, this value is the text that occurs before the USERDN_SUBSTITUTION_TOKEN in the userDnTemplate value.
        Returns:
        the the User DN prefix to use when building a runtime User DN value or null if no userDnTemplate has been configured.

      • getUserDnSuffix

        protected String getUserDnSuffix()
        Returns the User DN suffix to use when building a runtime User DN value. or null if no userDnTemplate has been configured. If configured, this value is the text that occurs after the USERDN_SUBSTITUTION_TOKEN in the userDnTemplate value.
        Returns:
        the User DN suffix to use when building a runtime User DN value or null if no userDnTemplate has been configured.

      • setUserDnTemplate

        public void setUserDnTemplate(String template)
                       throws IllegalArgumentException
        Sets the User Distinguished Name (DN) template to use when creating User DNs at runtime. A User DN is an LDAP fully-qualified unique user identifier which is required to establish a connection with the LDAP directory to authenticate users and query for authorization information.

        Usage

        User DN formats are unique to the LDAP directory's schema, and each environment differs - you will need to specify the format corresponding to your directory. You do this by specifying the full User DN as normal, but but you use a {0} placeholder token in the string representing the location where the user's submitted principal (usually a username or uid) will be substituted at runtime.

        For example, if your directory uses an LDAP uid attribute to represent usernames, the User DN for the jsmith user may look like this: 

        uid=jsmith,ou=users,dc=mycompany,dc=com

        in which case you would set this property with the following template value: 

        uid={0},ou=users,dc=mycompany,dc=com

        If no template is configured, the raw AuthenticationToken principal will be used as the LDAP principal. This is likely incorrect as most LDAP directories expect a fully-qualified User DN as opposed to the raw uid or username. So, ensure you set this property to match your environment!
        Parameters:
        template - the User Distinguished Name template to use for runtime substitution
        Throws:
        IllegalArgumentException - if the template is null, empty, or does not contain the {0} substitution token.
        See Also:
        LdapContextFactory.getLdapContext(Object,Object)

      • getUserDnTemplate

        public String getUserDnTemplate()
        Returns the User Distinguished Name (DN) template to use when creating User DNs at runtime - see the setUserDnTemplate JavaDoc for a full explanation.
        Returns:
        the User Distinguished Name (DN) template to use when creating User DNs at runtime.

      • setContextFactory

        public void setContextFactory(LdapContextFactory contextFactory)
        Sets the LdapContextFactory instance used to acquire connections to the LDAP directory during authentication attempts and authorization queries. Unless specified otherwise, the default is a JndiLdapContextFactory instance.
        Parameters:
        contextFactory - the LdapContextFactory instance used to acquire connections to the LDAP directory during authentication attempts and authorization queries

      • getContextFactory

        public LdapContextFactory getContextFactory()
        Returns the LdapContextFactory instance used to acquire connections to the LDAP directory during authentication attempts and authorization queries. Unless specified otherwise, the default is a JndiLdapContextFactory instance.
        Returns:
        the LdapContextFactory instance used to acquire connections to the LDAP directory during authentication attempts and authorization queries

      • getLdapPrincipal

        protected Object getLdapPrincipal(AuthenticationToken token)
        Returns the principal to use when creating the LDAP connection for an authentication attempt.

        This implementation uses a heuristic: it checks to see if the specified token's principal is a String, and if so, converts it from what is assumed to be a raw uid or username String into a User DN String. Almost all LDAP directories expect the authentication connection to present a User DN and not an unqualified username or uid.

        If the token's principal is not a String, it is assumed to already be in the format supported by the underlying LdapContextFactory implementation and the raw principal is returned directly.
        Parameters:
        token - the AuthenticationToken submitted during the authentication process
        Returns:
        the User DN or raw principal to use to acquire the LdapContext.
        See Also:
        LdapContextFactory.getLdapContext(Object, Object)

      • queryForAuthenticationInfo

        protected AuthenticationInfo queryForAuthenticationInfo(AuthenticationToken token,
                                                        LdapContextFactory ldapContextFactory)
                                                 throws NamingException
        This implementation opens an LDAP connection using the token's discovered principal and provided credentials. If the connection opens successfully, the authentication attempt is immediately considered successful and a new AuthenticationInfo instance is created and returned. If the connection cannot be opened, either because LDAP authentication failed or some other JNDI problem, an NamingException will be thrown.
        Parameters:
        token - the submitted authentication token that triggered the authentication attempt.
        ldapContextFactory - factory used to retrieve LDAP connections.
        Returns:
        an AuthenticationInfo instance representing the authenticated user's information.
        Throws:
        NamingException - if any LDAP errors occur.

      • createAuthenticationInfo

        protected AuthenticationInfo createAuthenticationInfo(AuthenticationToken token,
                                                      Object ldapPrincipal,
                                                      Object ldapCredentials,
                                                      LdapContext ldapContext)
                                               throws NamingException
        Returns the AuthenticationInfo resulting from a Subject's successful LDAP authentication attempt.

        This implementation ignores the ldapPrincipal, ldapCredentials, and the opened ldapContext arguments and merely returns an AuthenticationInfo instance mirroring the submitted token's principal and credentials. This is acceptable because this method is only ever invoked after a successful authentication attempt, which means the provided principal and credentials were correct, and can be used directly to populate the (now verified) AuthenticationInfo.

        Subclasses however are free to override this method for more advanced construction logic.
        Parameters:
        token - the submitted AuthenticationToken that resulted in a successful authentication
        ldapPrincipal - the LDAP principal used when creating the LDAP connection. Unlike the token's principal, this value is usually a constructed User DN and not a simple username or uid. The exact value is depending on the configured LDAP authentication mechanism in use.
        ldapCredentials - the LDAP credentials used when creating the LDAP connection.
        ldapContext - the LdapContext created that resulted in a successful authentication. It can be used further by subclasses for more complex operations. It does not need to be closed - it will be closed automatically after this method returns.
        Returns:
        the AuthenticationInfo resulting from a Subject's successful LDAP authentication attempt.
        Throws:
        NamingException - if there was any problem using the LdapContext

      • queryForAuthorizationInfo

        protected AuthorizationInfo queryForAuthorizationInfo(PrincipalCollection principals,
                                                      LdapContextFactory ldapContextFactory)
                                               throws NamingException
        Method that should be implemented by subclasses to build an AuthorizationInfo object by querying the LDAP context for the specified principal.
        Parameters:
        principals - the principals of the Subject whose AuthenticationInfo should be queried from the LDAP server.
        ldapContextFactory - factory used to retrieve LDAP connections.
        Returns:
        an AuthorizationInfo instance containing information retrieved from the LDAP server.
        Throws:
        NamingException - if any LDAP errors occur during the search.