Draft Authentication interface

Author: boggle

driver/src/main/java/org/neo4j/driver/v1/AuthenticationSchemes.java

@@ -0,0 +1,17 @@
+package org.neo4j.driver.v1;
+
+import org.neo4j.driver.v1.auth.BasicAuthenticationScheme;
+
+/**
+ * This class provides access to all authentication schemes supported by
+ * this driver implementation
+ */
+public final class AuthenticationSchemes
+{
+    private AuthenticationSchemes()
+    {
+        throw new UnsupportedOperationException();
+    }
+
+    public static final BasicAuthenticationScheme BASIC = null;
+}

driver/src/main/java/org/neo4j/driver/v1/Driver.java

@@ -23,6 +23,7 @@
 import org.neo4j.driver.internal.InternalSession;
 import org.neo4j.driver.internal.pool.InternalConnectionPool;
 import org.neo4j.driver.internal.spi.ConnectionPool;
+import org.neo4j.driver.v1.auth.AuthenticationScheme;
 
 /**
  * A Neo4j database driver, through which you can create {@link Session sessions} to run statements against the database.
@@ -83,6 +84,18 @@ public Driver( URI url, Config config )
         this.config = config;
     }
 
+    /**
+     * Create a new driver instance
+     *
+     * @param url of the remote database to connect to
+     * @param token to be used for authentication
+     * @param config settings of the driver
+     */
+    public Driver( URI url, AuthenticationScheme.Token token, Config config  )
+    {
+        throw new UnsupportedOperationException();
+    }
+
     /**
      * Establish a session
      * @return a session that could be used to run {@link Session#run(String) a statement} or
@@ -93,6 +106,20 @@ public Session session()
         return new InternalSession( connections.acquire( url ), config.logging().getLog( "session" ) );
     }
 
+    /**
+     * Change the password of the authenticated user on the database server.
+     *
+     * More precisely, change the credentials of the currently authenticated principal (the user) of this driver
+     * <b>on the database server</b>. If this is successful, use the provided new credentials for authentication
+     * of any sessions that may have to be created by the underlying session pool in the future.
+     *
+     * @param newCredential the new credentials of the authenticated user
+     */
+    public void updateCredentials( AuthenticationScheme.Credential newCredential )
+    {
+        throw new UnsupportedOperationException();
+    }
+
     /**
      * Close all the resources assigned to this driver
      * @throws Exception any error that might happen when releasing all resources

driver/src/main/java/org/neo4j/driver/v1/auth/AuthenticationScheme.java

@@ -0,0 +1,42 @@
+package org.neo4j.driver.v1.auth;
+
+/**
+ * An authentication scheme is a method of performing authentication against a Neo4j graph database
+ */
+public interface AuthenticationScheme
+{
+    /**
+     * @return the (human readable) name of the authentication scheme
+     */
+    String name();
+
+    /**
+     * A credential encapsulates a critical piece of information (like a password or a certificate)
+     * for verifying the identify of a subject (a user)
+     *
+     * @see AuthenticationScheme
+     */
+    interface Credential
+    {
+        /**
+         * @return the authentication scheme in which this credential may be used
+         */
+        AuthenticationScheme scheme();
+    }
+
+    /**
+     * A token is the combination of a credential and an associated principal. A principal is a piece
+     * of information (like a user name) that uniquely describes the subject (user) whose identity
+     * is verified by the credential.
+     *
+     * @see Credential
+     * @see AuthenticationScheme
+     */
+    interface Token extends Credential
+    {
+        /**
+         * @return the principal of the encapsulated credential
+         */
+        Object principal();
+    }
+}

driver/src/main/java/org/neo4j/driver/v1/auth/BasicAuthenticationScheme.java

@@ -0,0 +1,44 @@
+package org.neo4j.driver.v1.auth;
+
+/**
+ * Basic authentication uses the user name as the principal and transmits
+ * the password as its credential as clear text as part of establishing a session
+ *
+ * Basis authentication should not be used over unencrypted connections
+ *
+ * @see AuthenticationScheme
+ */
+public interface BasicAuthenticationScheme extends AuthenticationScheme
+{
+    /**
+     * Obtain a {@link Credential} for authentication using the basic authentication scheme
+     *
+     * @param password to be used
+     * @return a credential for authentication using the basic authentication scheme
+     */
+    Credential credential( String password );
+
+    /**
+     * Obtain a {@link Token} for authentication using the basic authentication scheme
+     *
+     * @param userName of the user to be authenticated
+     * @param password of the user to be authenticated
+     * @return token for authentication using the basic authentication scheme
+     */
+    Token token( String userName, String password );
+
+    interface Credential extends AuthenticationScheme.Credential
+    {
+        @Override
+        BasicAuthenticationScheme scheme();
+    }
+
+    interface Token extends AuthenticationScheme.Token, Credential
+    {
+        /**
+         * @return user name of the user to be authenticated using this token
+         */
+        @Override
+        String principal();
+    }
+}