View Javadoc

1   /*
2    * Licensed to the Apache Software Foundation (ASF) under one
3    * or more contributor license agreements.  See the NOTICE file
4    * distributed with this work for additional information
5    * regarding copyright ownership.  The ASF licenses this file
6    * to you under the Apache License, Version 2.0 (the
7    * "License"); you may not use this file except in compliance
8    * with the License.  You may obtain a copy of the License at
9    *
10   *     http://www.apache.org/licenses/LICENSE-2.0
11   *
12   * Unless required by applicable law or agreed to in writing,
13   * software distributed under the License is distributed on an
14   * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15   * KIND, either express or implied.  See the License for the
16   * specific language governing permissions and limitations
17   * under the License.
18   */
19  package org.apache.shiro.realm.ldap;
20  
21  import javax.naming.NamingException;
22  import javax.naming.ldap.LdapContext;
23  
24  /**
25   * Interface that encapsulates the creation of {@code LdapContext} objects that are used by {@link DefaultLdapRealm}s to
26   * perform authentication attempts and query for authorization data.
27   *
28   * @since 0.2
29   */
30  public interface LdapContextFactory {
31  
32      /**
33       * Creates (or retrieves from a pool) a {@code LdapContext} connection bound using the system account, or
34       * anonymously if no system account is configured.
35       *
36       * @return a {@code LdapContext} bound by the system account, or bound anonymously if no system account
37       *         is configured.
38       * @throws javax.naming.NamingException if there is an error creating the context.
39       */
40      LdapContext getSystemLdapContext() throws NamingException;
41  
42      /**
43       * Creates (or retrieves from a pool) a {@code LdapContext} connection bound using the username and password
44       * specified.
45       *
46       * @param username the username to use when creating the connection.
47       * @param password the password to use when creating the connection.
48       * @return a {@code LdapContext} bound using the given username and password.
49       * @throws javax.naming.NamingException if there is an error creating the context.
50       * @deprecated the {@link #getLdapContext(Object, Object)} method should be used in all cases to ensure more than
51       * String principals and credentials can be used.
52       */
53      @Deprecated
54      LdapContext getLdapContext(String username, String password) throws NamingException;
55  
56      /**
57       * Creates (or retrieves from a pool) an {@code LdapContext} connection bound using the specified principal and
58       * credentials.  The format of the principal and credentials are whatever is supported by the underlying
59       * LDAP {@link javax.naming.spi.InitialContextFactory InitialContextFactory} implementation.  The default Sun
60       * (now Oracle) implementation supports
61       * <a href="http://download-llnw.oracle.com/javase/tutorial/jndi/ldap/auth_mechs.html">anonymous, simple, and
62       * SASL-based mechanisms</a>.
63       * <p/>
64       * This method was added in Shiro 1.1 to address the fact that principals and credentials can be more than just
65       * {@code String} user DNs and passwords for connecting to LDAP.  For example, the credentials can be an
66       * {@code X.509} certificate.
67       *
68       * @param principal   the principal to use when acquiring a connection to the LDAP directory
69       * @param credentials the credentials (password, X.509 certificate, etc) to use when acquiring a connection to the
70       *                    LDAP directory
71       * @return the acquired {@code LdapContext} connection bound using the specified principal and credentials.
72       * @throws NamingException if unable to acquire a connection.
73       * @since 1.1
74       */
75      LdapContext getLdapContext(Object principal, Object credentials) throws NamingException;
76      
77  }