Authenticator

An Authenticator is a key part of a Silhouette application, because it tracks a user 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 handles that kind of authenticator. This service is responsible for the following actions:

Create an authenticator

Creates a new authenticator for the login information of an identity. This step should be executed after a successful authentication. The created authenticator can then be used to track 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 part of the incoming HTTP request (user session, cookie, user defined header field, request param). 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.

Init 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 by 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.

🚧

Attention

The following actions are only used for internal purposes inside a Silhouette endpoint. It’s provided here as background information and for advanced users.

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 fix expiration date. With this method it’s 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.

📘

Note

To renew an authenticator you must call the renew method of the authenticator instance inside a Silhouette endpoint. This method accepts a Result and returns a wrapped Renew result, which notifies the action to renew the authenticator instead of updating it.

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.

📘

Note

To discard an authenticator you must call the discard method of the authenticator instance inside a Silhouette endpoint. This method accepts a Result and returns a wrapped Discard result, which notifies the action to discard the authenticator instead of updating it.

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

Good decision aids can be found in the blog posts Cookies vs Tokens. Getting auth right with Angular.JS and 10 Things You Should Know about Tokens from Auth0.

CookieAuthenticator

An authenticator that uses a stateful, cookie-based approach. It works by storing the unique ID of the authenticator in a cookie. This ID gets then mapped to an authenticator instance in the server side backing store. This 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.

Pros

• Small network throughput on client side
• Ideal for traditional browser based websites
• Client fingerprinting

Cons

• Larger network throughput on the server side
• Not stateless (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

New in version 2.0

An authenticator that 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

👍

Tip

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

BearerTokenAuthenticator

New in version 2.0

An authenticator that 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

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

New in version 2.0

An authenticator that 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.

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

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

New in version 2.0

An authenticator that 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