Silhouette

Authenticators

CookieAuthenticator

To configure the CookieAuthenticator service you must use the CookieAuthenticatorSettings class. This class has the following form:

case class CookieAuthenticatorSettings(
  cookieName: String = "id",
  cookiePath: String = "/",
  cookieDomain: Option[String] = None,
  secureCookie: Boolean = true,
  httpOnlyCookie: Boolean = true,
  useFingerprinting: Boolean = true,
  cookieMaxAge: Option[FiniteDuration] = None,
  authenticatorIdleTimeout: Option[FiniteDuration] = None,
  authenticatorExpiry: FiniteDuration = 12 hours)
Property
Description

cookieName

The cookie name

cookiePath

The cookie path

cookieDomain

The cookie domain

secureCookie

Whether this cookie is secured, sent only for HTTPS requests.

Note:
This should be disabled for testing on localhost without SSL, otherwise cookie couldn't be set

httpOnlyCookie

Whether this cookie is HTTP only, i.e. not accessible from client-side JavaScript code

useFingerprinting

Indicates if a fingerprint of the user should be stored in the authenticator

cookieMaxAge

The duration a cookie expires. None for a transient cookie

authenticatorIdleTimeout

The duration an authenticator can be idle before it timed out. This means, if you set the time to 5 minutes then a user will be logged out if he visits the site again after 5 minutes and 1 second. If he visits the site before the authenticator times out then he has again 5 minutes until the authenticator times out.

authenticatorExpiry

The duration an authenticator expires after it was created. This means, if the timeout is set to 1 day, then the authenticator expires definitely after one day.

Example

authenticator.cookieName = "authenticator"
authenticator.cookiePath = "/"
authenticator.secureCookie = false
authenticator.httpOnlyCookie = true
authenticator.useFingerprinting = true
authenticator.authenticatorIdleTimeout = 30 minutes
authenticator.authenticatorExpiry = 12 hours

SessionAuthenticator

To configure the SessionAuthenticator service you must use the SessionAuthenticatorSettings class. This class has the following form:

case class SessionAuthenticatorSettings(
  sessionKey: String = "authenticator",
  useFingerprinting: Boolean = true,
  authenticatorIdleTimeout: Option[FiniteDuration] = None,
  authenticatorExpiry: FiniteDuration = 12 hours)
Property
Description

sessionKey

The key of the authenticator in the session

useFingerprinting

Indicates if a fingerprint of the user should be stored in the

authenticatorIdleTimeout

The duration an authenticator can be idle before it timed out. This means, if you set the time to 5 minutes then a user will be logged out if he visits the site again after 5 minutes and 1 second. If he visits the site before the authenticator times out then he has again 5 minutes until the authenticator times out.

authenticatorExpiry

The duration an authenticator expires after it was created. This means, if the timeout is set to 1 day, then the authenticator expires definitely after one day.

Example

authenticator.sessionKey = "authenticator"
authenticator.useFingerprinting = true
authenticator.authenticatorIdleTimeout = 30 minutes
authenticator.authenticatorExpiry = 12 hours

BearerTokenAuthenticator

To configure the BearerTokenAuthenticator service you must use the BearerTokenAuthenticatorSettings class. This class has the following form:

case class BearerTokenAuthenticatorSettings(
  fieldName: String = "X-Auth-Token",
  requestParts: Option[Seq[RequestPart.Value]] = Some(Seq(RequestPart.Headers)),
  authenticatorIdleTimeout: Option[FiniteDuration] = None,
  authenticatorExpiry: FiniteDuration = 12 hours)
Property
Description

fieldName

The name of the field in which the token will be transferred in any part of the request

requestParts

Some request parts from which a value can be extracted or None to extract values from any part of the request. Default is set to Headers only. This functionality is useful if the token should be transported into another part of the request. For a WebSocket, opened from JavaScript, the token must be transported in the query string, because the JavaScript WebSockets API doesn't allow additional headers.

authenticatorIdleTimeout

The duration an authenticator can be idle before it timed out. This means, if you set the time to 5 minutes then a user will be logged out if he visits the site again after 5 minutes and 1 second. If he visits the site before the authenticator times out then he has again 5 minutes until the authenticator times out.

authenticatorExpiry

The duration an authenticator expires after it was created. This means, if the timeout is set to 1 day, then the authenticator expires definitely after one day.

Example

Enumeration based values in the configuration

The authenticator.requestParts configuration property uses Enumeration based values. This values can be parsed with Ficus if you import the additional EnumerationReader.

authenticator.fieldName = "X-Auth-Token"
authenticator.authenticatorIdleTimeout = 30 minutes
authenticator.authenticatorExpiry = 12 hours

JWTAuthenticator

To configure the JWTAuthenticator service you must use the JWTAuthenticatorSettings
class. This class has the following form:

case class JWTAuthenticatorSettings(
  fieldName: String = "X-Auth-Token",
  requestParts: Option[Seq[RequestPart.Value]] = Some(Seq(RequestPart.Headers)),
  issuerClaim: String = "play-silhouette",
  authenticatorIdleTimeout: Option[FiniteDuration] = None,
  authenticatorExpiry: FiniteDuration = 12 hours,
  sharedSecret: String)
Property
Description

fieldName

The name of the field in which the token will be transferred in any part of the request

requestParts

Some request parts from which a value can be extracted or None to extract values from any part of the request. Default is set to Headers only. This functionality is useful if the token should be transported into another part of the request. For a WebSocket, opened from JavaScript, the token must be transported in the query string, because the JavaScript WebSockets API doesn't allow additional headers.

issuerClaim

The issuer claim identifies the principal that issued the JWT

authenticatorIdleTimeout

The duration an authenticator can be idle before it times out. This means, if you set the time to 5 minutes then a user will be logged out if he visits the site again after 5 minutes and 1 second. If he visits the site before the authenticator times out then he has again 5 minutes until the authenticator times out.

authenticatorExpiry

The duration an authenticator expires after it was created. This means, if the timeout is set to 1 day, then the authenticator expires definitely after one day.

sharedSecret

The shared secret to sign the JWT

Example

Enumeration based values in the configuration

The authenticator.requestParts configuration property uses Enumeration based values. This values can be parsed with Ficus if you import the additional EnumerationReader.

authenticator.fieldName = "X-Auth-Token"
authenticator.requestParts = ["headers"]
authenticator.issuerClaim = "play-angular-silhouette"
authenticator.authenticatorExpiry = 12 hours
authenticator.sharedSecret = "changeme"

What's Next

Gravatar service

Authenticators