Authentication manager

When an anonymous access to a repository is not permitted, a server asks for authentication credentials. For these purposes SVNKit uses authentication managers. Such managers implement the [http://svnkit.com/kb/javadoc/org/tmatesoft/svn/core/auth/ISVNAuthenticationManager.html ISVNAuthenticationManager] interface. The [:Getting Started With SVNKit:previous article] describes how to create an [http://svnkit.com/kb/javadoc/org/tmatesoft/svn/core/io/SVNRepository.html SVNRepository] driver for working with a repository. After such a driver has been instantiated you provide an authentication manager in the following way:

   1        try {
   2             ...
   3             
   4             ISVNAuthenticationManager authManager;
   5             
   6             ...
   7 
   8             SVNURL url = SVNURL.parseURIDecoded( "svn://host/path_to_repository_root/inner_path" );
   9             SVNRepository repository = SVNRepositoryFactory.create( url , null );
  10 
  11             //set an auth manager which will provide user credentials
  12             repository.setAuthenticationManager(basicAuthManager);
  13    
  14             ...
  15             
  16        } catch (SVNException e) {
  17             //handle exception                  
  18        }

If you don't provide an authentication manager and a server does not reject anonymous requests (for example, a server can be world-readable, and you are performing a checkout) everything should go well. But if it's not so and the server challenges you for credentials, you will certainly get an exception since there's no authentication manager provided.

Authentication manager usage

The whole authentication manager is based on the following four logical blocks:

attachment:AuthManager_Architecture.png

On the diagram each logical block is followed by a corresponding interface (in a bold font) provided within the [http://svnkit.com/kb/javadoc/org/tmatesoft/svn/core/auth/package-summary.html auth package]. These blokcs are like pinions of a gear, in our case - of an authentication gear that is used within SVNKit. Such a structure allows you to replace different blocks while the authentication manager itself remaining the same. Let's look at those blocks closer.

Authentication Provider

This block is represented by the [http://svnkit.com/kb/javadoc/org/tmatesoft/svn/core/auth/ISVNAuthenticationProvider.html ISVNAuthenticationProvider] interface in SVNKit authentication API. It's responsible for providing [http://svnkit.com/kb/javadoc/org/tmatesoft/svn/core/auth/SVNAuthentication.html user authentication credentials] of different kinds. Such providers are passed to an authentication manager. Let's look at how SVNKit acts when it receives a server challenge for authentication.

attachment:AuthProvider_In_Work.png

The above sequence diagram illustrates a commit process performed by SVNKit.

A user initiates a commit request. SVNKit sends the request to the server.
The server receives the request and answers with a challenge for authentication.
SVNKit receives the server's challenge and asks the auth manager provided by the client for the first credentials. Here we assume that this is the first time credentials are requested, and since there can be probably more than one credentials for the same authentication realm, SVNKit starts with the first credentials.
The auth manager invokes its auth provider asking for the first credentials.
The auth provider returns user credentials to the manager. In our example it prompts a user for login\password. However there can be other implementations: for example, a provider which fetches credentials from the standard Subversion auth storage. Actually, it's up to a user.
The auth manager returns the credentials to the caller. Surely, this diagram is a bit relative: the auth manager
(as well as auth provider) is also a part of SVNKit, but is shown separately only for more clear demonstration.
SVNKit sends the request with credentials to the server.
The server receives the credentials, checks them for validity. If the user is authorized seccessfully, the server carries out the request and sends back a response.
So, if negotiation is successful SVNKit says to the auth manager that the provided credentials have been acknowledged by the server. Then returns the control back to the caller.

But imagine, that the user has mistyped his password. # In this case the server rejects the credentials and challenges for authentication again. # SVNKit receives an error message and says to the auth manager that the provided credentials are not acknowledged by the server. # Then SVNKit asks the manager for the next credentials and the process described above repeats once again.

[{Image src = 'AuthProvider_In_Work_1.png' caption = 'Authentication Provider In Work'}]

SVNKit keeps on asking the auth manager for the next credentials until either the server acknowledges some of them or the auth provider (hence the auth manager, too) runs out of credentials (returns null). In the latter case SVNKit throws an [SVNAuthenticationException | http://svnkit.com/kb/javadoc/org/tmatesoft/svn/core/SVNAuthenticationException.html].

There may be more than one auth provider registered in the auth manager (like in the default auth manager implementation which is discussed later). Or maybe some wouldn't use providers at all, combining an auth manager and auth provider into a single class. It depends on a concrete implementation.

!Kinds of authentication credentials The following is a table of different kinds of auth credentials and subclasses of SVNAuthentication which correspond to them:

These kinds are provided by SVNKit to the credentials-getter methods of an authentication manager. And an auth manager provides them to its auth provider. Those SVNAuthentication instances which are returned back from an auth manager %%(color:red)must%% correspond to the kind passed. That means that, for example, if credentials of type PASSWORD are requested, an auth manager must return an SVNPasswordAuthentication object, and so on.

According to an access scheme SVNKit passes an appropriate kind to an auth manager. For example, if svn+ssh:// scheme is used, SVNKit passes the SSH kind to an auth manager.

!Authentication Storage This block is represented by the [ISVNAuthenticationStorage | http://svnkit.com/kb/javadoc/org/tmatesoft/svn/core/auth/ISVNAuthenticationStorage.html] interface. SVNKit implements this interface as a run-time in-memory storage for credentials of different kinds. In our previous example the auth provider can store login\password provided by the user in such a storage, so that later credentials (acknowledged by the server and stored in the run-time storage) may be reused without prompting the user again.

!Proxy Manager If an authentication manager provides a non-null [proxy manager | http://svnkit.com/kb/javadoc/org/tmatesoft/svn/core/auth/ISVNProxyManager.html], SVNKit interacts with a target server through a proxy server represented by the proxy manager.

!SSL Manager This block is represented by the [ISVNSSLManager | http://svnkit.com/kb/javadoc/org/tmatesoft/svn/core/auth/ISVNSSLManager.html] interface. When a secured http connection is used (https:// ), and this manager is not null, it's used by SVNKit to create SSL encrypted sockets (i.e. such a manager provides an appropriate SSL context). However if no SSL manager is provided by an auth manager, SVNKit uses a default one which, of course, knows nothing of user certificate files. But this default one will provide an SSL context for creating SSL sockets as well as receive server certificate file.

!!!Default ISVNAuthenticationManager implementations SVNKit provides the following implementations of ISVNAuthenticationManager: * [BasicAuthenticationManager | http://svnkit.com/kb/javadoc/org/tmatesoft/svn/core/auth/BasicAuthenticationManager.html] * DefaultSVNAuthenticationManager

!DefaultSVNAuthenticationManager This implementation has the following features: * Can use an on-disk auth storage located in the [default Subversion run-time configuration are | http://svnbook.red-bean.com/nightly/en/svn.advanced.html#svn.advanced.confarea] or in a specified directory. It's able to cache credentials in that directory. * Uses a run-time in-memory storage for credentials (ISVNAuthenticationStorage implementation). * Can authenticate a user with provided name\password credentials. * Uses SSL, SSH, proxy settings from the config and servers files found in the default Subversion run-time configuration area.

On Windows machines name\password credentials are often stored encrypted. Unfortunately, SVNKit is not able to decrypt such credentials, therefore they are not used (just skipped).

The class which is responsible for instantiating DefaultSVNAuthenticationManager objects is [SVNWCUtil | http://svnkit.com/kb/javadoc/org/tmatesoft/svn/core/wc/SVNWCUtil.html].

BasicAuthenticationManager This is another very simple implementation of ISVNAuthenticationManager. Its has got the following features: * Does not use an on-disk auth storage. * Does not provide any SSL manager. * Does not use any settings from the config and servers files mentioned above. * Uses proxy, ssh settings and user credentials provided into the class constructors, i.e. does not use authentication providers at all. * Does not cache credentials at all.

You may provide an array of different SVNAuthentication credentials, your own specific proxy and ssh settings to such an auth manager and then use it in SVNKit.

!!!Forcing authentication Although one of the Subversion advantages is that you do not need to authenticate yourself until a server challenges you, sometimes it may be effective to have an ability to make SVNKit immediately authenticate a user without wasting time. The ISVNAuthenticationManager interface provides this ability: it returns a flag which SVNKit uses to control such a behaviour.

!!!HTTP authentication schemes SVNKit supports the following http auth schemes (for both server and proxy authentication): * Basic * Digest * NTLM

For Basic and Digest schemes you provide a login name and a password. Like this:

[{Java2HtmlPlugin

..
ISVNAuthenticationManager authManager = new BasicAuthenticationManager( "login" , "password" );
..

}]

In the NTLM auth scheme you also provide a domain name:

[{Java2HtmlPlugin

..
ISVNAuthenticationManager authManager = new BasicAuthenticationManager( "DOMAIN\\login" , "password" );
..

}]

-  ⇤ ← Revision 2 as of 2007-02-16 12:23:59 → 
  Size: 12224
  Editor: 85
  Comment:
+   ← Revision 3 as of 2007-02-16 13:32:35 → ⇥
  Size: 12288
  Editor: 85
  Comment:
-Deletions are marked like this.
+Additions are marked like this.
 Line 61:
-The above sequence diagram illustrates a commit process performed by __SVNKit__.
# A user initiates a commit request. __SVNKit__ sends the request to the server.
# The server receives the request and answers with a challenge for authentication.
# __SVNKit__ receives the server's challenge and asks the auth manager provided by the client for the first credentials. Here we assume that this is the first time credentials are requested, and since there can be probably more than one credentials for the same authentication realm, __SVNKit__ starts with the first credentials.
# The auth manager invokes its auth provider asking for the first credentials.
# The auth provider returns user credentials to the manager. In our example it prompts a user for login\password. However there can be other implementations: for example, a provider which fetches credentials from the standard Subversion auth storage. Actually, it's up to a user.
# The auth manager returns the credentials to the caller. Surely, this diagram is a bit relative: the auth manager (as well as auth provider) is also a part of __SVNKit__, but is shown separately only for more clear demonstration. 
# __SVNKit__ sends the request with credentials to the server.
# The server receives the credentials, checks them for validity. If the user is authorized seccessfully, the server carries out the request and sends back a response.
# So, if negotiation is successful __SVNKit__ says to the auth manager that the provided credentials have been acknowledged by the server. Then returns the control back to the caller.
+The above sequence diagram illustrates a commit process performed by '''SVNKit'''.
 1. A user initiates a commit request. '''SVNKit''' sends the request to the server.
 2. The server receives the request and answers with a challenge for authentication.
 3. '''SVNKit''' receives the server's challenge and asks the auth manager provided by the client for the first      credentials. Here we assume that this is the first time credentials are requested, and since there can be probably    more than one credentials for the same authentication realm, '''SVNKit''' starts with the first credentials.
 4. The auth manager invokes its auth provider asking for the first credentials.
 5. The auth provider returns user credentials to the manager. In our example it prompts a user for login\password.     However there can be other implementations: for example, a provider which fetches credentials from the standard    Subversion auth storage. Actually, it's up to a user.
 6. The auth manager returns the credentials to the caller. Surely, this diagram is a bit relative: the auth manager     (as well as auth provider) is also a part of '''SVNKit''', but is shown separately only for more clear demonstration. 
 7. '''SVNKit''' sends the request with credentials to the server.
 8. The server receives the credentials, checks them for validity. If the user is authorized seccessfully, the server     carries out the request and sends back a response.
 9. So, if negotiation is successful '''SVNKit''' says to the auth manager that the provided credentials have been   acknowledged by the server. Then returns the control back to the caller.