Authentication (Oak Security SPI 1.22.12 API)

```
@ProviderType
public interface Authentication
```
The Authentication interface defines methods to validate Credentials during the login step of the authentication process. The validation depends on the authentication mechanism in place.
A given implementation may only handle certain types of Credentials as the authentication process is tightly coupled to the semantics of the Credentials.
For example a implementation may only be able to validate UserID/password pairs such as passed with SimpleCredentials, while another might be responsible for validating login token issued by the repository or an external access token generation mechanism.

Method Summary

All Methods Instance Methods Abstract Methods
Modifier and Type	Method	Description
`boolean`	`authenticate(@Nullable Credentials credentials)`	Validates the specified `Credentials` and returns `true` if the validation was successful.
`@Nullable String`	`getUserId()`	Optional method that return the userID extracted upon `authenticate(Credentials)`.
`@Nullable Principal`	`getUserPrincipal()`	Optional method that return the `Principal` of the authenticating user extracted upon `authenticate(Credentials)`.

- Method Detail
  - authenticate
```
boolean authenticate(@Nullable
                     @Nullable Credentials credentials)
              throws LoginException
```
    Validates the specified Credentials and returns true if the validation was successful.
    
    Parameters:
    
    credentials - to verify
    
    Returns:
    
    true if the validation was successful; false if the specified credentials are not supported and this authentication implementation cannot verify their validity.
    
    Throws:
    
    LoginException - if the authentication failed.
  - getUserId
```
@Nullable
@Nullable String getUserId()
```
    Optional method that return the userID extracted upon authenticate(Credentials). It is expected to return null if the implementation doesn't support this. An IllegalStateException may be thrown if called prior to authenticate(Credentials).
    
    Returns:
    
    a user identifier or null
  - getUserPrincipal
```
@Nullable
@Nullable Principal getUserPrincipal()
```
    Optional method that return the Principal of the authenticating user extracted upon authenticate(Credentials). It is expected to return null if the implementation doesn't support this. An IllegalStateException may be thrown if called prior to authenticate(Credentials).
    
    Returns:
    
    a valid Principal or null