<commit_before>Kerb4J
========

Industry standard library for working with Kerberos/SPNEGO authentication in Java in 2018.

Main features:
 - Getting group membership information from Kerberos token - no need to query LDAP
 - Proper caching of tickets - make just one request to domain controller and cache the ticket
 - Flexible SPN resolution - you own the code and do not have to rely on magic SPN calculation algorithms
 
Installation
========

Kerb4J is available from Maven Central repo:

**Client**
```xml
<dependency>
    <groupId>com.kerb4j</groupId>
    <artifactId>kerb4j-client</artifactId>
    <version>0.0.5</version>
</dependency>
```

**Spring Security**
```xml
<dependency>
    <groupId>com.kerb4j</groupId>
    <artifactId>kerb4j-server-spring-security</artifactId>
    <version>0.0.5</version>
</dependency>
```

**Tomcat**
```xml
<dependency>
    <groupId>com.kerb4j</groupId>
    <artifactId>kerb4j-server-tomcat</artifactId>
    <version>0.0.5</version>
</dependency>
```

SPNEGO/Kerberos Client
========

Kerb4J provides efficient way to create Kerberos/SPNEGO HTTP Clients. Main two classes you'll need are `SpnegoClient` and `SpnegoContext`
- `SpnegoClient` provides API for authenticating client in KDC (e.g. in Active Directory Domain Controller).
- `SpnegoContext` is responsible for accessing downstream systems, creating and validating appropriate security HTTP headers.

`SpnegoClient` supports authentication using name and password, keytab file or ticket cache.

Example usage:
```java
SpnegoClient spnegoClient = SpnegoClient.loginWithKeyTab("svc_consumer", "/opt/myapp/consumer.keytab");
```

`SpnegoContext` allows creating 'Authorization: Negotiate XXXXX' header and optionally validating `WWW-Authenticate` response header for SPNEGO mutual authentication

Example usage:
```java
URL url = new URL("http://api.provider.acme.com/api/operation1");
SpnegoContext context = spnegoClient.createContext("http://provider.acme.com"); // Will result in HTTP/provider.acme.com SPN
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
conn.setRequestProperty("Authorization", context.createTokenAsAuthroizationHeader());
```<commit_msg>Added documentation for Kerb4J SPNEGO HTTP server<commit_after>Kerb4J
========

Industry standard library for working with Kerberos/SPNEGO authentication in Java in 2018.

Main features:
 - Getting group membership information from Kerberos token - no need to query LDAP
 - Proper caching of tickets - make just one request to domain controller and cache the ticket
 - Flexible SPN resolution - you own the code and do not have to rely on magic SPN calculation algorithms
 
Installation
========

Kerb4J is available from Maven Central repo:

**Client**
```xml
<dependency>
    <groupId>com.kerb4j</groupId>
    <artifactId>kerb4j-client</artifactId>
    <version>0.0.5</version>
</dependency>
```

**Spring Security**
```xml
<dependency>
    <groupId>com.kerb4j</groupId>
    <artifactId>kerb4j-server-spring-security</artifactId>
    <version>0.0.5</version>
</dependency>
```

**Tomcat**
```xml
<dependency>
    <groupId>com.kerb4j</groupId>
    <artifactId>kerb4j-server-tomcat</artifactId>
    <version>0.0.5</version>
</dependency>
```

SPNEGO/Kerberos Client
========

Kerb4J provides efficient way to create Kerberos/SPNEGO HTTP Clients. Main two classes you'll need are `SpnegoClient` and `SpnegoContext`
- `SpnegoClient` provides API for authenticating client in KDC (e.g. in Active Directory Domain Controller).
- `SpnegoContext` is responsible for accessing downstream systems, creating and validating appropriate security HTTP headers.

`SpnegoClient` supports authentication using name and password, keytab file or ticket cache.

Example usage:
```java
SpnegoClient spnegoClient = SpnegoClient.loginWithKeyTab("svc_consumer", "/opt/myapp/consumer.keytab");
```

`SpnegoContext` allows creating 'Authorization: Negotiate XXXXX' header and optionally validating `WWW-Authenticate` response header for SPNEGO mutual authentication

Example usage:
```java
URL url = new URL("http://api.provider.acme.com/api/operation1");
SpnegoContext context = spnegoClient.createContext("http://provider.acme.com"); // Will result in HTTP/provider.acme.com SPN
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
conn.setRequestProperty("Authorization", context.createTokenAsAuthroizationHeader());
```

**SPN resolution**

Kerb4J allows you to specify SPN for the downstream system manually without doing any reverse DNS lookups, canonicalizations, e.t.c.
You can even use SPN `HTTP/foo` for calling service `bar`

**Caching tickets**

Consider you want to make a million of HTTP requests to Kerberos-protected server.
Kerb4J will allow you to make just two requests to the KDC (e.g. in Active Directory Domain Controller).

One `SpnegoClient` is created, Kerb4J will make first request for TGT (authentication).
TGT will be cached and renewed only when tickets expired. 
Reuse the `SpnegoClient` instance for all requests you want to make using the same credentials.

When you create a `SpnegoContext` instance, Kerb4J will make another request for a service ticket.
Again keep the `SpnegoContext` instance to reuse the same service ticket (while it is not expired).   


SPNEGO/Kerberos Server
========

Validating Kerberos/SPNEGO tickets on server side is even simpler then client side.

Use `SpnegoClient` and authenticate in KDC (e.g. in Active Directory Domain Controller) using your server account.
Call `spnegoClient.createAcceptContext()` method to create a `SpnegoContext` instance responsible for authenticating your client.
Pass decoded SPNEGO token (Base64 decoded value of token in 'Authorization: Negotiate' header) to `spnegoContext.acceptToken` method to validate it.
  
Kerb4J comes with an Authenticator for Apache Tomcat (kerb4j-server-tomcat artifact) as well as authentication provider for Spring Security (See kerb4j-server-spring-security)

**Extracting groups from Kerberos ticket generated by Active Directory**

Spnego allows you to extract user groups from SPNEGO token (one sent from client to server) without making any additional requests to Active Directory.

```java
SpnegoInitToken spnegoInitToken = new SpnegoInitToken(decoded);
SpnegoKerberosMechToken spnegoKerberosMechToken = spnegoInitToken.getSpnegoKerberosMechToken();
Pac pac = spnegoKerberosMechToken.getPac(spnegoClient.getKerberosKeys());
PacLogonInfo logonInfo = pac.getLogonInfo();
List<String> roles = Stream.of(logonInfo.getGroupSids()).map(PacSid::toHumanReadableString).collect(Collectors.toList());
```
  
This functionality is specific to Microsoft Active Directory and supported both by Kerb4J Tomcat and Active Directory integrations. 
{'fraction_non_alphanumeric': 0.09615098825977114, 'fraction_numerical': 0.008470798038341507, 'mean_word_length': 5.4836223506743735, 'pattern_counts': {'":': 0, '<': 52, '<?xml version=': 0, '>': 52, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 6}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '546336', 'n_tokens_mistral': 2015, 'n_tokens_neox': 1876, 'n_words': 678}