[[Getting Started With SVNKit|<<]] ... [[Managing Repository With SVNKit|>>]]
<br />
<br />

== 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:
<java>
       try {
            ...
            
            ISVNAuthenticationManager authManager;
            
            ...

            SVNURL url = SVNURL.parseURIDecoded("svn://host/path_to_repository_root/inner_path");
            SVNRepository repository = SVNRepositoryFactory.create(url, null);

            //set an auth manager which will provide user credentials
            repository.setAuthenticationManager(basicAuthManager);
            
            ...
            
       } catch (SVNException e) {
            //handle exception       		
       }
</java>
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:

<br />
[[Image:AuthManager_Architecture.png]]
<br />

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.

<br />
[[Image:AuthProvider_In_Work.png]]
<br />

<p>
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.

<p>
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.

<br />
[[Image:AuthProvider_In_Work_1.png]]
<br />

<p>
'''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].

<p>
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:

{|border=1
|bgcolor=#AACCFF|Kind||bgcolor=#AACCFF|Class representation||bgcolor=#AACCFF|Field of usage
|-
|[http://svnkit.com/kb/javadoc/org/tmatesoft/svn/core/auth/ISVNAuthenticationManager.html#PASSWORD PASSWORD]||[http://svnkit.com/kb/javadoc/org/tmatesoft/svn/core/auth/SVNPasswordAuthentication.html SVNPasswordAuthentication]||''login:password'' authentication (''svn://'', ''http:// '')
|-
|[http://svnkit.com/kb/javadoc/org/tmatesoft/svn/core/auth/ISVNAuthenticationManager.html#SSH SSH]||[http://svnkit.com/kb/javadoc/org/tmatesoft/svn/core/auth/SVNSSHAuthentication.html SVNSSHAuthentication]||In ''svn+ssh://'' tunneled connections
|-
|[http://svnkit.com/kb/javadoc/org/tmatesoft/svn/core/auth/ISVNAuthenticationManager.html#SSL SSL]||[http://svnkit.com/kb/javadoc/org/tmatesoft/svn/core/auth/SVNSSLAuthentication.html SVNSSLAuthentication]||In secure ''https:// '' connections
|-
|[http://svnkit.com/kb/javadoc/org/tmatesoft/svn/core/auth/ISVNAuthenticationManager.html#USERNAME USERNAME]||[http://svnkit.com/kb/javadoc/org/tmatesoft/svn/core/auth/SVNUserNameAuthentication.html SVNUserNameAuthentication]||With ''file:///'' protocol, on local machines
|}

<p>
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 <font color=red>must</font> 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.

<p>
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 '''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.

<p>
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).

<p>
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 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.

<p>
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 '''ISVNAuthenticationInterface''' 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

<p>
For Basic and Digest schemes you provide a login name and a password. Like this:
<java>
       ...
            
       ISVNAuthenticationManager authManager = new BasicAuthenticationManager("login", "password");
       
       ...
</java>

<p>
In the NTLM auth scheme you also provide a domain name:
<java>
       ...
            
       ISVNAuthenticationManager authManager = new BasicAuthenticationManager("DOMAIN\\login", "password");
       
       ...
</java>

<br />
<br />
[[Getting Started With SVNKit|<<]] ... [[Managing Repository With SVNKit|>>]]