org.forgerock.openig.jwt

Class JwtSessionManager

java.lang.Object

org.forgerock.openig.jwt.JwtSessionManager

All Implemented Interfaces:

SessionManager

public class JwtSessionManager
extends Object
implements SessionManager

A JwtSessionManager is responsible to configure and create a JwtCookieSession. Full secrets:

      
      {
          "name": "JwtSession",
          "type": "JwtSession",
          "config": {
              "encryptionSecretId": "encryption.key.id",
              "cookie": {
                  "name": "OpenIG",
                  "domain": ".example.com",
                  "path": "/",
                  "secure": false,
                  "httpOnly": true
              }
              "sessionTimeout": "30 minutes",
              "persistentCookie": true,
              "signatureSecretId": signature.key.id"
          }
      }
      
  

Or using passwordSecretId:

     
     {
         "name": "JwtSession",
         "type": "JwtSession",
         "config": {
             "alias": "PrivateKey Alias",
             "passwordSecretId": "keystore.secret.id",
             "cookie": {
                 "name": "OpenIG",
                 "domain": ".example.com",
                 "path": "/",
                 "secure": false,
                 "httpOnly": true
             }
             "sessionTimeout": "30 minutes",
             "persistentCookie": true,
             "signatureSecretId": signature.key.id"
         }
     }
     
 

All the session configuration is optional: if you omit everything, the appropriate keys will be generated and the cookie name used will be JwtCookieSession.OPENIG_JWT_SESSION.

The encryptionSecretId secret attribute specifies the name of the DataDecryptionKey that will be used to encrypt the JWT.

Or if not use:

The alias string attribute specifies the name of the private key to obtain from the KeyStore. It is only required when a keystore is specified.

The passwordSecretId is the label of a Purpose using Commons Secrets API, used to specifies the password to use when reading the private key from the KeyStore. It is only required when a keystore is specified.

Or:

The password [Deprecated since 6.5 in favor of passwordSecretId]. password is a static expression attribute specifies the password to use when reading the private key from the KeyStore. It is only required when a keystore is specified. NOTE: If both password and passwordSecretId are provided, the passwordSecretId has precedence.

The cookieName optional string attribute specifies the name of the cookie used to store the encrypted JWT.

The cookieDomain optional string attribute specifies the domain of the cookie used to store the encrypted JWT. If not set, the cookie will be treated as a host-based cookie.

The "cookie" optional structure describing the properties of the JWT session cookie: "name" : Name of cookie containing the IG JWT session. Defaults to JwtCookieSession.OPENIG_JWT_SESSION. "domain" : Domain that cookie is applicable to. If not set, the cookie will be treated as a host-based cookie "path" : Path to apply to the cookie. Defaults to "/" "secure" : Determines if the cookie should be set to be secure. Defaults to false. "httpOnly" : Determines if the cookie should be set to be httpOnly. Defaults to true.

The sessionTimeout optional duration attribute, specifies the amount of time before the JWT session expires. If not set, a default of 30 minutes is used. A duration of 0 is not valid and it will be limited to a maximum duration of approximately 10 years.

The persistentCookie optional boolean attribute (defaults to false), specifies whether the supporting cookie will have an Expires attribute (persistent cookie) or not (session cookie). The expiration value is based on the sessionTimeout value.

The signatureSecretId is the label of a Purpose using Commons Secrets API, the secret which specifies the key used to sign/verify the JWTs. It is expected to be Base64 encoded. If unspecified some random data is generated as key.

Since:

3.1

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	JwtSessionManager.Heaplet Creates and initializes a jwt-session in a heap environment.

Field Summary

Fields

Modifier and Type	Field and Description
static String	DEFAULT_SESSION_TIMEOUT Default sessionTimeout duration.
static Duration	MAX_SESSION_TIMEOUT The maximum session timeout duration, allows for an expiry time of approx 10 years (does not take leap years into consideration).

Constructor Summary

Constructors

Constructor and Description
JwtSessionManager(KeyPair keyPair, CookieBuilder cookieBuilder, Clock clock, Duration sessionTimeout, boolean persistentCookie, SigningHandler handler) Builds a new JwtSessionManager using the given KeyPair for session encryption, storing the opaque result in a cookie with the given name.

Method Summary

Modifier and Type	Method and Description
Session	load(Request request) Loads a new Session for the given Request.
void	save(Session session, Response response) Saves the session into the provided response.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DEFAULT_SESSION_TIMEOUT

public static final String DEFAULT_SESSION_TIMEOUT

Default sessionTimeout duration.

See Also:

Constant Field Values

MAX_SESSION_TIMEOUT

public static final Duration MAX_SESSION_TIMEOUT

The maximum session timeout duration, allows for an expiry time of approx 10 years (does not take leap years into consideration).

Constructor Detail

JwtSessionManager

public JwtSessionManager(KeyPair keyPair,
                         CookieBuilder cookieBuilder,
                         Clock clock,
                         Duration sessionTimeout,
                         boolean persistentCookie,
                         SigningHandler handler)

Builds a new JwtSessionManager using the given KeyPair for session encryption, storing the opaque result in a cookie with the given name.

Parameters:

keyPair - Private and public keys used for ciphering/deciphering.

cookieBuilder - The session cookie builder.

clock - Clock to use when dealing with JWT sessions' expiration.

sessionTimeout - The duration of the session.

persistentCookie - Issue a persistent cookie (with Expiry attribute) or a session cookie (no Expiry attribute)

handler - The JWT signing handler.

Method Detail

load

public Session load(Request request)

Description copied from interface: SessionManager

Loads a new Session for the given Request. The implementations are free to keep a reference to the Request.

The session object is scoped by the Request's own lifecycle.

Specified by:

load in interface SessionManager

Parameters:

request - Request to create a session for.

Returns:

a new Session instance.

save

public void save(Session session,
                 Response response)
          throws IOException

Description copied from interface: SessionManager

Saves the session into the provided response.

Specified by:

save in interface SessionManager

Parameters:

session - The session to save.

response - The response to save the session to.

Throws:

IOException - If the session could not be saved to the response.