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 JndiLdapRealm}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 }