Miscellaneous Heap Objects ClientRegistration — Hold OAuth 2.0 client registration information Description A ClientRegistration holds information about registration with an OAuth 2.0 authorization server or OpenID Provider. The configuration includes the client credentials that are used to authenticate to the identity provider. The client credentials can be included directly in the configuration, or retrieved in some other way using an expression, described in Expressions(5). Usage { "name": string, "type": "ClientRegistration", "config": { "clientId": expression, "clientSecret": expression, "issuer": Issuer reference, "registrationHandler": Handler reference, "scopes": [ expression, ...], "tokenEndpointUseBasicAuth": boolean } } Properties The client registration configuration object properties are as follows: "name": string, required A name for the client registration. "clientId": expression, required The client_id obtained when registering with the authorization server. See also Expressions(5). "clientSecret": expression, required The client_secret obtained when registering with the authorization server. See also Expressions(5). "issuer": Issuer reference, required The provider configuration to use for this client registration. Provide either the name of a Issuer object defined in the heap, or an inline Issuer configuration object. See also Issuer(5). "registrationHandler": Handler reference, optional Invoke this HTTP client handler to communicate with the authorization server. Provide either the name of a Handler object defined in the heap, or an inline Handler configuration object. Usually set this to the name of a ClientHandler configured in the heap, or a chain that ends in a ClientHandler. Default: OpenIG uses the default ClientHandler. See also Handlers, ClientHandler(5). "scopes": array of expressions, optional OAuth 2.0 scopes to use with this client registration. See also Expressions(5). "tokenEndpointUseBasicAuth": boolean, optional Whether to perform client authentication to the provider using HTTP Basic authentication when sending a request to the provider’s OAuth 2.0 token endpoint. When set to true, the client credentials are sent using HTTP Basic authentication as in the following example request: POST /oauth2/token HTTP/1.1 Host: as.example.com Authorization: Basic .... Content-Type: application/x-www-form-urlencoded grant_type=authorization_code&code=... When set to false, the client credentials are sent in HTTP POST form data as in the following example request: POST /oauth2/token HTTP/1.1 Host: as.example.com Content-Type: application/x-www-form-urlencoded grant_type=authorization_code&client_id=.....&client_secret=.....&code=... Some providers accept both authentication methods. For providers that strictly enforce how the client must authenticate, such as recent versions of OpenAM, you must align the configuration with that of the provider. If the provider does not support the configured authentication method, then according to RFC 6749 The OAuth 2.0 Authorization Framework the provider sends an HTTP 400 Bad Request response with an invalid_client error message as in the following example response: HTTP/1.1 400 Bad Request Content-Type: application/json;charset=UTF-8 Cache-Control: no-store Pragma: no-cache { "error":"invalid_client" } Default: true Example The following example shows a client registration for OpenAM. In this example client credentials are replaced with . In the actual configuration either include the credentials and protect the configuration file or obtain the credentials from the environment in a safe manner: { "name": "OpenIDConnectRelyingParty", "type": "ClientRegistration", "config": { "clientId": "**********", "clientSecret": "**********", "issuer": "openam", "redirect_uris": [ "https://openig.example.com:8443/openid/callback" ], "scopes": [ "openid", "profile" ] } } Javadoc org.forgerock.openig.filter.oauth2.client.ClientRegistration See Also Issuer(5), OAuth2ClientFilter(5) The OAuth 2.0 Authorization Framework OAuth 2.0 Bearer Token Usage OpenID Connect JwtSession — store sessions in encrypted JWT cookies Description A JwtSession object holds settings for storing session information in encrypted JSON Web Token (JWT) cookies. In this context, encrypted JWT cookie means an HTTP cookie whose value is an encrypted JWT. The payload of the encrypted JWT is a JSON representation of the session information. The JWT cookie lifetime is Session (not persistent), meaning the user-agent deletes the JWT cookie when it shuts down. When using this storage implementation, you must use data types for session information that can be mapped to JavaScript Object Notation (JSON). JSON allows strings, numbers, true, false, null, as well as arrays and JSON objects composed of the same primitives. Java and Groovy types that can be mapped include Java primitive types and null, String and CharSequence objects, as well as List and Map objects. As browser cookie storage capacity is limited to 4 KB, and encryption adds overhead, take care to limit the size of any JSON that you store. Rather than store larger data in the session information, consider storing a reference instead. When a request enters a route that uses a new session type, the scope of the session information becomes limited to the route. OpenIG builds a new session object and does not propagate any existing session information to the new object. session references the new session object. When the response then exits the route, the session object is closed, and serialized to a JWT cookie in this case, and session references the previous session object. Session information set inside the route is no longer available. An HTTP client that performs multiple requests in a session that modify the content of its session can encounter inconsistencies in the session information. This is because OpenIG does not share JwtSessions across threads. Instead, each thread has its own JwtSession objects that it modifies as necessary, writing its own session to the JWT cookie regardless of what other threads do. Usage { "name": string, "type": "JwtSession", "config": { "keystore": KeyStore reference, "alias": string, "password": configuration expression, "cookieName": string, "sessionTimeout": duration, "sharedSecret": string } } An alternative value for type is JwtSessionFactory. Properties "keystore": KeyStore reference, optional The keystore holding the key pair with the private key used to decrypt the JWT. Provide either the name of the KeyStore object defined in the heap, or the inline KeyStore configuration object inline. Default: When no keystore is specified, OpenIG generates a unique key pair, and stores the key pair in memory. With JWTs encrypted using a unique key pair generated at runtime, OpenIG cannot decrypt the JWTs after a restart, nor can it decrypt such JWTs encrypted by another OpenIG server. See also KeyStore(5). "alias": string, required when keystore is used Alias for the private key. "password": configuration expression, required when keystore is used The password to read the private key from the keystore. A configuration expression, described in Expressions(5) is independent of the request, response, and contexts, so do not use expressions that reference their properties. You can, however, use ${env['variable']}, ${system['property']}, and all the built-in functions listed in Functions(5). "cookieName" string, optional The name of the JWT cookie stored on the user-agent. Default: openig-jwt-session "sessionTimeout" duration, optional The amount of time before the cookie session expires. A duration is a lapse of time expressed in English, such as 23 hours 59 minutes and 59 seconds. Durations are not case sensitive. Negative durations are not supported. The following units can be used in durations: indefinite, infinity, undefined, unlimited: unlimited duration zero, disabled: zero-length duration days, day, d: days hours, hour, h: hours minutes, minute, min, m: minutes seconds, second, sec, s: seconds milliseconds, millisecond, millisec, millis, milli, ms: milliseconds microseconds, microsecond, microsec, micros, micro, us: microseconds nanoseconds, nanosecond, nanosec, nanos, nano, ns: nanoseconds Default: 30 minutes A zero duration for session timeout is not a valid setting. The maximum session timeout duration is 3650 days (approximately 10 years). If you set a longer duration, OpenIG truncates the duration to the maximum value. "sharedSecret" string, optional Specifies the key used to sign and verify the JWTs. This attribute is expected to be base-64 encoded. The minimum key size after base-64 decoding is 32 bytes/256 bits (HMAC-SHA-256 is used to sign JWTs). If the provided key is too short, an error message is created. If this attribute is not specified, random data is generated as the key, and the OpenIG instance can verify only the sessions it has created. Example The following example defines a JwtSession for storing session information in a JWT token cookie named OpenIG. The JWT is encrypted with a private key that is recovered using the alias private-key, and stored in the keystore. The password is both the password for the keystore and also the private key: { "name": "JwtSession", "type": "JwtSession", "config": { "keystore": { "type": "KeyStore", "config": { "url": "file://${env['HOME']}/keystore.jks", "password": "${system['keypass']}" } }, "alias": "private-key", "password": "${system['keypass']}", "cookieName": "OpenIG" } } Javadoc org.forgerock.openig.jwt.JwtSessionManager KeyManager — configure a Java Secure Socket Extension KeyManager Description This represents the configuration for a Java Secure Socket Extension KeyManager, which manages the keys used to authenticate an SSLSocket to a peer. The configuration references the keystore that actually holds the keys. Usage { "name": string, "type": "KeyManager", "config": { "keystore": KeyStore reference, "password": expression, "alg": string } } Properties "keystore": KeyStore reference, optional The keystore that references the store for the actual keys. Provide either the name of the KeyStore object defined in the heap, or the inline KeyStore configuration object inline. See also KeyStore(5). "password": expression, required The password to read private keys from the keystore. "alg" string, optional The certificate algorithm to use. Default: the default for the platform, such as SunX509. See also Expressions(5). Example The following example configures a key manager that depends on a KeyStore configuration. The keystore takes a password supplied as a Java system property when starting the container where OpenIG runs, as in -Dkeypass=password. This configuration uses the default certificate algorithm: { "name": "MyKeyManager", "type": "KeyManager", "config": { "keystore": { "type": "KeyStore", "config": { "url": "file://${env['HOME']}/keystore.jks", "password": "${system['keypass']}" } }, "password": "${system['keypass']}" } } Javadoc org.forgerock.openig.security.KeyManagerHeaplet See Also JSSE Reference Guide, KeyStore(5), TrustManager(5) KeyStore — configure a Java KeyStore Description This represents the configuration for a Java KeyStore, which stores cryptographic private keys and public key certificates. Usage { "name": name, "type": "KeyStore", "config": { "url": expression, "password": expression, "type": string } } Properties "url": expression, required URL to the keystore file. See also Expressions(5). "password": expression, optional The password to read private keys from the keystore. If the keystore is used as a truststore to store only public key certificates of peers and no password is required to do so, then you do not have to specify this field. Default: No password is set. See also Expressions(5). "type": string, optional The keystore format. Default: the default for the platform, such as JKS. Example The following example configures a keystore that references a Java Keystore file, $HOME/keystore.jks. The keystore takes a password supplied as a Java system property when starting the container where OpenIG runs, as in -Dkeypass=password. As the keystore file uses the default format, no type is specified: { "name": "MyKeyStore", "type": "KeyStore", "config": { "url": "file://${env['HOME']}/keystore.jks", "password": "${system['keypass']}" } } Javadoc org.forgerock.openig.security.KeyStoreHeaplet See Also JSSE Reference Guide, KeyManager(5), TrustManager(5) Issuer — Describe an Authorization Server or OpenID Provider Description An Issuer describes an OAuth 2.0 Authorization Server or an OpenID Provider that OpenIG can use as a OAuth 2.0 client or OpenID Connect relying party. An Issuer is generally referenced from a ClientRegistration, described in ClientRegistration(5). Usage { "name": string, "type": "Issuer", "config": { "wellKnownEndpoint": URL string, "authorizeEndpoint": URI expression, "registrationEndpoint": URI expression, "tokenEndpoint": URI expression, "userInfoEndpoint": URI expression, "issuerHandler": Handler reference, "supportedDomains": [ domain pattern, ... ] } } Properties If the provider has a well-known configuration URL as defined for OpenID Connect 1.0 Discovery that returns JSON with at least authorization and token endpoint URLs, then you can specify that URL in the provider configuration. Otherwise, you must specify at least the provider authorization and token endpoint URLs, and optionally the registration endpoint and user info endpoint URLs. The provider configuration object properties are as follows: "name": string, required A name for the provider configuration. "wellKnownEndpoint": URL string, required unless authorizeEndpoint and tokenEndpoint are specified The URL to the well-known configuration resource as described in OpenID Connect 1.0 Discovery. "authorizeEndpoint": expression, required unless obtained through wellKnownEndpoint The URL to the provider’s OAuth 2.0 authorization endpoint. See also Expressions(5). "registrationEndpoint": expression, optional The URL to the provider’s OpenID Connect dynamic registration endpoint. See also Expressions(5). "tokenEndpoint": expression, required unless obtained through wellKnownEndpoint The URL to the provider’s OAuth 2.0 token endpoint. See also Expressions(5). "userInfoEndpoint": expression, optional The URL to the provider’s OpenID Connect UserInfo endpoint. Default: no UserInfo is obtained from the provider. See also Expressions(5). "issuerHandler": Handler reference, optional Invoke this HTTP client handler to communicate with the authorization server. Provide either the name of a Handler object defined in the heap, or an inline Handler configuration object. Usually set this to the name of a ClientHandler configured in the heap, or a chain that ends in a ClientHandler. Default: OpenIG uses the default ClientHandler. See also Handlers, ClientHandler(5). "supportedDomains": array of patterns, optional List of patterns matching domain names handled by this issuer, used as a shortcut for OpenID Connect discovery before performing OpenID Connect dynamic registration. In summary when the OpenID Provider is not known in advance, it might be possible to discover the OpenID Provider Issuer based on information provided by the user, such as an email address. The OpenID Connect discovery specification explains how to use WebFinger to discover the issuer. OpenIG can discover the issuer in this way. As a shortcut OpenIG can also use supported domains lists to find issuers already described in the OpenIG configuration. To use this shortcut, OpenIG extracts the domain from the user input, and looks for an issuer whose supported domains list contains a match. Supported domains patterns match host names with optional port numbers. Do not specify a URI scheme such as HTTP. OpenIG adds the scheme. For instance, *.example.com matches any host in the example.com domain. You can specify the port number as well as in host.example.com:8443. Patterns must be valid regular expression patterns according to the rules for the Java Pattern class. Examples The following example shows an OpenAM issuer configuration for OpenAM. OpenAM exposes a well-known endpoint for the provider configuration, but this example demonstrates use of the other fields: { "name": "openam", "type": "Issuer", "config": { "authorizeEndpoint": "https://openam.example.com:8443/openam/oauth2/authorize", "registration_endpoint": "https://openam.example.com:8443/openam/oauth2/connect/register", "tokenEndpoint": "https://openam.example.com:8443/openam/oauth2/access_token", "userInfoEndpoint": "https://openam.example.com:8443/openam/oauth2/userinfo", "supportedDomains": [ "mail.example.*", "docs.example.com:8443" ] } } The following example shows an issuer configuration for Google: { "name": "google", "type": "Issuer", "config": { "wellKnownEndpoint": "https://accounts.google.com/.well-known/openid-configuration", "supportedDomains": [ "gmail.*", "googlemail.com:8052" ] } } Javadoc org.forgerock.openig.filter.oauth2.client.Issuer ScheduledExecutorService — schedule the execution of tasks Description An executor service to schedule tasks for execution after a delay or for repeated execution with a fixed interval of time in between each execution. You can configure the number of threads in the executor service and how the executor service is stopped. The ScheduledExecutorService is shared by all downstream components that use an executor service. Usage { "name": string, "type": "ScheduledExecutorService", "config": { "corePoolSize”: integer or expression<integer>, "gracefulStop": boolean or expression<boolean>, "gracePeriod" : duration string or expression<duration string> } } Properties "corePoolSize": integer or expression<integer>, optional The minimum number of threads to keep in the pool. If this property is an expression, the expression is evaluated as soon as the configuration is read. The value must be an integer greater than zero. Default: 1 "gracefulStop": boolean or expression<boolean> , optional Defines how the executor service stops. If this property is an expression, the expression is evaluated as soon as the configuration is read. If true, the executor service does the following: Blocks the submission of new jobs. Allows running jobs to continue. If a grace period is defined, waits for up to that maximum time for running jobs to finish before it stops. If false, the executor service does the following: Blocks the submission of new jobs. Removes submitted jobs without running them. Attempts to end running jobs. If a grace period is defined, ignores it. Default: true "gracePeriod": duration string or expression<duration string>, optional The maximum time that the executor service waits for running jobs to finish before it stops. If this property is an expression, the expression is evaluated as soon as the configuration is read. If all jobs finish before the grace period, the executor service stops without waiting any longer. If jobs are still running after the grace period, the executor service stops anyway and prints a message. When gracefulStop is false, the grace period is ignored. A duration is a lapse of time expressed in English, such as 23 hours 59 minutes and 59 seconds. Durations are not case sensitive. Negative durations are not supported. The following units can be used in durations: indefinite, infinity, undefined, unlimited: unlimited duration zero, disabled: zero-length duration days, day, d: days hours, hour, h: hours minutes, minute, min, m: minutes seconds, second, sec, s: seconds milliseconds, millisecond, millisec, millis, milli, ms: milliseconds microseconds, microsecond, microsec, micros, micro, us: microseconds nanoseconds, nanosecond, nanosec, nanos, nano, ns: nanoseconds Default: 10 seconds Example The following example creates a thread pool to execute tasks. When the executor service is instructed to stop, it blocks the submission of new jobs, and waits for up to 10 seconds for submitted and running jobs to complete before it stops. If any jobs are still submitted or running after 10 seconds, the executor service stops anyway and prints a message. { "name": "ExecutorService", "comment": "Default service for executing tasks in the background.", "type": "ScheduledExecutorService", "config": { "corePoolSize": 5, "gracefulStop": true, "gracePeriod": "10 seconds" } } Javadoc org.forgerock.openig.thread.ScheduledExecutorServiceHeaplet TemporaryStorage — cache streamed content Description Allocates temporary buffers for caching streamed content during request processing. Initially uses memory; when the memory limit is exceeded, switches to a temporary file. Usage { "name": string, "type": "TemporaryStorage", "config": { "initialLength": number, "memoryLimit": number, "fileLimit": number, "directory": string } } Properties "initialLength": number, optional The initial length of memory buffer byte array. Default: 8192 (8 KiB). "memoryLimit": number, optional The length limit of the memory buffer. Exceeding this limit results in promotion from memory to file. Default: 65536 (64 KiB). "fileLimit": number, optional The length limit of the file buffer. Exceeding this limit results in a thrown exception. Default: 1048576 (1 MiB). "directory": string, optional The directory where temporary files are created. If omitted, then the system-dependent default temporary directory is used (typically "/tmp" on Unix systems). Default: use system-dependent default. Javadoc org.forgerock.openig.io.TemporaryStorage TrustManager — configure a Java Secure Socket Extension TrustManager Description This represents the configuration for a Java Secure Socket Extension TrustManager, which manages the trust material (typically X.509 public key certificates) used to decide whether to accept the credentials presented by a peer. The configuration references the keystore that actually holds the trust material. Usage { "name": string, "type": "TrustManager", "config": { "keystore": KeyStore reference, "alg": string } } Properties "keystore": KeyStore reference, optional The KeyStore that references the store for public key certificates. Provide either the name of the KeyStore object defined in the heap, or the inline KeyStore configuration object inline. See also KeyStore(5). "alg" string, optional The certificate algorithm to use. Default: the default for the platform, such as SunX509. Example The following example configures a trust manager that depends on a KeyStore configuration. This configuration uses the default certificate algorithm: { "name": "MyTrustManager", "type": "TrustManager", "config": { "keystore": { "type": "KeyStore", "config": { "url": "file://${env['HOME']}/keystore.jks", "password": "${system['keypass']}" } } } } Javadoc org.forgerock.openig.security.TrustManagerHeaplet See Also JSSE Reference Guide, KeyManager(5), KeyStore(5) TrustAllManager — a TrustManager that blindly trusts all servers Description The TrustAllManager blindly trusts all server certificates presented the servers for protected applications. It can be used instead of a TrustManager(5) in test environments to trust server certificates that were not signed by a well-known CA, such as self-signed certificates. The TrustAllManager is not safe for production use. Use a properly configured TrustManager(5) instead. Usage { "name": string, "type": "TrustAllManager" } Example The following example configures a client handler that blindly trusts server certificates when OpenIG connects to servers over HTTPS: { "name": "BlindTrustClientHandler", "type": "ClientHandler", "config": { "trustManager": { "type": "TrustAllManager" } } } Javadoc org.forgerock.openig.security.TrustAllManager UmaService — represent an UMA resource server configuration Description An UmaService represents a User-Managed Access (UMA) resource server. Each service is statically registered as an OAuth 2.0 client of a single UMA authorization server. The UmaService includes a list of resource patterns and associated actions that define the scopes for permissions to matching resources. When creating a share using the REST API described below, you specify a path matching a pattern in a resource of the UmaService. Usage { "type": "UmaService", "config": { "protectionApiHandler": Handler reference, "authorizationServerUri": URI string, "clientId": expression, "clientSecret": expression, "resources": [ resource, ... ] } } Properties "protectionApiHandler": Handler reference, required The handler to use when interacting with the UMA authorization server to manage resource sets, such as a ClientHandler capable of making an HTTPS connection to the server. For details, see Handlers. "authorizationServerUri": URI string, required The URI to the UMA authorization server. "clientId": expression, required An expression that evaluates to the OAuth 2.0 client_id registered with the UMA authorization server. "clientSecret": expression, required An expression that evaluates to the OAuth 2.0 client_secret registered with the UMA authorization server. "resources": array of resources, required Resource objects matching the resources the resource owner wants to share. Each resource object has the following form: { "pattern": resource pattern, "actions": [ { "scopes": [ scope string, ... ], "condition": boolean expression }, { ... } ] } Each resource pattern can be seen to represent an application, or a consistent set of endpoints that share scope definitions. The actions map each request to the associated scopes. This configuration serves to set the list of scopes in the following ways: When registering a resource set, OpenIG uses the list of actions to provide the aggregated, exhaustive list of all scopes that can be used. When responding to an initial request for a resource, OpenIG derives the scopes for the ticket based on the scopes that apply according to the request. When verifying the RPT, OpenIG checks that all required scopes are encoded in the RPT. A description of each field follows: "pattern": resource pattern, required A pattern matching resources to be shared by the resource owner, such as . to match any resource path, and /photos/. to match paths starting with /photos/. See also Patterns(5). "actions": array of action objects, optional A set of actions on matching resources that the resource owner can authorize. When granting permission, the resource owner specifies the action scope. Conditions specify what the scopes mean in concrete terms. A given scope matches a requesting party operation when the corresponding condition evaluates to true. "scopes": array of scope strings, optional Scope strings to identify permissions. For example, #read (read access on a resource). "condition": boolean expression, required A boolean expression representing the meaning of a scope. For example, ${request.method == 'GET'} (true when reading a resource). See also Expressions(5). The REST API for Shares The REST API for UMA shares is exposed at a registered endpoint. OpenIG logs the paths to registered endpoints when the log level is INFO or finer. Look for messages such as the following in the log: UMA Share endpoint available at '/openig/api/system/objects/router-handler/routes/00-uma/objects/umaservice/share' To access the endpoint over HTTP or HTTPS, prefix the path with the OpenIG scheme, host, and port to obtain a full URL, such as http://localhost:8080/openig/api/system/objects/router-handler/routes/00-uma/objects/umaservice/share. The UMA REST API supports create (POST only), read, delete, and query (_queryFilter=true only). For an introduction to common REST APIs, see About ForgeRock Common REST. In the present implementation, OpenIG does not have a mechanism for persisting shares. When the OpenIG container stops, the shares are discarded. A share object has the following form: { "path": pattern, "pat": UMA protection API token (PAT) string, "id": unique identifier string, "resource_set_id": unique identifier string, "user_access_policy_uri": URI string } The fields are as follows: "path": pattern, required A pattern matching the path to protected resources, such as /photos/.*. This pattern must match a pattern defined in the UmaService for this API. See also Patterns(5). "pat": PAT string, required A PAT granted by the UMA authorization server given consent by the resource owner. In the present implementation, OpenIG has access only to the PAT, not to any refresh tokens. "id": unique identifier string, read-only This uniquely identifies the share. This value is set by the service when the share is created, and can be used when reading or deleting a share. "resource_set_id": unique identifier string, read-only This uniquely identifies the UMA resource set registered with the authorization server. This value is obtained by the service when the resource set is registered, and can be used when setting access policy permissions. "user_access_policy_uri": URI string, read-only This URI indicates the location on the UMA authorization server where the resource owner can set or modify access policies. This value is obtained by the service when the resource set is registered. See Also User-Managed Access (UMA) Profile of OAuth 2.0 org.forgerock.openig.uma.UmaSharingService Throttling Filters and Policies Expressions