[[Credentials]]
=== Authentication credentials

The Holon Platform provides a support for authentication _credentials_ management, relying on the following structures:

* The link:{apidir}/com/holonplatform/auth/Credentials.html[Credentials^] API to represent credentials data, for example a _secret_ access token and the encoding informations related to it.
* The link:{apidir}/com/holonplatform/auth/CredentialsContainer.html[CredentialsContainer^] API to be used as a  credentials data holder (for example, the stored account informations related to a _principal_ and the credentials provided by a _principal_ with an authentication request).
* The link:{apidir}/com/holonplatform/auth/CredentialsContainer.CredentialsMatcher.html[CredentialsMatcher^] API to deal with credential validation, to check if two _credentials_ representations match.

==== Credentials creation

The link:{apidir}/com/holonplatform/auth/Credentials.html[Credentials^] interface provides a _builder_ to create and encode a `Credentials` representation, basing on the `String` representation of the _secret_ access token (for example, a password).

The `Credentials` builder provides method to encode a the _secret_ representation by using a _hashing_ algorithm (specifying also a _salt_ and the hash iterations to be performed), specifing an optional _expiry date_ and applying encoding methods, for example `Base64`.

[source, java]
----
include::{examplesdir}/com/holonplatform/core/examples/ExampleCredentials.java[tag=credentials,indent=0]
----
<1> Simple credentials using `test` as secret and no encodings
<2> Credentials using `test` as secret and `MD5` as hashing algorithm
<3> Credentials using `test` as secret and `MD5` as hashing algorithm, with a _salt_ and 7 hashing iterations
<4> Credentials using `test` as secret and `MD5` as hashing algorithm, encoded using _Base64_
<5> Simple credentials using `test` as secret and no encodings, specifying an _expiry date_

==== Credentials encoding

To encode credentials data, for example for storing purposes, the `Credentials` interface provides an `Encoder` interface, which can be obtained through the `encoder()` static method.

[source, java]
.Credentials encoding examples
----
include::{examplesdir}/com/holonplatform/core/examples/ExampleCredentials.java[tag=encoder,indent=0]
----
<1> Credentials using `test` as secret and _Base64_ encoded
<2> Credentials using `test` as secret and `SHA-256` as hashing algorithm, returned as bytes
<3> Credentials using `test` as secret and `SHA-256` as hashing algorithm, with a _salt_ and _Base64_ encoded
<4> Credentials using `test` as secret and `SHA-512` as hashing algorithm, encoded using _Base64_ with the UTF-8 charset

[[CredentialsContainer]]
==== Credentials container

The link:{apidir}/com/holonplatform/auth/CredentialsContainer.html[CredentialsContainer^] API represents a _credentials_ holder, providing the credentials data through the `getCredentials()`.

The credentials data is provided using a generic `Object` type, since the specific credentials representation is higly dependent from the concrete implementations.

The <<AuthenticationToken>> API is an example of `CredentialsContainer`.

[[CredentialsMatcher]]
==== Credentials matching

Credentials matching can be performed using the link:{apidir}/com/holonplatform/auth/CredentialsContainer.CredentialsMatcher.html[CredentialsMatcher^] API.

The `CredentialsMatcher` API can be used to compare two credentials representations, providing the providing the respective `CredentialsContainer` instances.

The Holon Platform provides a *default* `CredentialsMatcher` implementation which can be obtained through the `defaultMatcher()` method from the `CredentialsContainer` interface.

The default credentials matcher tries to employ best-practices and common behaviours to perform credentials validation and matching:

* Obtain the credentials representations using the `getCredentials()` method of the <<CredentialsContainer>> representation.
* Try to convert generic Object credentials data into a *byte array*:
** Supports `char[]`, `String`, `File` and `InputStream` for direct bytes conversion.
** Supports the `Credentials` type, using the `getSecret()` method to obtain the credentials secret representation.
* If the provided credentials data are of `Credentials` type and an _expiry date_ is provided, it checks the credentials are not expired.
* It checks if the array of bytes obtained from the two credentials data structures *match*, hashing and/or decoding the credentials data if these informations are available.
