Session

Realm Operations

Resource path:

/realm-config/services/session

Resource version: 1.0

create

Usage

am> create Session --realm Realm --body body

Parameters

--body

The resource in JSON format, described by the following JSON schema:

{
  "type" : "object",
  "properties" : {
    "dynamic" : {
      "properties" : {
        "maxSessionTime" : {
          "title" : "Maximum Session Time",
          "description" : "Maximum time a session can remain valid before OpenAM requires the user to authenticate again, in minutes.",
          "propertyOrder" : 100,
          "required" : true,
          "type" : "integer",
          "exampleValue" : ""
        },
        "maxIdleTime" : {
          "title" : "Maximum Idle Time",
          "description" : "Maximum time a CTS-based session can remain idle before OpenAM requires the user to authenticate again, in minutes.",
          "propertyOrder" : 200,
          "required" : true,
          "type" : "integer",
          "exampleValue" : ""
        },
        "quotaLimit" : {
          "title" : "Active User Sessions",
          "description" : "Maximum number of concurrent CTS-based sessions OpenAM allows a user to have.",
          "propertyOrder" : 800,
          "required" : true,
          "type" : "integer",
          "exampleValue" : ""
        },
        "maxCachingTime" : {
          "title" : "Maximum Caching Time",
          "description" : "Maximum time that external clients of AM are recommended to cache the session for, in minutes.",
          "propertyOrder" : 300,
          "required" : true,
          "type" : "integer",
          "exampleValue" : ""
        }
      },
      "type" : "object",
      "title" : "Dynamic Attributes"
    }
  }
}

delete

Usage

am> delete Session --realm Realm

getAllTypes

Obtain the collection of all secondary configuration types related to the resource.

Usage

am> action Session --realm Realm --actionName getAllTypes

getCreatableTypes

Obtain the collection of secondary configuration types that have yet to be added to the resource.

Usage

am> action Session --realm Realm --actionName getCreatableTypes

nextdescendents

Obtain the collection of secondary configuration instances that have been added to the resource.

Usage

am> action Session --realm Realm --actionName nextdescendents

read

Usage

am> read Session --realm Realm

update

Usage

am> update Session --realm Realm --body body

Parameters

--body

The resource in JSON format, described by the following JSON schema:

{
  "type" : "object",
  "properties" : {
    "dynamic" : {
      "properties" : {
        "maxSessionTime" : {
          "title" : "Maximum Session Time",
          "description" : "Maximum time a session can remain valid before OpenAM requires the user to authenticate again, in minutes.",
          "propertyOrder" : 100,
          "required" : true,
          "type" : "integer",
          "exampleValue" : ""
        },
        "maxIdleTime" : {
          "title" : "Maximum Idle Time",
          "description" : "Maximum time a CTS-based session can remain idle before OpenAM requires the user to authenticate again, in minutes.",
          "propertyOrder" : 200,
          "required" : true,
          "type" : "integer",
          "exampleValue" : ""
        },
        "quotaLimit" : {
          "title" : "Active User Sessions",
          "description" : "Maximum number of concurrent CTS-based sessions OpenAM allows a user to have.",
          "propertyOrder" : 800,
          "required" : true,
          "type" : "integer",
          "exampleValue" : ""
        },
        "maxCachingTime" : {
          "title" : "Maximum Caching Time",
          "description" : "Maximum time that external clients of AM are recommended to cache the session for, in minutes.",
          "propertyOrder" : 300,
          "required" : true,
          "type" : "integer",
          "exampleValue" : ""
        }
      },
      "type" : "object",
      "title" : "Dynamic Attributes"
    }
  }
}

Global Operations

Resource path:

/global-config/services/session

Resource version: 1.0

getAllTypes

Obtain the collection of all secondary configuration types related to the resource.

Usage

am> action Session --global --actionName getAllTypes

getCreatableTypes

Obtain the collection of secondary configuration types that have yet to be added to the resource.

Usage

am> action Session --global --actionName getCreatableTypes

nextdescendents

Obtain the collection of secondary configuration instances that have been added to the resource.

Usage

am> action Session --global --actionName nextdescendents

read

Usage

am> read Session --global

update

Usage

am> update Session --global --body body

Parameters

--body

The resource in JSON format, described by the following JSON schema:

{
  "type" : "object",
  "properties" : {
    "stateless" : {
      "type" : "object",
      "title" : "Client-based Sessions",
      "propertyOrder" : 4,
      "properties" : {
        "openam-session-stateless-blacklist-cache-size" : {
          "title" : "Session Blacklist Cache Size",
          "description" : "Number of blacklisted sessions to cache in memory to speed up blacklist checks and reduce load on the CTS. The cache size should be approximately the number of logouts expected in the maximum session time.",
          "propertyOrder" : 2700,
          "required" : true,
          "type" : "integer",
          "exampleValue" : ""
        },
        "statelessEncryptionType" : {
          "title" : "Encryption Algorithm",
          "description" : "Specifies the algorithm that AM uses to encrypt the JSON Web Token (JWT) containing the session content.<br><br>AM supports the following encryption algorithms:<ul><li><strong>NONE</strong>. No encryption is selected.</li><li><strong>RSA</strong>. Session content is encrypted with AES using a unique key. The key is then encrypted with an RSA public key and appended to the JWT.<p><p>AM supports the following padding modes, which you can set using the <code>org.forgerock.openam.session.stateless.rsa.padding</code> advanced property:<ul><li><code>RSA1_5</code>. RSA with PKCS#1 v1.5 padding.</li><li><code>RSA-OAEP</code>. RSA with optimal asymmetric encryption padding (OAEP) and SHA-1.</li><li><code>RSA-OAEP-256</code>. RSA with OAEP padding and SHA-256.</li></ul></li><li><strong>AES KeyWrapping</strong>. Session content is encrypted with AES using a unique key and is then wrapped using AES KeyWrap and the master key. This provides additional security, compared to RSA, at the cost of 128 or 256 bits (or 32 bytes) depending on the size of the master key. This method provides authenticated encryption, which removes the need for a separate signature and decreases the byte size of the JWT. See <a href=\"https://tools.ietf.org/html/rfc3394\" target=\"_blank\">RFC 3394</a>.</li><li><strong>Direct AES Encryption</strong>.  Session content is encrypted with direct AES encryption with a symmetric key. This method provides authenticated encryption, which removes the need for a separate signature and decreases the byte size of the JWT. </li></ul><p><p><strong>Important</strong>: To prevent users from accidentally disabling all authentication support, which can be accomplished by disabling signing and not using an authenticated encryption mode, you must set the <code>org.forgerock.openam.session.stateless.signing.allownone</code> system property to <code>true</code> to turn off signing completely.",
          "propertyOrder" : 2200,
          "required" : true,
          "type" : "string",
          "exampleValue" : ""
        },
        "openam-session-stateless-blacklist-purge-delay" : {
          "title" : "Blacklist Purge Delay (minutes)",
          "description" : "When added to the maximum session time, specifies the amount of time that AM tracks logged out sessions.<br><br>Increase the blacklist purge delay if you expect system clock skews in a deployment of AM servers to be greater than one minute. There is no need to increase the blacklist purge delay for servers running a clock synchronization protocol, such as Network Time Protocol.",
          "propertyOrder" : 2900,
          "required" : true,
          "type" : "integer",
          "exampleValue" : ""
        },
        "statelessEncryptionAesKey" : {
          "title" : "Encryption Symmetric AES Key",
          "description" : "AES key for use with Direct or AES KeyWrap encryption modes.<br><br>The symmetric AES key is a base64-encoded random key.<p><p>For direct encryption with <code>AES-GCM</code> or for <code>AES-KeyWrap</code> with any content encryption method, this should be 128, 192, or 256 bits.<p><p>For direct encryption with <code>AES-CBC-HMAC</code>, the key should be double those sizes (one half for the AES key, the other have for the HMAC key).<p><p>AES key sizes greater than 128 bits require installation of the JCE Unlimited Strength policy files in your JRE.",
          "propertyOrder" : 2400,
          "required" : true,
          "type" : "string",
          "format" : "password",
          "exampleValue" : ""
        },
        "statelessSigningType" : {
          "title" : "Signing Algorithm Type",
          "description" : "Specifies the algorithm that AM uses to sign the JSON Web Token (JWT) containing the session content. Signing the JWT enables tampering detection.<br><br>AM supports the following signing algorithms: <ul><li><strong>HS256</strong>. HMAC using SHA-256.</li><li><strong>HS384</strong>. HMAC using SHA-384.</li><li><strong>HS512</strong>. HMAC using SHA-512.</li><li><strong>RS256</strong>. RSASSA-PKCS1-v1_5 using SHA-256.</li><li><strong>ES256</strong>. ECDSA using SHA-256 and NIST standard P-256 elliptic curve.</li><li><strong>ES384</strong>. ECDSA using SHA-384 and NIST standard P-384 elliptic curve.</li><li><strong>ES512</strong>. ECDSA using SHA-512 and NIST standard P-521 elliptic curve.</li></ul>",
          "propertyOrder" : 1900,
          "required" : true,
          "type" : "string",
          "exampleValue" : ""
        },
        "openam-session-stateless-enable-session-blacklisting" : {
          "title" : "Enable Session Blacklisting",
          "description" : "Blacklists client-based sessions that log out.<br><br>We recommend enabling this setting if the maximum session time is high. Blacklist state is stored in the Core Token Service (CTS) token store until the session expires, in order to ensure that sessions cannot continue to be used.",
          "propertyOrder" : 2600,
          "required" : true,
          "type" : "boolean",
          "exampleValue" : ""
        },
        "statelessCompressionType" : {
          "title" : "Compression Algorithm",
          "description" : "If enabled the session state is compressed before signing and encryption.<br><br><strong>WARNING</strong>: Enabling compression may compromise encryption. This may leak information about the content of the session state if encryption is enabled.",
          "propertyOrder" : 2500,
          "required" : true,
          "type" : "string",
          "exampleValue" : ""
        },
        "statelessSigningHmacSecret" : {
          "title" : "Signing HMAC Shared Secret",
          "description" : "Specifies the shared secret that AM uses when performing HMAC signing on the session JWT.<p><p>Specify a shared secret when using a \"Signing Algorithm Type\" of <code>HS256</code>, <code>HS384</code>, or <code>HS512</code>.",
          "propertyOrder" : 2000,
          "required" : true,
          "type" : "string",
          "format" : "password",
          "exampleValue" : ""
        },
        "openam-session-stateless-blacklist-poll-interval" : {
          "title" : "Blacklist Poll Interval (seconds)",
          "description" : "Specifies the interval at which AM polls the Core Token Service to update the list of logged out sessions, in seconds.<br><br>The longer the polling interval, the more time a malicious user has to connect to other AM servers in a deployment and make use of a stolen session cookie. Shortening the polling interval improves the security for logged out sessions, but might incur a minimal decrease in overall AM performance due to increased network activity. Set to <code>0</code> to disable this feature completely.",
          "propertyOrder" : 2800,
          "required" : true,
          "type" : "integer",
          "exampleValue" : ""
        }
      }
    },
    "search" : {
      "type" : "object",
      "title" : "Session Search",
      "propertyOrder" : 1,
      "properties" : {
        "sessionListRetrievalTimeout" : {
          "title" : "Timeout for Search",
          "description" : "Time after which OpenAM sees an incomplete search as having failed, in seconds.",
          "propertyOrder" : 500,
          "required" : true,
          "type" : "integer",
          "exampleValue" : ""
        },
        "maxSessionListSize" : {
          "title" : "Maximum Number of Search Results",
          "description" : "Maximum number of results from a session search. Do not set this attribute to a large value, for example more than 1000, unless sufficient system resources are allocated.",
          "propertyOrder" : 400,
          "required" : true,
          "type" : "integer",
          "exampleValue" : ""
        }
      }
    },
    "quotas" : {
      "type" : "object",
      "title" : "Session Quotas",
      "propertyOrder" : 3,
      "properties" : {
        "iplanet-am-session-enable-session-constraint" : {
          "title" : "Enable Quota Constraints",
          "description" : "If on, then OpenAM allows you to set quota constraints on CTS-based sessions.",
          "propertyOrder" : 700,
          "required" : true,
          "type" : "string",
          "exampleValue" : ""
        },
        "quotaConstraintMaxWaitTime" : {
          "title" : "Read Timeout for Quota Constraint",
          "description" : "Maximum wait time after which OpenAM considers a search for live session count as having failed if quota constraints are enabled, in milliseconds.",
          "propertyOrder" : 900,
          "required" : true,
          "type" : "integer",
          "exampleValue" : ""
        },
        "denyLoginWhenRepoDown" : {
          "title" : "Deny user login when session repository is down",
          "description" : "This property only takes effect when the session quota constraint is enabled, and the session data store is unavailable.",
          "propertyOrder" : 1100,
          "required" : true,
          "type" : "string",
          "exampleValue" : ""
        },
        "behaviourWhenQuotaExhausted" : {
          "title" : "Resulting behavior if session quota exhausted",
          "description" : "Specify the action to take if a session quota is exhausted:<ul><li><strong>Deny Access</strong>. New session creation requests will be denied.</li><li><strong>Destroy Next Expiring</strong>. The session that would expire next will be destroyed.</li><li><strong>Destroy Oldest</strong>. The oldest session will be destroyed.</li><li><strong>Destroy All</strong>. All previous sessions will be destroyed.</li></ul>",
          "propertyOrder" : 1000,
          "required" : true,
          "type" : "string",
          "exampleValue" : ""
        }
      }
    },
    "general" : {
      "type" : "object",
      "title" : "General",
      "propertyOrder" : 0,
      "properties" : {
        "timeoutHandlers" : {
          "title" : "Session Timeout Handler implementations",
          "description" : "Lists plugin classes implementing session timeout handlers. Specify the fully qualified name.",
          "propertyOrder" : 1800,
          "required" : true,
          "items" : {
            "type" : "string"
          },
          "type" : "array",
          "exampleValue" : ""
        },
        "latestAccessTimeUpdateFrequency" : {
          "title" : "Latest Access Time Update Frequency",
          "description" : "Defaults to <code>60</code> seconds. At most, AM updates a session's latest access time this often.<br><br>Subsequent touches to the session that occur within the specified number of seconds after an update will not cause additional updates to the session's access time.<p><p>Refreshing a session returns the idle time as the number of seconds since an update has occurred, which will be between <code>0</code> and the specified Latest Access Time Update Frequency.",
          "propertyOrder" : null,
          "required" : true,
          "type" : "integer",
          "exampleValue" : ""
        },
        "dnRestrictionOnly" : {
          "title" : "DN Restriction Only Enabled",
          "description" : "If enabled, OpenAM will not perform DNS lookups when checking restrictions in cookie hijacking mode.",
          "propertyOrder" : 1300,
          "required" : true,
          "type" : "boolean",
          "exampleValue" : ""
        }
      }
    },
    "notifications" : {
      "type" : "object",
      "title" : "Session Property Change Notifications",
      "propertyOrder" : 2,
      "properties" : {
        "notificationPropertyList" : {
          "title" : "Notification Properties",
          "description" : "Lists session properties for which OpenAM can send notifications upon modification. Session notification applies to CTS-based sessions only.",
          "propertyOrder" : 1200,
          "required" : true,
          "items" : {
            "type" : "string"
          },
          "type" : "array",
          "exampleValue" : ""
        },
        "propertyChangeNotifications" : {
          "title" : "Enable Property Change Notifications",
          "description" : "If on, then OpenAM notifies other applications participating in SSO when a session property in the Notification Properties list changes on a CTS-based session.",
          "propertyOrder" : 600,
          "required" : true,
          "type" : "string",
          "exampleValue" : ""
        }
      }
    },
    "dynamic" : {
      "properties" : {
        "maxSessionTime" : {
          "title" : "Maximum Session Time",
          "description" : "Maximum time a session can remain valid before OpenAM requires the user to authenticate again, in minutes.",
          "propertyOrder" : 100,
          "required" : true,
          "type" : "integer",
          "exampleValue" : ""
        },
        "maxCachingTime" : {
          "title" : "Maximum Caching Time",
          "description" : "Maximum time that external clients of AM are recommended to cache the session for, in minutes.",
          "propertyOrder" : 300,
          "required" : true,
          "type" : "integer",
          "exampleValue" : ""
        },
        "quotaLimit" : {
          "title" : "Active User Sessions",
          "description" : "Maximum number of concurrent CTS-based sessions OpenAM allows a user to have.",
          "propertyOrder" : 800,
          "required" : true,
          "type" : "integer",
          "exampleValue" : ""
        },
        "maxIdleTime" : {
          "title" : "Maximum Idle Time",
          "description" : "Maximum time a CTS-based session can remain idle before OpenAM requires the user to authenticate again, in minutes.",
          "propertyOrder" : 200,
          "required" : true,
          "type" : "integer",
          "exampleValue" : ""
        }
      },
      "type" : "object",
      "title" : "Dynamic Attributes"
    }
  }
}