["Main"]

• + ["What Is Subversion For"]
• + ["Setting Up A Subversion Repository"]
• + ["SVNKit Architecture"]
• + ["Getting Started With SVNKit"]
• - Authentication
• + ["Managing Repository With SVNKit"]
  • + ["Printing Out A Subversion Repository Tree"]
  • + ["Printing Out File Contents"]
  • + ["Printing Out Repository History"]

  • + [:Committing To A Repository:Editing operation: committing to a repository]

  • + [:Updating From A Repository:Editing Operation: receiving changes from a repository]

  • + ["Replicating An Existing Repository"]
  • + ["Managing A Working Copy"]

TableOfContents

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 blocks 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"].

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 successfully, 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.

But imagine, that the user has mistyped his password.

1. In this case the server rejects the credentials and challenges for authentication again.
2. ["SVNKit"] receives an error message and says to the auth manager that the provided credentials are not acknowledged by the server.
3. Then ["SVNKit"] asks the manager for the next credentials and the process described above repeats once again.

attachment:AuthProvider_In_Work_1.png

["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 [http://svnkit.com/kb/javadoc/org/tmatesoft/svn/core/SVNAuthenticationException.html SVNAuthenticationException].

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 [http://svnkit.com/kb/javadoc/org/tmatesoft/svn/core/auth/SVNAuthentication.html 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 [http://svnkit.com/kb/javadoc/org/tmatesoft/svn/core/auth/SVNAuthentication.html SVNAuthentication"] instances which are returned back from an auth manager must correspond to the kind passed to the auth manager. That means that, for example, if credentials of type PASSWORD are requested, an auth manager must return an [http://svnkit.com/kb/javadoc/org/tmatesoft/svn/core/auth/SVNPasswordAuthentication.html 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 [http://svnkit.com/kb/javadoc/org/tmatesoft/svn/core/auth/ISVNAuthenticationStorage.html ISVNAuthenticationStorage] 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 [http://svnkit.com/kb/javadoc/org/tmatesoft/svn/core/auth/ISVNProxyManager.html proxy manager], ["SVNKit"] interacts with a target server through a proxy server represented by the proxy manager.

SSL Manager

This block is represented by the [http://svnkit.com/kb/javadoc/org/tmatesoft/svn/core/auth/ISVNSSLManager.html ISVNSSLManager] 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 [http://svnkit.com/kb/javadoc/org/tmatesoft/svn/core/auth/SVNAuthenticationManager.html ISVNAuthenticationManager]:

• [http://svnkit.com/kb/javadoc/org/tmatesoft/svn/core/auth/BasicAuthenticationManager.html BasicAuthenticationManager]

• DefaultSVNAuthenticationManager

DefaultSVNAuthenticationManager

This implementation has the following features:

• Can use an on-disk auth storage located in the [http://svnbook.red-bean.com/nightly/en/svn.advanced.html#svn.advanced.confarea default Subversion run-time configuration are] 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 [http://svnkit.com/kb/javadoc/org/tmatesoft/svn/core/wc/SVNWCUtil.html SVNWCUtil].

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:

   1        
   2        ...
   3             
   4        ISVNAuthenticationManager authManager = new BasicAuthenticationManager( "login" , "password" );
   5        
   6        ...

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

   1        ...
   2             
   3        ISVNAuthenticationManager authManager = new BasicAuthenticationManager( "DOMAIN\\login" , "password" );
   4        
   5        ...