Authenticator

An Authenticator is a key part of a Silhouette application, because it recognizes a user on every request after a successful authentication. The Authenticator itself is a small class which stores only some data like its validity and the linked login information for an identity.

Authenticator Service

Every Authenticator has an associated Authenticator Service which implements the Authenticator's functionality. This service is responsible for the following actions:

Create an Authenticator

Creates a new Authenticator from the an identity's login information. This action should be executed after a successful authentication. The created Authenticator can then be used to recognize the user on every subsequent request.

Retrieve an Authenticator

An Authenticator service is used to check an incoming request for an existing instance of its Authenticator. An Authenticator can be embedded in any aspect of the incoming HTTP request (user session, cookie, user-defined header field, or request parameter). Some services can validate a retrieved Authenticator, based on its ID, against a backing store. Silhouette automatically tries to retrieve an Authenticator on every request to a Silhouette endpoint.

Initialize an Authenticator

Authenticators need to be initialized, usually when they are created during a successful authentication. If the service uses a backing store, then the Authenticator instance will be stored in it, to check the validity of an Authenticator on every subsequent request to the application.

Embed an Authenticator

After initialization, an Authenticator must be embedded into a Play framework request or result. This can by done in several ways, including creating a cookie, storing data into the user session or including the Authenticator in a user-defined header.

Embedding the Authenticator-related data into the result means that the data will be sent to the client. It may also be useful to embed the Authenticator-related data into an incoming request to lead a Silhouette endpoint to believe that the request is a new request which contains a valid Authenticator. This is typically done in tests or Play filters.

Touch an Authenticator

For Authenticators that use a sliding window expiration, calling touch causes the last used time to be updated upon each request to a Silhouette endpoint. Such updates are not needed for Authenticators that do not use a sliding window expiration.

Update an Authenticator

Automatically updates the state of an Authenticator on every request to a Silhouette endpoint. Updated Authenticators will be embedded into the Play framework result before sending it to the client. If the service uses a backing store, then the Authenticator instance will be updated in the store, too.

Renew an Authenticator

Authenticators have a fixed expiration date. With this method it is possible to renew the expiration of an Authenticator by discarding the old one and creating a new one. Based on the implementation, the renew method revokes the given Authenticator first, before creating a new one. If the Authenticator was updated, then the updated artifacts will be embedded into the response.

Discard an Authenticator

Every request to a Silhouette endpoint causes invalid Authenticators to be automatically discarded. Discarding means that all client-side stored artifacts will be removed. If the service uses a backing store, then the Authenticator will also be removed from it.

Logging a user out of a Silhouette application requires explicitly discarding the Authenticator.

List of authenticators

Silhouette comes with a set of stateless as well as stateful authenticator implementations that cover most use cases. It’s up to you to decide which authenticator fits best into your application architecture.

👍

Hint

You can find guidance on authenticators in the blog posts Cookies vs Tokens. Getting auth right with Angular.JS and 10 Things You Should Know about Tokens from Auth0.

CookieAuthenticator

The CookieAuthenticator can use a stateful as well as stateless cookie-based approach. It works either by storing an ID in a cookie to track the authenticated user and a server-side backing store that maps the ID to an Authenticator instance or by a stateless approach that stores the Authenticator in a serialized form directly into the cookie. The stateful approach could also be named “server-side session”.

The Authenticator can use a sliding window expiration. This means that the Authenticator times out after a certain time if it hasn't been used. This can be controlled with the authenticatorIdleTimeout property of the settings class.

📘

Note

The stateful or stateless approach is selected depending on whether a AuthenticatorRepository was supplied to the authenticator service.

Pros

• Small network throughput on client side
• Ideal for traditional browser based websites
• Client fingerprinting
• Can be stateless
• Can be used for remember me functionality

Cons

• The stateless cookie has larger network throughput on client side
• The stateful cookie has larger network throughput on the server side
• The stateful cookie needs a synchronized backing store
• Less than ideal for mobile or single page apps
• Can be vulnerable for CSRF attacks
• Does not play well with CORS

👍

Tip

Please take a look on the configuration settings, on how to configure this authenticator.

SessionAuthenticator

The SessionAuthenticator uses a stateless, session-based approach. It works by storing a serialized authenticator instance in the Play Framework session cookie.

The authenticator can use a sliding window expiration. This means that the authenticator times out after a certain time if it hasn't been used. This can be controlled with the authenticatorIdleTimeout property of the settings class.

Pros

• No network throughput on the server side
• Ideal for traditional browser-based websites
• Client fingerprinting
• Stateless

Cons

• Larger network throughput on client side
• Less than ideal for mobile or single page apps
• Can be vulnerable for CSRF attacks
• Does not play well with CORS
• Cannot be used for remember me functionality

👍

Tip

Please take a look on the configuration settings, on how to configure this authenticator.

BearerTokenAuthenticator

The BearerTokenAuthenticator uses a header-based approach with the help of a bearer token. It works by transporting a token in a user-defined header to track the authenticated user and a server-side backing store that maps the token to an Authenticator instance.

The Authenticator can use a sliding window expiration. This means that the Authenticator times out after a certain time if it hasn't been used. This can be controlled with the authenticatorIdleTimeout property of the settings class.

Pros

• Small network throughput on client side
• Ideal for mobile or single page apps
• Not vulnerable against CSRF attacks
• Plays well with CORS
• Can be used for remember me functionality

Cons

• Larger network throughput on the server side
• Not stateless (needs a synchronized backing store)
• Less than ideal for traditional browser based websites
• No client fingerprinting

👍

Tip

Please take a look on the configuration settings, on how to configure this authenticator.

JWTAuthenticator

The JWTAuthenticator uses a header-based approach with the help of a JWT (JSON Web Token). It works by using a JWT to transport the Authenticator data inside a user-defined header. It can be stateless with the disadvantages that the JWT can’t be invalidated.

The authenticator can use a sliding window expiration. This means that the authenticator times out after a certain time if it hasn’t been used. This can be controlled with the authenticatorIdleTimeout property of the settings class. If this feature is activated then a new token will be generated on every update. Make sure your application can handle this case.

📘

Note

The stateful or stateless approach is selected depending on whether a AuthenticatorRepository was supplied to the authenticator service.

Pros

• Ideal for mobile or single page apps
• Can be stateless (with the disadvantages it can’t be invalidated)
• Not vulnerable against CSRF attacks
• Plays well with CORS
• Can transport arbitrary claims
• Can be used for remember me functionality

Cons

• Larger network throughput on client side
• Larger network throughput on the server side (if backing store is used)
• Less than ideal for traditional browser based websites
• No client fingerprinting

👍

Tip

Please take a look on the configuration settings, on how to configure this authenticator.

DummyAuthenticator

The DummyAuthenticator can be used if a client doesn’t need an authenticator to track a user. This can be useful for request providers, because authentication may occur here on every request to a protected resource.

Pros

• Ideal for request providers
• Doesn’t have any network throughput or memory footprint compared to other authenticators

Cons

• Cannot track users
• Only useful for request providers