<commit_before><p align="center">
  <img src="http://www.pac4j.org/img/logo.png" />
</p>

- [What is pac4j ?](#what-is-pac4j--)
- [The "big picture"](#the-big-picture)
- [Technical description](#technical-description)
- [Providers supported](#providers-supported)
- [Code sample](#code-sample)
- [Libraries built with pac4j](#libraries-built-with-pac4j)
- [Versions](#versions)
- [Testing](#testing)
- [Bugs / Features tracking](#bugs--features-tracking)
- [Contact](#contact)


## What is pac4j ? [![Build Status](https://travis-ci.org/leleuj/pac4j.png?branch=master)](https://travis-ci.org/leleuj/pac4j)

**pac4j** is a Profile & Authentication Client for Java, it's a general security library to authenticate users, get their profiles, manage their authorizations in order to secure web applications for all Java frameworks.


### Main concepts

- **Client**: an authentication client is responsible for starting the authentication process, getting the user credentials and the user profile
- **UserProfile**: it's the profile of an authenticated user (a hierarchy of user profiles exists: CommonProfile, OAuth20Profile, FacebookProfile...)
- **AttributesDefinition**: it's the attributes definition for a specific type of profile
- **Credentials**: it's a user credentials (a hierarchy of credentials exists: CasCredentials, Saml2Credentials, UsernamePasswordCredentials...)
- **Clients**: it's a helper class to define all clients together
- **Context**: it represents the current HTTP request and response, regardless of the framework
- **AuthorizationGenerator**: it's a class to compute the roles and permissions of a user from his profile
- **Authenticator**: it's a method to validate user credentials
- **ProfileCreator**: it's a method to create a user profile from credentials.


### Supported authentication methods

Although **pac4j** historically targets external authentication protocols, it supports direct authentication methods as well.

#### External/stateful authentication protocols

1. From the client application, save the requested url and redirect the user to the identity provider for authentication (HTTP 302)
2. After a successful authentication, redirect back the user from the identity provider to the client application (HTTP 302) and get the user credentials
3. With these credentials, get the profile of the authenticated user (direct call from the client application to the identity provider)
4. Redirect the user to the originally requested url and allow or disallow the access.

Supported protocols are:

1. OAuth (1.0 & 2.0)
2. CAS (1.0, 2.0, SAML, logout & proxy)
3. HTTP (form & basic auth authentications)<commit_msg>pac4j-118: Improve documentation and core concepts<commit_after><p align="center">
  <img src="http://www.pac4j.org/img/logo.png" />
</p>

- [What is pac4j ?](#what-is-pac4j--)
- [The "big picture"](#the-big-picture)
- [Technical description](#technical-description)
- [Providers supported](#providers-supported)
- [Code sample](#code-sample)
- [Libraries built with pac4j](#libraries-built-with-pac4j)
- [Versions](#versions)
- [Testing](#testing)
- [Bugs / Features tracking](#bugs--features-tracking)
- [Contact](#contact)


## What is pac4j ? [![Build Status](https://travis-ci.org/leleuj/pac4j.png?branch=master)](https://travis-ci.org/leleuj/pac4j)

**pac4j** is a Profile & Authentication Client for Java, it's a general security library to authenticate users, get their profiles, manage their authorizations in order to secure web applications for all Java frameworks.


### Main concepts

- **Client**: an authentication client is responsible for starting the authentication process, getting the user credentials and the user profile
- **UserProfile**: it's the profile of an authenticated user (a hierarchy of user profiles exists: CommonProfile, OAuth20Profile, FacebookProfile...)
- **AttributesDefinition**: it's the attributes definition for a specific type of profile
- **Credentials**: it's a user credentials (a hierarchy of credentials exists: CasCredentials, Saml2Credentials, UsernamePasswordCredentials...)
- **Clients**: it's a helper class to define all clients together
- **Context**: it represents the current HTTP request and response, regardless of the framework
- **AuthorizationGenerator**: it's a class to compute the roles and permissions of a user from his profile
- **Authenticator**: it's a method to validate user credentials
- **ProfileCreator**: it's a method to create a user profile from credentials.


### Supported authentication methods

Although **pac4j** historically targets external authentication protocols, it supports direct authentication methods as well. See the [authentication flows](https://github.com/pac4j/pac4j/wiki/Authentication-flows).

#### External/stateful authentication protocols

1. From the client application, save the requested url and redirect the user to the identity provider for authentication (HTTP 302)
2. After a successful authentication, redirect back the user from the identity provider to the client application (HTTP 302) and get the user credentials
3. With these credentials, get the profile of the authenticated user (direct call from the client application to the identity provider)
4. Redirect the user to the originally requested url and allow or disallow the access.

Supported protocols are:

1. OAuth (1.0 & 2.0)
2. CAS (1.0, 2.0, SAML, logout & proxy)
3. HTTP (form & basic auth authentications)
{'fraction_non_alphanumeric': 0.10358126721763085, 'fraction_numerical': 0.013590449954086318, 'mean_word_length': 5.1886363636363635, 'pattern_counts': {'":': 0, '<': 9, '<?xml version=': 0, '>': 9, 'https://': 5, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 2, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '36040', 'n_tokens_mistral': 1481, 'n_tokens_neox': 1379, 'n_words': 620}