001: /*
002:
003: Derby - Class org.apache.derby.authentication.UserAuthenticator
004:
005: Licensed to the Apache Software Foundation (ASF) under one or more
006: contributor license agreements. See the NOTICE file distributed with
007: this work for additional information regarding copyright ownership.
008: The ASF licenses this file to You under the Apache License, Version 2.0
009: (the "License"); you may not use this file except in compliance with
010: the License. You may obtain a copy of the License at
011:
012: http://www.apache.org/licenses/LICENSE-2.0
013:
014: Unless required by applicable law or agreed to in writing, software
015: distributed under the License is distributed on an "AS IS" BASIS,
016: WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
017: See the License for the specific language governing permissions and
018: limitations under the License.
019:
020: */
021:
022: package org.apache.derby.authentication;
023:
024: import java.util.Properties;
025: import java.sql.SQLException;
026:
027: /**
028: * The UserAuthenticator interface provides operations to authenticate
029: * a user's credentials in order to successfully connect to a database.
030: *
031: * Any user authentication schemes could be implemented using this interface
032: * and registered at start-up time.
033: * <p>
034: * If an application requires its own authentication scheme, then it can
035: * implement this interface and register as the authentication scheme
036: * that Derby should call upon connection requests to the system.
037: See the dcoumentation for the property <I>derby.authentication.provider</I>
038: * <p>
039: * A typical example would be to implement user authentication using
040: * LDAP, Sun NIS+, or even Windows User Domain, using this interface.
041: * <p>
042: * <i>Note</i>: Additional connection attributes can be specified on the
043: * database connection URL and/or Properties object on jdbc connection. Values
044: * for these attributes can be retrieved at runtime by the (specialized)
045: * authentication scheme to further help user authentication, if one needs
046: * additional info other than user, password, and database name.
047: *
048: *
049: */
050:
051: public interface UserAuthenticator {
052:
053: /**
054: * Authenticate a user's credentials.
055: * <BR>
056: * E.g. if connection url is
057: * <code>jdbc:derby:testdb;user=Fred;password=ScT7dmM2</code>
058: * then the userName will be Fred and within the Derby user authorization
059: * system, Fred becomes a case-insensitive authorization identifier and
060: * is known as FRED
061: *<BR>
062: * if connection url is
063: * <code>jdbc:derby:testdb;user="Fred";password=ScT7dmM2</code>
064: * then the userName will be "Fred" and within the Derby user authorization
065: * system, Fred becomes a case-sensitive authorization identifier and is
066: * known as Fred
067: * <BR>
068: *
069: * @param userName The user's name for the connection request. May be
070: * null. The user name is passed in as is from the
071: * connection request.
072: * Derby will pass in the user name that is set on
073: * connection request as is, without changing the
074: * casing and without removing the delimiter quotes
075: * if any.
076: *
077: * @param userPassword The user's password for the connection request.
078: * May be null.
079: *
080: * @param databaseName The database that the user wants to connect to.
081: * Will be null if this is system level authentication.
082: *
083: * @param info A Properties object that contains additional
084: * connection information, that can help to
085: * authenticate the user. It has properties of the
086: * 'info' object passed as part of
087: * DriverManager.getConnection() call and any
088: * attributes set on the JDBC URL.
089: *
090: * @return false if the connection request should be denied, true if the
091: * connection request should proceed. If false is returned the
092: * connection attempt will receive a SQLException with SQL State
093: * 08004.
094: *
095: * @exception java.sql.SQLException An exception processing the request,
096: * connection request will be denied. The SQL exception will
097: * be returned to the connection attempt.
098: */
099: public boolean authenticateUser(String userName,
100: String userPassword, String databaseName, Properties info)
101: throws SQLException;
102: }
|