RESTSecurityTokenServices
Realm Operations
The REST STS endpoint is responsible for storing the configuration of instances of REST Security Token Services (STS). Available operations are create, read, update, delete, query, schema and template.
Resource path:
/realm-config/services/sts/rest-sts
Resource version: 1.0
create
Usage
am> create RESTSecurityTokenServices --realm Realm --id id --body body
Parameters
- --id
-
The unique identifier for the resource.
- --body
-
The resource in JSON format, described by the following JSON schema:
{ "type" : "object", "properties" : { "restStsDeployment" : { "type" : "object", "title" : "Deployment", "propertyOrder" : 1, "properties" : { "deployment-auth-target-mappings" : { "title" : "Authentication Target Mappings", "description" : "Configuration of consumption of OpenAM's rest-authN. For each validated token type (other than OpenAM), the REST authN elements which will validate token instances. <br>Entry format: <code>TokenType;authIndexType;authIndexValue;context_key=context_value,context_key1=context_value1</code>. <br>The <code>context_key=context_value</code> entries are optional.<br><br>Each deployed STS is configured with the authentication targets for each input token type for each supported token transformation. For example, if the transformation OPENIDCONNECT->SAML2 is supported, the STS instance must be configured with information specifying which elements of the OpenAM restful authentication context needs to be consumed to validate the OPENIDCONNECT token. The elements of the configuration tuple are separated by '|'. <br>The first element is the input token type in the token transform: i.e. X509, OPENIDCONNECT, USERNAME, or OPENAM. The second element is the authentication target - i.e. either 'module' or 'service', and the third element is the name of the authentication module or service. The fourth (optional) element provides the STS authentication context information about the to-be-consumed authentication context. <br>When transforming OpenID Connect Id tokens, the OpenID Connect authentication module must be consumed, and thus a deployed rest-sts instance must be configured with the name of the header/cookie element where the OpenID Connect Id token will be placed. For this example, the following string would define these configurations: <code>OPENIDCONNECT|module|oidc|oidc_id_token_auth_target_header_key=oidc_id_token</code>. In this case, 'oidc' is the name of the OpenID Connect authentication module created to authenticate OpenID Connect tokens. <br>When transforming a X509 Certificate, the Certificate module must be consumed, and the published rest-sts instance must be configured with the name of the Certificate module (or the service containing the module), and the header name configured for the Certificate module corresponding to where the Certificate module can expect to find the to-be-validated Certificate. The following string would define these configurations: <code>X509|module|cert_module|x509_token_auth_target_header_key=client_cert</code>. In this case 'cert_module' is the name of the Certificate module, and client_cert is the header name where Certificate module has been configured to find the client's Certificate.", "propertyOrder" : 800, "required" : true, "items" : { "type" : "string" }, "minItems" : 1, "type" : "array", "exampleValue" : "" }, "deployment-offloaded-two-way-tls-header-key" : { "title" : "Client Certificate Header Key", "description" : "TLS-offload host certificate header key<br><br>Token transformation which take X509 Certificates as the input token require that the X509 Certificate be presented via two-way TLS, so that the TLS handshake can validate client certificate ownership. A standard means of obtaining the client certificate presented via two-way TLS is via the javax.servlet.request.X509Certificate attribute in the ServletRequest. However, in TLS-offloaded deployments, the TLS-offloader must communicate the client certificate to its ultimate destination via an Http header. If this rest-sts instance is to support token transformations with X509 Certificate input, and OpenAM will be deployed in a TLS-offloaded context, then this value must be set to the header value which the TLS-offloading engine will use to set client certificates presented via the TLS handshake.", "propertyOrder" : 900, "required" : false, "type" : "string", "exampleValue" : "" }, "deployment-tls-offload-engine-hosts" : { "title" : "Trusted Remote Hosts", "description" : "IP addresses of TLS-Offload Hosts<br><br>Token transformation which take X509 Certificates as the input token require that the X509 Certificate be presented via two-way TLS, so that the TLS handshake can validate client certificate ownership. If OpenAM is deployed in a TLS-offloaded environment, in which the TLS-offloader must communicate the client certificate to the rest-sts via an Http header, this certificate will only be accepted if the ip address(es) of the TLS-offload engines are specified in this list. Specify 'any' if a client certificate can be presented in the specified header by any rest-sts client.", "propertyOrder" : 1000, "required" : false, "items" : { "type" : "string" }, "type" : "array", "exampleValue" : "" } } }, "restStsSaml2" : { "type" : "object", "title" : "SAML2 Token", "propertyOrder" : 2, "properties" : { "saml2-encrypt-attributes" : { "title" : "Encrypt Attributes", "description" : "Check this box if the assertion Attributes should be encrypted. If this box is checked, the Encrypt Assertion box cannot be checked.", "propertyOrder" : 2600, "required" : false, "type" : "boolean", "exampleValue" : "" }, "saml2-custom-subject-provider-class-name" : { "title" : "Customs Subject Provider Class Name", "description" : "If the Subject of the issued SAML2 assertion needs to be customized, implement the <code>org.forgerock.openam.sts.tokengeneration.saml2.statements.SubjectProvider</code> interface, and specify the class name of the implementation here.", "propertyOrder" : 1700, "required" : false, "type" : "string", "exampleValue" : "" }, "issuer-name" : { "title" : "The SAML2 Issuer Id", "description" : "The name of the issuer<br><br>This name will appear in some issued tokens - e.g. in the <code>saml:Issuer</code> of issued SAML2 assertions.", "propertyOrder" : 1100, "required" : true, "type" : "string", "exampleValue" : "" }, "saml2-custom-authz-decision-statements-provider-class-name" : { "title" : "Custom Authorization Decision Statements Class Name", "description" : "If the AuthorizationDecisionStatements of the issued SAML2 assertion need to be customized, implement the <code>org.forgerock.openam.sts.tokengeneration.saml2.statements.AuthzDecisionStatementsProvider</code> interface, and specify the class name of the implementation here.", "propertyOrder" : 2000, "required" : false, "type" : "string", "exampleValue" : "" }, "saml2-encryption-key-alias" : { "title" : "Encryption Key Alias", "description" : "This alias corresponds to the SP's x509 Certificate identified by the SP Entity ID for this rest-sts instance. Not necessary unless assertions are to be encrypted.", "propertyOrder" : 3200, "required" : false, "type" : "string", "exampleValue" : "" }, "saml2-sp-acs-url" : { "title" : "Service Provider Assertion Consumer Service Url", "description" : "When issuing bearer assertions, the recipient attribute of the SubjectConfirmation element must be set to the Service Provider Assertion Consumer Service Url. See section 4.1.4.2 of Profiles for the OASIS Security Assertion Markup Language (SAML) V2.0 for details. Value required when issuing Bearer assertions.", "propertyOrder" : 1300, "required" : false, "type" : "string", "exampleValue" : "" }, "saml2-encryption-algorithm-strength" : { "title" : "Encryption Algorithm Strength", "description" : "", "propertyOrder" : 2850, "required" : false, "type" : "integer", "exampleValue" : "" }, "saml2-custom-conditions-provider-class-name" : { "title" : "Custom Conditions Provider Class Name", "description" : "If the Conditions of the issued SAML2 assertion need to be customized, implement the <code>org.forgerock.openam.sts.tokengeneration.saml2.statements.ConditionsProvider</code> interface, and specify the class name of the implementation here.", "propertyOrder" : 1600, "required" : false, "type" : "string", "exampleValue" : "" }, "saml2-encrypt-nameid" : { "title" : "Encrypt NameID", "description" : "Check this box if the assertion NameID should be encrypted. If this box is checked, the Encrypt Assertion box cannot be checked.", "propertyOrder" : 2700, "required" : false, "type" : "boolean", "exampleValue" : "" }, "saml2-attribute-map" : { "title" : "Attribute Mappings", "description" : "Contains the mapping of assertion attribute names (Map keys) to local OpenAM attributes (Map values) in configured data stores. Format: <code>assertion_attr_name=ldap_attr_name</code><br><br>The DefaultAttributeMapper looks at profile attributes in configured data stores, or in Session properties. The keys will define the name of the attributes included in the Assertion Attribute statements, and the data pulled from the subject's directory entry or session state corresponding to the map value will define the value corresponding to this attribute name. The keys can have the format <code>[NameFomatURI|]SAML ATTRIBUTE NAME</code>. If the attribute value is enclosed in quotes, that quoted value will be included in the attribute without mapping. Binary attributes should be followed by ';binary'. <br>Examples: <ul><li>EmailAddress=mail</li><li>Address=postaladdress</li><li>urn:oasis:names:tc:SAML:2.0:attrname-format:uri|urn:mace:dir:attribute-def:cn=cn</li><li>partnerID=\"staticPartnerIDValue\"</li><li>urn:oasis:names:tc:SAML:2.0:attrname-format:uri|nameID=\"staticNameIDValue\"</li><li>photo=photo;binary</li><li>urn:oasis:names:tc:SAML:2.0:attrname-format:uri|photo=photo;binary</li></ul>", "propertyOrder" : 2300, "required" : false, "patternProperties" : { ".*" : { "type" : "string" } }, "type" : "object", "exampleValue" : "" }, "saml2-keystore-filename" : { "title" : "KeystorePath", "description" : "Path to keystore<br><br>Provide either the full filesystem path to a filesystem resident keystore, or a classpath-relative path to a keystore bundled in the OpenAM .war file. This keystore contains the IdP public/private keys and SP public key for signed and/or encrypted assertions. If assertions are neither signed nor encrypted, these values need not be specified.", "propertyOrder" : 2900, "required" : false, "type" : "string", "exampleValue" : "" }, "saml2-custom-attribute-mapper-class-name" : { "title" : "Custom Attribute Mapper Class Name", "description" : "If the class implementing attribute mapping for attributes contained in the issued SAML2 assertion needs to be customized, implement the <code>org.forgerock.openam.sts.tokengeneration.saml2.statements.AttributeMapper</code> interface, and specify the class name of the implementation here.", "propertyOrder" : 2100, "required" : false, "type" : "string", "exampleValue" : "" }, "saml2-token-lifetime-seconds" : { "title" : "Token Lifetime (Seconds)", "description" : "Set to over-ride the default of 600 (10 minutes).", "propertyOrder" : 1500, "required" : false, "type" : "integer", "exampleValue" : "" }, "saml2-custom-attribute-statements-provider-class-name" : { "title" : "Custom AttributeStatements Class Name", "description" : "If the AttributeStatements of the issued SAML2 assertion need to be customized, implement the <code>org.forgerock.openam.sts.tokengeneration.saml2.statements.AttributeStatementsProvider</code> interface, and specify the class name of the implementation here.", "propertyOrder" : 1900, "required" : false, "type" : "string", "exampleValue" : "" }, "saml2-custom-authentication-statements-provider-class-name" : { "title" : "Custom AuthenticationStatements Class Name", "description" : "If the AuthenticationStatements of the issued SAML2 assertion need to be customized, implement the <code>org.forgerock.openam.sts.tokengeneration.saml2.statements.AuthenticationStatementsProvider</code> interface, and specify the class name of the implementation here.", "propertyOrder" : 1800, "required" : false, "type" : "string", "exampleValue" : "" }, "saml2-name-id-format" : { "title" : "NameIdFormat", "description" : "The default value is <code>urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified</code><br><br>See section 8.3 of <a href=\"http://docs.oasis-open.org/security/saml/v2.0/saml-core-2.0-os.pdf\" target=\"_blank\">Assertions and Protocols for the OASIS Security Assertion Markup Language (SAML) V2.0</a> for details on possible values.", "propertyOrder" : 1400, "required" : true, "type" : "string", "exampleValue" : "" }, "saml2-encrypt-assertion" : { "title" : "Encrypt Assertion", "description" : "Check this box if the entire assertion should be encrypted. If this box is checked, the Encrypt NameID and Encrypt Attributes boxes cannot be checked.", "propertyOrder" : 2500, "required" : false, "type" : "boolean", "exampleValue" : "" }, "saml2-signature-key-alias" : { "title" : "Signature Key Alias", "description" : "Corresponds to the private key of the IdP. Will be used to sign assertions. Value can remain unspecified unless assertions are signed.", "propertyOrder" : 3300, "required" : false, "type" : "string", "exampleValue" : "" }, "saml2-encryption-algorithm" : { "title" : "Encryption Algorithm", "description" : "Algorithm used to encrypt generated assertions.", "propertyOrder" : 2800, "required" : false, "type" : "string", "exampleValue" : "" }, "saml2-key-transport-algorithm" : { "title" : "Key Transport Algorithm", "description" : "This setting controls the encryption algorithm used to encrypt the symmetric encryption key when SAML2 token encryption is enabled. Valid values include: <pre>http://www.w3.org/2001/04/xmlenc#rsa-1_5</pre>, <pre>http://www.w3.org/2001/04/xmlenc#rsa-oaep-mgf1p</pre>, and <pre>http://www.w3.org/2009/xmlenc11#rsa-oaep</pre>", "propertyOrder" : 2860, "required" : false, "type" : "string", "exampleValue" : "" }, "saml2-sign-assertion" : { "title" : "Sign Assertion", "description" : "", "propertyOrder" : 2400, "required" : false, "type" : "boolean", "exampleValue" : "" }, "saml2-sp-entity-id" : { "title" : "Service Provider Entity Id", "description" : "Values will be used to populate the Audiences of the AudienceRestriction element of the Conditions element. This value is required when issuing Bearer assertions. See section 4.1.4.2 of Profiles for the OASIS Security Assertion Markup Language (SAML) V2.0 for details.", "propertyOrder" : 1200, "required" : true, "type" : "string", "exampleValue" : "" }, "saml2-keystore-password" : { "title" : "Keystore Password", "description" : "", "propertyOrder" : 3000, "required" : false, "type" : "string", "format" : "password", "exampleValue" : "" }, "saml2-signature-key-password" : { "title" : "Signature Key Password", "description" : "", "propertyOrder" : 3400, "required" : false, "type" : "string", "format" : "password", "exampleValue" : "" }, "saml2-custom-authn-context-mapper-class-name" : { "title" : "Custom Authentication Context Class Name", "description" : "If the AuthnContext mapping implemented by the <code>org.forgerock.openam.sts.rest.token.provider.saml.DefaultSaml2JsonTokenAuthnContextMapper</code> class needs to be customized, implement the <code>org.forgerock.openam.sts.rest.token.provider.saml.Saml2JsonTokenAuthnContextMapper</code> interface, and specify the name of the implementation here.", "propertyOrder" : 2200, "required" : false, "type" : "string", "exampleValue" : "" } } }, "restStsGeneral" : { "type" : "object", "title" : "General", "propertyOrder" : 0, "properties" : { "custom-token-transforms" : { "title" : "Custom Token Transforms", "description" : "If either custom token validators or providers are specified, they must also be specified in a custom rest-sts token transformation. These input or output tokens can be specified in a transformation with standard, or other custom, tokens.<br><br>The format of these token transformation definitions is the same as the standard token transformation definitions. The first field defines the input token type, the second the output token type, and the third field specifies whether the OpenAM session, produced as part of the validation of the input token type, is invalidated following the production of the output token. <br><br>Example 1:<code> MY_CUSTOM_INPUT_TOKEN|SAML2|true</code> <br>Example 1 specifies a MY_CUSTOM_INPUT_TOKEN as the input token (requires the specification of a custom token validator) SAML2 as the produced token, and that the interim OpenAM Session should be invalidated after the SAML2 token is produced. <br><br>Example 2: <code>OPENIDCONNECT|MY_CUSTOM_OUTPUT_TOKEN|true</code> <br>Example 2 specifies that an OPENIDCONNECT token should be authenticated to assert the identity of a token of type MY_CUSTOM_OUTPUT_TOKEN (requires the specification of a custom token provider) and that the interim OpenAM Session should be invalidated. <br><br>Example 3: <code>MY_CUSTOM_INPUT_TOKEN|MY_CUSTOM_OUTPUT_TOKEN|false</code> <br>Example 3 specifies that a MY_CUSTOM_INPUT_TOKEN should be transformed into a MY_CUSTOM_OUTPUT_TOKEN (requires the specification of both a custom provider and a custom validator), and that the interim OpenAM session should not be invalidated.", "propertyOrder" : 500, "required" : false, "items" : { "type" : "string" }, "type" : "array", "exampleValue" : "" }, "is-remote-sts-instance" : { "title" : "STS Instance is running as remote instance", "description" : "When true, STS instance will assume it's running on the remote Java process separate from AM server.", "propertyOrder" : 5200, "required" : false, "type" : "boolean", "exampleValue" : "" }, "custom-token-validators" : { "title" : "Custom Token Validators", "description" : "If validator of a custom token type is desired, specify the name of the custom token here, followed by '|', followed by the class name of the <code>org.forgerock.openam.sts.rest.token.validator.RestTokenTransformValidator</code> implementation which will be invoked to validate the custom tokens.<br><br>Example: <code>MY_CUSTOM_INPUT_TOKEN|org.mycompany.tokens.MyCustomTokenValidator</code> <br>Note that MY_CUSTOM_INPUT_TOKEN would then be specified as the value corresponding to the token_type key in the input_token_state json object specified in rest-sts token transformation invocations.", "propertyOrder" : 300, "required" : false, "items" : { "type" : "string" }, "type" : "array", "exampleValue" : "" }, "supported-token-transforms" : { "title" : "Supported Token Transformations", "description" : "Entry format:<code>input_token_type;output_token_type;{true|false}</code>, where true|false indicates whether the interim OpenAM session is invalidated following token issuance.<br><br>Example: for the transform <code>USERNAME:SAML2</code>, it is likely that the OpenAM session generated as part of validating the USERNAME token should be invalidated, and thus the config entry would be <code>USERNAME;SAML2;true</code>. If this value is false, each USERNAME->SAML2 transformation will result in a 'left-over' OpenAM session. Note that currently, any transformation which starts with an OPENAM session, e.g. <code>OPENAM;SAML2</code>, will not invalidate this OPENAM session, as it was not created as part of the token transformation.", "propertyOrder" : 200, "required" : true, "items" : { "type" : "string" }, "minItems" : 1, "type" : "array", "exampleValue" : "" }, "custom-token-providers" : { "title" : "Custom Token Providers", "description" : "If a rest-sts instance is to produce a custom token, specify the name of the custom token here, followed by '|', followed by the class name of the <code>org.forgerock.openam.sts.rest.token.provider.RestTokenProvider</code> implementation which will be invoked to produce an instance of the custom token.<br><br>Example: <code>MY_CUSTOM_OUTPUT_TOKEN|org.mycompany.tokens.MyCustomTokenProvider</code> <br>Note that MY_CUSTOM_OUTPUT_TOKEN would then be specified as the value corresponding to the token_type key in the output_token_state json object specified in rest-sts token transformation invocations.", "propertyOrder" : 400, "required" : false, "items" : { "type" : "string" }, "type" : "array", "exampleValue" : "" }, "persist-issued-tokens-in-cts" : { "title" : "Persist Issued Tokens in Core Token Store", "description" : "Necessary to support token validation and cancellation<br><br>Validation of STS-issued tokens will involve determining whether the token has been issued, has not expired, and has not been cancelled. Token cancellation involves removing the record of this token from the CTS. Thus CTS persistence of STS-issued tokens is required to support these features.", "propertyOrder" : 100, "required" : false, "type" : "boolean", "exampleValue" : "" } } }, "restStsOidc" : { "type" : "object", "title" : "OpenID Connect Token", "propertyOrder" : 3, "properties" : { "oidc-custom-claim-mapper-class" : { "title" : "Custom Claim Mapper Class", "description" : "If the class implementing attribute mapping for attributes contained in issued OpenID Connect tokens needs to be customized, implement the <code>org.forgerock.openam.sts.tokengeneration.oidc.OpenIdConnectTokenClaimMapper</code> interface, and specify the class name of the implementation here.", "propertyOrder" : 4900, "required" : false, "type" : "string", "exampleValue" : "" }, "oidc-signature-key-alias" : { "title" : "KeyStore Signing Key Alias", "description" : "", "propertyOrder" : 4100, "required" : true, "type" : "string", "exampleValue" : "" }, "oidc-authorized-party" : { "title" : "Authorized Party", "description" : "", "propertyOrder" : 4700, "required" : false, "type" : "string", "exampleValue" : "" }, "oidc-custom-authn-method-references-mapper-class" : { "title" : "Custom Authn Methods References Mapper Class", "description" : "If issued OIDC tokens are to contain amr claims, implement the <code>org.forgerock.openam.sts.rest.token.provider.oidc.OpenIdConnectTokenAuthMethodReferencesMapper</code> interface, and specify the class name of the implementation here.", "propertyOrder" : 5100, "required" : false, "type" : "string", "exampleValue" : "" }, "oidc-public-key-reference-type" : { "title" : "Public Key Reference Type", "description" : "For tokens signed with RSA, how should corresponding public key be referenced in the issued jwt", "propertyOrder" : 3700, "required" : false, "type" : "string", "exampleValue" : "" }, "oidc-issuer" : { "title" : "The OpenID Connect Token Provider Issuer Id", "description" : "", "propertyOrder" : 3450, "required" : true, "type" : "string", "exampleValue" : "" }, "oidc-claim-map" : { "title" : "Claim Map", "description" : "Contains the mapping of OIDC token claim names (Map keys) to local OpenAM attributes (Map values) in configured data stores. Format: <code>claim_name=attribute_name</code><br><br>The keys in the map will be claim entries in the issued OIDC token, and the value of these claims will be the principal attribute state resulting from LDAP datastore lookup of the map values. If no values are returned from the LDAP datastore lookup of the attribute corresponding to the map value, no claim will be set in the issued OIDC token.", "propertyOrder" : 4800, "required" : false, "patternProperties" : { ".*" : { "type" : "string" } }, "type" : "object", "exampleValue" : "" }, "oidc-audience" : { "title" : "Issued Tokens Audience", "description" : "Contents will be set in the aud claim", "propertyOrder" : 4600, "required" : true, "items" : { "type" : "string" }, "type" : "array", "exampleValue" : "" }, "oidc-signature-algorithm" : { "title" : "Token Signature Algorithm", "description" : "Algorithm used to sign issued OIDC tokens", "propertyOrder" : 3600, "required" : true, "type" : "string", "exampleValue" : "" }, "oidc-client-secret" : { "title" : "Client Secret", "description" : "For HMAC-signed tokens, the client secret used as the HMAC key.<br><br>For HMAC-signed tokens, the KeyStore location, password, signature key alias and password configurations are not required.", "propertyOrder" : 4400, "required" : true, "type" : "string", "format" : "password", "exampleValue" : "" }, "oidc-keystore-password" : { "title" : "KeyStore Password", "description" : "", "propertyOrder" : 3900, "required" : true, "type" : "string", "format" : "password", "exampleValue" : "" }, "oidc-token-lifetime-seconds" : { "title" : "Token Lifetime (Seconds)", "description" : "", "propertyOrder" : 3500, "required" : false, "type" : "integer", "exampleValue" : "" }, "oidc-custom-authn-context-mapper-class" : { "title" : "Custom Authn Context Mapper Class", "description" : "If issued OIDC tokens are to contain acr claims, implement the <code>org.forgerock.openam.sts.rest.token.provider.oidc.OpenIdConnectTokenAuthnContextMapper</code> interface, and specify the class name of the implementation here.", "propertyOrder" : 5000, "required" : false, "type" : "string", "exampleValue" : "" }, "oidc-keystore-location" : { "title" : "KeyStore Location", "description" : "For RSA-signed tokens, the filesystem or classpath location of the KeyStore containing signing key entry<br><br>For RSA-signed tokens, the KeyStore location, password, signing-key alias, and signing key password must be specified. The client secret is not required for RSA-signed tokens.", "propertyOrder" : 3800, "required" : true, "type" : "string", "exampleValue" : "" }, "oidc-signature-key-password" : { "title" : "Signature Key Password", "description" : "", "propertyOrder" : 4200, "required" : true, "type" : "string", "format" : "password", "exampleValue" : "" } } } } }
delete
Usage
am> delete RESTSecurityTokenServices --realm Realm --id id
Parameters
- --id
-
The unique identifier for the resource.
getAllTypes
Obtain the collection of all secondary configuration types related to the resource.
Usage
am> action RESTSecurityTokenServices --realm Realm --actionName getAllTypes
getCreatableTypes
Obtain the collection of secondary configuration types that have yet to be added to the resource.
Usage
am> action RESTSecurityTokenServices --realm Realm --actionName getCreatableTypes
nextdescendents
Obtain the collection of secondary configuration instances that have been added to the resource.
Usage
am> action RESTSecurityTokenServices --realm Realm --actionName nextdescendents
query
Get the full list of instances of this collection. This query only supports _queryFilter=true filter.
Usage
am> query RESTSecurityTokenServices --realm Realm --filter filter
Parameters
- --filter
-
A CREST formatted query filter, where "true" will query all.
read
Usage
am> read RESTSecurityTokenServices --realm Realm --id id
Parameters
- --id
-
The unique identifier for the resource.
update
Usage
am> update RESTSecurityTokenServices --realm Realm --id id --body body
Parameters
- --id
-
The unique identifier for the resource.
- --body
-
The resource in JSON format, described by the following JSON schema:
{ "type" : "object", "properties" : { "restStsDeployment" : { "type" : "object", "title" : "Deployment", "propertyOrder" : 1, "properties" : { "deployment-auth-target-mappings" : { "title" : "Authentication Target Mappings", "description" : "Configuration of consumption of OpenAM's rest-authN. For each validated token type (other than OpenAM), the REST authN elements which will validate token instances. <br>Entry format: <code>TokenType;authIndexType;authIndexValue;context_key=context_value,context_key1=context_value1</code>. <br>The <code>context_key=context_value</code> entries are optional.<br><br>Each deployed STS is configured with the authentication targets for each input token type for each supported token transformation. For example, if the transformation OPENIDCONNECT->SAML2 is supported, the STS instance must be configured with information specifying which elements of the OpenAM restful authentication context needs to be consumed to validate the OPENIDCONNECT token. The elements of the configuration tuple are separated by '|'. <br>The first element is the input token type in the token transform: i.e. X509, OPENIDCONNECT, USERNAME, or OPENAM. The second element is the authentication target - i.e. either 'module' or 'service', and the third element is the name of the authentication module or service. The fourth (optional) element provides the STS authentication context information about the to-be-consumed authentication context. <br>When transforming OpenID Connect Id tokens, the OpenID Connect authentication module must be consumed, and thus a deployed rest-sts instance must be configured with the name of the header/cookie element where the OpenID Connect Id token will be placed. For this example, the following string would define these configurations: <code>OPENIDCONNECT|module|oidc|oidc_id_token_auth_target_header_key=oidc_id_token</code>. In this case, 'oidc' is the name of the OpenID Connect authentication module created to authenticate OpenID Connect tokens. <br>When transforming a X509 Certificate, the Certificate module must be consumed, and the published rest-sts instance must be configured with the name of the Certificate module (or the service containing the module), and the header name configured for the Certificate module corresponding to where the Certificate module can expect to find the to-be-validated Certificate. The following string would define these configurations: <code>X509|module|cert_module|x509_token_auth_target_header_key=client_cert</code>. In this case 'cert_module' is the name of the Certificate module, and client_cert is the header name where Certificate module has been configured to find the client's Certificate.", "propertyOrder" : 800, "required" : true, "items" : { "type" : "string" }, "minItems" : 1, "type" : "array", "exampleValue" : "" }, "deployment-offloaded-two-way-tls-header-key" : { "title" : "Client Certificate Header Key", "description" : "TLS-offload host certificate header key<br><br>Token transformation which take X509 Certificates as the input token require that the X509 Certificate be presented via two-way TLS, so that the TLS handshake can validate client certificate ownership. A standard means of obtaining the client certificate presented via two-way TLS is via the javax.servlet.request.X509Certificate attribute in the ServletRequest. However, in TLS-offloaded deployments, the TLS-offloader must communicate the client certificate to its ultimate destination via an Http header. If this rest-sts instance is to support token transformations with X509 Certificate input, and OpenAM will be deployed in a TLS-offloaded context, then this value must be set to the header value which the TLS-offloading engine will use to set client certificates presented via the TLS handshake.", "propertyOrder" : 900, "required" : false, "type" : "string", "exampleValue" : "" }, "deployment-tls-offload-engine-hosts" : { "title" : "Trusted Remote Hosts", "description" : "IP addresses of TLS-Offload Hosts<br><br>Token transformation which take X509 Certificates as the input token require that the X509 Certificate be presented via two-way TLS, so that the TLS handshake can validate client certificate ownership. If OpenAM is deployed in a TLS-offloaded environment, in which the TLS-offloader must communicate the client certificate to the rest-sts via an Http header, this certificate will only be accepted if the ip address(es) of the TLS-offload engines are specified in this list. Specify 'any' if a client certificate can be presented in the specified header by any rest-sts client.", "propertyOrder" : 1000, "required" : false, "items" : { "type" : "string" }, "type" : "array", "exampleValue" : "" } } }, "restStsSaml2" : { "type" : "object", "title" : "SAML2 Token", "propertyOrder" : 2, "properties" : { "saml2-encrypt-attributes" : { "title" : "Encrypt Attributes", "description" : "Check this box if the assertion Attributes should be encrypted. If this box is checked, the Encrypt Assertion box cannot be checked.", "propertyOrder" : 2600, "required" : false, "type" : "boolean", "exampleValue" : "" }, "saml2-custom-subject-provider-class-name" : { "title" : "Customs Subject Provider Class Name", "description" : "If the Subject of the issued SAML2 assertion needs to be customized, implement the <code>org.forgerock.openam.sts.tokengeneration.saml2.statements.SubjectProvider</code> interface, and specify the class name of the implementation here.", "propertyOrder" : 1700, "required" : false, "type" : "string", "exampleValue" : "" }, "issuer-name" : { "title" : "The SAML2 Issuer Id", "description" : "The name of the issuer<br><br>This name will appear in some issued tokens - e.g. in the <code>saml:Issuer</code> of issued SAML2 assertions.", "propertyOrder" : 1100, "required" : true, "type" : "string", "exampleValue" : "" }, "saml2-custom-authz-decision-statements-provider-class-name" : { "title" : "Custom Authorization Decision Statements Class Name", "description" : "If the AuthorizationDecisionStatements of the issued SAML2 assertion need to be customized, implement the <code>org.forgerock.openam.sts.tokengeneration.saml2.statements.AuthzDecisionStatementsProvider</code> interface, and specify the class name of the implementation here.", "propertyOrder" : 2000, "required" : false, "type" : "string", "exampleValue" : "" }, "saml2-encryption-key-alias" : { "title" : "Encryption Key Alias", "description" : "This alias corresponds to the SP's x509 Certificate identified by the SP Entity ID for this rest-sts instance. Not necessary unless assertions are to be encrypted.", "propertyOrder" : 3200, "required" : false, "type" : "string", "exampleValue" : "" }, "saml2-sp-acs-url" : { "title" : "Service Provider Assertion Consumer Service Url", "description" : "When issuing bearer assertions, the recipient attribute of the SubjectConfirmation element must be set to the Service Provider Assertion Consumer Service Url. See section 4.1.4.2 of Profiles for the OASIS Security Assertion Markup Language (SAML) V2.0 for details. Value required when issuing Bearer assertions.", "propertyOrder" : 1300, "required" : false, "type" : "string", "exampleValue" : "" }, "saml2-encryption-algorithm-strength" : { "title" : "Encryption Algorithm Strength", "description" : "", "propertyOrder" : 2850, "required" : false, "type" : "integer", "exampleValue" : "" }, "saml2-custom-conditions-provider-class-name" : { "title" : "Custom Conditions Provider Class Name", "description" : "If the Conditions of the issued SAML2 assertion need to be customized, implement the <code>org.forgerock.openam.sts.tokengeneration.saml2.statements.ConditionsProvider</code> interface, and specify the class name of the implementation here.", "propertyOrder" : 1600, "required" : false, "type" : "string", "exampleValue" : "" }, "saml2-encrypt-nameid" : { "title" : "Encrypt NameID", "description" : "Check this box if the assertion NameID should be encrypted. If this box is checked, the Encrypt Assertion box cannot be checked.", "propertyOrder" : 2700, "required" : false, "type" : "boolean", "exampleValue" : "" }, "saml2-attribute-map" : { "title" : "Attribute Mappings", "description" : "Contains the mapping of assertion attribute names (Map keys) to local OpenAM attributes (Map values) in configured data stores. Format: <code>assertion_attr_name=ldap_attr_name</code><br><br>The DefaultAttributeMapper looks at profile attributes in configured data stores, or in Session properties. The keys will define the name of the attributes included in the Assertion Attribute statements, and the data pulled from the subject's directory entry or session state corresponding to the map value will define the value corresponding to this attribute name. The keys can have the format <code>[NameFomatURI|]SAML ATTRIBUTE NAME</code>. If the attribute value is enclosed in quotes, that quoted value will be included in the attribute without mapping. Binary attributes should be followed by ';binary'. <br>Examples: <ul><li>EmailAddress=mail</li><li>Address=postaladdress</li><li>urn:oasis:names:tc:SAML:2.0:attrname-format:uri|urn:mace:dir:attribute-def:cn=cn</li><li>partnerID=\"staticPartnerIDValue\"</li><li>urn:oasis:names:tc:SAML:2.0:attrname-format:uri|nameID=\"staticNameIDValue\"</li><li>photo=photo;binary</li><li>urn:oasis:names:tc:SAML:2.0:attrname-format:uri|photo=photo;binary</li></ul>", "propertyOrder" : 2300, "required" : false, "patternProperties" : { ".*" : { "type" : "string" } }, "type" : "object", "exampleValue" : "" }, "saml2-keystore-filename" : { "title" : "KeystorePath", "description" : "Path to keystore<br><br>Provide either the full filesystem path to a filesystem resident keystore, or a classpath-relative path to a keystore bundled in the OpenAM .war file. This keystore contains the IdP public/private keys and SP public key for signed and/or encrypted assertions. If assertions are neither signed nor encrypted, these values need not be specified.", "propertyOrder" : 2900, "required" : false, "type" : "string", "exampleValue" : "" }, "saml2-custom-attribute-mapper-class-name" : { "title" : "Custom Attribute Mapper Class Name", "description" : "If the class implementing attribute mapping for attributes contained in the issued SAML2 assertion needs to be customized, implement the <code>org.forgerock.openam.sts.tokengeneration.saml2.statements.AttributeMapper</code> interface, and specify the class name of the implementation here.", "propertyOrder" : 2100, "required" : false, "type" : "string", "exampleValue" : "" }, "saml2-token-lifetime-seconds" : { "title" : "Token Lifetime (Seconds)", "description" : "Set to over-ride the default of 600 (10 minutes).", "propertyOrder" : 1500, "required" : false, "type" : "integer", "exampleValue" : "" }, "saml2-custom-attribute-statements-provider-class-name" : { "title" : "Custom AttributeStatements Class Name", "description" : "If the AttributeStatements of the issued SAML2 assertion need to be customized, implement the <code>org.forgerock.openam.sts.tokengeneration.saml2.statements.AttributeStatementsProvider</code> interface, and specify the class name of the implementation here.", "propertyOrder" : 1900, "required" : false, "type" : "string", "exampleValue" : "" }, "saml2-custom-authentication-statements-provider-class-name" : { "title" : "Custom AuthenticationStatements Class Name", "description" : "If the AuthenticationStatements of the issued SAML2 assertion need to be customized, implement the <code>org.forgerock.openam.sts.tokengeneration.saml2.statements.AuthenticationStatementsProvider</code> interface, and specify the class name of the implementation here.", "propertyOrder" : 1800, "required" : false, "type" : "string", "exampleValue" : "" }, "saml2-name-id-format" : { "title" : "NameIdFormat", "description" : "The default value is <code>urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified</code><br><br>See section 8.3 of <a href=\"http://docs.oasis-open.org/security/saml/v2.0/saml-core-2.0-os.pdf\" target=\"_blank\">Assertions and Protocols for the OASIS Security Assertion Markup Language (SAML) V2.0</a> for details on possible values.", "propertyOrder" : 1400, "required" : true, "type" : "string", "exampleValue" : "" }, "saml2-encrypt-assertion" : { "title" : "Encrypt Assertion", "description" : "Check this box if the entire assertion should be encrypted. If this box is checked, the Encrypt NameID and Encrypt Attributes boxes cannot be checked.", "propertyOrder" : 2500, "required" : false, "type" : "boolean", "exampleValue" : "" }, "saml2-signature-key-alias" : { "title" : "Signature Key Alias", "description" : "Corresponds to the private key of the IdP. Will be used to sign assertions. Value can remain unspecified unless assertions are signed.", "propertyOrder" : 3300, "required" : false, "type" : "string", "exampleValue" : "" }, "saml2-encryption-algorithm" : { "title" : "Encryption Algorithm", "description" : "Algorithm used to encrypt generated assertions.", "propertyOrder" : 2800, "required" : false, "type" : "string", "exampleValue" : "" }, "saml2-key-transport-algorithm" : { "title" : "Key Transport Algorithm", "description" : "This setting controls the encryption algorithm used to encrypt the symmetric encryption key when SAML2 token encryption is enabled. Valid values include: <pre>http://www.w3.org/2001/04/xmlenc#rsa-1_5</pre>, <pre>http://www.w3.org/2001/04/xmlenc#rsa-oaep-mgf1p</pre>, and <pre>http://www.w3.org/2009/xmlenc11#rsa-oaep</pre>", "propertyOrder" : 2860, "required" : false, "type" : "string", "exampleValue" : "" }, "saml2-sign-assertion" : { "title" : "Sign Assertion", "description" : "", "propertyOrder" : 2400, "required" : false, "type" : "boolean", "exampleValue" : "" }, "saml2-sp-entity-id" : { "title" : "Service Provider Entity Id", "description" : "Values will be used to populate the Audiences of the AudienceRestriction element of the Conditions element. This value is required when issuing Bearer assertions. See section 4.1.4.2 of Profiles for the OASIS Security Assertion Markup Language (SAML) V2.0 for details.", "propertyOrder" : 1200, "required" : true, "type" : "string", "exampleValue" : "" }, "saml2-keystore-password" : { "title" : "Keystore Password", "description" : "", "propertyOrder" : 3000, "required" : false, "type" : "string", "format" : "password", "exampleValue" : "" }, "saml2-signature-key-password" : { "title" : "Signature Key Password", "description" : "", "propertyOrder" : 3400, "required" : false, "type" : "string", "format" : "password", "exampleValue" : "" }, "saml2-custom-authn-context-mapper-class-name" : { "title" : "Custom Authentication Context Class Name", "description" : "If the AuthnContext mapping implemented by the <code>org.forgerock.openam.sts.rest.token.provider.saml.DefaultSaml2JsonTokenAuthnContextMapper</code> class needs to be customized, implement the <code>org.forgerock.openam.sts.rest.token.provider.saml.Saml2JsonTokenAuthnContextMapper</code> interface, and specify the name of the implementation here.", "propertyOrder" : 2200, "required" : false, "type" : "string", "exampleValue" : "" } } }, "restStsGeneral" : { "type" : "object", "title" : "General", "propertyOrder" : 0, "properties" : { "custom-token-transforms" : { "title" : "Custom Token Transforms", "description" : "If either custom token validators or providers are specified, they must also be specified in a custom rest-sts token transformation. These input or output tokens can be specified in a transformation with standard, or other custom, tokens.<br><br>The format of these token transformation definitions is the same as the standard token transformation definitions. The first field defines the input token type, the second the output token type, and the third field specifies whether the OpenAM session, produced as part of the validation of the input token type, is invalidated following the production of the output token. <br><br>Example 1:<code> MY_CUSTOM_INPUT_TOKEN|SAML2|true</code> <br>Example 1 specifies a MY_CUSTOM_INPUT_TOKEN as the input token (requires the specification of a custom token validator) SAML2 as the produced token, and that the interim OpenAM Session should be invalidated after the SAML2 token is produced. <br><br>Example 2: <code>OPENIDCONNECT|MY_CUSTOM_OUTPUT_TOKEN|true</code> <br>Example 2 specifies that an OPENIDCONNECT token should be authenticated to assert the identity of a token of type MY_CUSTOM_OUTPUT_TOKEN (requires the specification of a custom token provider) and that the interim OpenAM Session should be invalidated. <br><br>Example 3: <code>MY_CUSTOM_INPUT_TOKEN|MY_CUSTOM_OUTPUT_TOKEN|false</code> <br>Example 3 specifies that a MY_CUSTOM_INPUT_TOKEN should be transformed into a MY_CUSTOM_OUTPUT_TOKEN (requires the specification of both a custom provider and a custom validator), and that the interim OpenAM session should not be invalidated.", "propertyOrder" : 500, "required" : false, "items" : { "type" : "string" }, "type" : "array", "exampleValue" : "" }, "is-remote-sts-instance" : { "title" : "STS Instance is running as remote instance", "description" : "When true, STS instance will assume it's running on the remote Java process separate from AM server.", "propertyOrder" : 5200, "required" : false, "type" : "boolean", "exampleValue" : "" }, "custom-token-validators" : { "title" : "Custom Token Validators", "description" : "If validator of a custom token type is desired, specify the name of the custom token here, followed by '|', followed by the class name of the <code>org.forgerock.openam.sts.rest.token.validator.RestTokenTransformValidator</code> implementation which will be invoked to validate the custom tokens.<br><br>Example: <code>MY_CUSTOM_INPUT_TOKEN|org.mycompany.tokens.MyCustomTokenValidator</code> <br>Note that MY_CUSTOM_INPUT_TOKEN would then be specified as the value corresponding to the token_type key in the input_token_state json object specified in rest-sts token transformation invocations.", "propertyOrder" : 300, "required" : false, "items" : { "type" : "string" }, "type" : "array", "exampleValue" : "" }, "supported-token-transforms" : { "title" : "Supported Token Transformations", "description" : "Entry format:<code>input_token_type;output_token_type;{true|false}</code>, where true|false indicates whether the interim OpenAM session is invalidated following token issuance.<br><br>Example: for the transform <code>USERNAME:SAML2</code>, it is likely that the OpenAM session generated as part of validating the USERNAME token should be invalidated, and thus the config entry would be <code>USERNAME;SAML2;true</code>. If this value is false, each USERNAME->SAML2 transformation will result in a 'left-over' OpenAM session. Note that currently, any transformation which starts with an OPENAM session, e.g. <code>OPENAM;SAML2</code>, will not invalidate this OPENAM session, as it was not created as part of the token transformation.", "propertyOrder" : 200, "required" : true, "items" : { "type" : "string" }, "minItems" : 1, "type" : "array", "exampleValue" : "" }, "custom-token-providers" : { "title" : "Custom Token Providers", "description" : "If a rest-sts instance is to produce a custom token, specify the name of the custom token here, followed by '|', followed by the class name of the <code>org.forgerock.openam.sts.rest.token.provider.RestTokenProvider</code> implementation which will be invoked to produce an instance of the custom token.<br><br>Example: <code>MY_CUSTOM_OUTPUT_TOKEN|org.mycompany.tokens.MyCustomTokenProvider</code> <br>Note that MY_CUSTOM_OUTPUT_TOKEN would then be specified as the value corresponding to the token_type key in the output_token_state json object specified in rest-sts token transformation invocations.", "propertyOrder" : 400, "required" : false, "items" : { "type" : "string" }, "type" : "array", "exampleValue" : "" }, "persist-issued-tokens-in-cts" : { "title" : "Persist Issued Tokens in Core Token Store", "description" : "Necessary to support token validation and cancellation<br><br>Validation of STS-issued tokens will involve determining whether the token has been issued, has not expired, and has not been cancelled. Token cancellation involves removing the record of this token from the CTS. Thus CTS persistence of STS-issued tokens is required to support these features.", "propertyOrder" : 100, "required" : false, "type" : "boolean", "exampleValue" : "" } } }, "restStsOidc" : { "type" : "object", "title" : "OpenID Connect Token", "propertyOrder" : 3, "properties" : { "oidc-custom-claim-mapper-class" : { "title" : "Custom Claim Mapper Class", "description" : "If the class implementing attribute mapping for attributes contained in issued OpenID Connect tokens needs to be customized, implement the <code>org.forgerock.openam.sts.tokengeneration.oidc.OpenIdConnectTokenClaimMapper</code> interface, and specify the class name of the implementation here.", "propertyOrder" : 4900, "required" : false, "type" : "string", "exampleValue" : "" }, "oidc-signature-key-alias" : { "title" : "KeyStore Signing Key Alias", "description" : "", "propertyOrder" : 4100, "required" : true, "type" : "string", "exampleValue" : "" }, "oidc-authorized-party" : { "title" : "Authorized Party", "description" : "", "propertyOrder" : 4700, "required" : false, "type" : "string", "exampleValue" : "" }, "oidc-custom-authn-method-references-mapper-class" : { "title" : "Custom Authn Methods References Mapper Class", "description" : "If issued OIDC tokens are to contain amr claims, implement the <code>org.forgerock.openam.sts.rest.token.provider.oidc.OpenIdConnectTokenAuthMethodReferencesMapper</code> interface, and specify the class name of the implementation here.", "propertyOrder" : 5100, "required" : false, "type" : "string", "exampleValue" : "" }, "oidc-public-key-reference-type" : { "title" : "Public Key Reference Type", "description" : "For tokens signed with RSA, how should corresponding public key be referenced in the issued jwt", "propertyOrder" : 3700, "required" : false, "type" : "string", "exampleValue" : "" }, "oidc-issuer" : { "title" : "The OpenID Connect Token Provider Issuer Id", "description" : "", "propertyOrder" : 3450, "required" : true, "type" : "string", "exampleValue" : "" }, "oidc-claim-map" : { "title" : "Claim Map", "description" : "Contains the mapping of OIDC token claim names (Map keys) to local OpenAM attributes (Map values) in configured data stores. Format: <code>claim_name=attribute_name</code><br><br>The keys in the map will be claim entries in the issued OIDC token, and the value of these claims will be the principal attribute state resulting from LDAP datastore lookup of the map values. If no values are returned from the LDAP datastore lookup of the attribute corresponding to the map value, no claim will be set in the issued OIDC token.", "propertyOrder" : 4800, "required" : false, "patternProperties" : { ".*" : { "type" : "string" } }, "type" : "object", "exampleValue" : "" }, "oidc-audience" : { "title" : "Issued Tokens Audience", "description" : "Contents will be set in the aud claim", "propertyOrder" : 4600, "required" : true, "items" : { "type" : "string" }, "type" : "array", "exampleValue" : "" }, "oidc-signature-algorithm" : { "title" : "Token Signature Algorithm", "description" : "Algorithm used to sign issued OIDC tokens", "propertyOrder" : 3600, "required" : true, "type" : "string", "exampleValue" : "" }, "oidc-client-secret" : { "title" : "Client Secret", "description" : "For HMAC-signed tokens, the client secret used as the HMAC key.<br><br>For HMAC-signed tokens, the KeyStore location, password, signature key alias and password configurations are not required.", "propertyOrder" : 4400, "required" : true, "type" : "string", "format" : "password", "exampleValue" : "" }, "oidc-keystore-password" : { "title" : "KeyStore Password", "description" : "", "propertyOrder" : 3900, "required" : true, "type" : "string", "format" : "password", "exampleValue" : "" }, "oidc-token-lifetime-seconds" : { "title" : "Token Lifetime (Seconds)", "description" : "", "propertyOrder" : 3500, "required" : false, "type" : "integer", "exampleValue" : "" }, "oidc-custom-authn-context-mapper-class" : { "title" : "Custom Authn Context Mapper Class", "description" : "If issued OIDC tokens are to contain acr claims, implement the <code>org.forgerock.openam.sts.rest.token.provider.oidc.OpenIdConnectTokenAuthnContextMapper</code> interface, and specify the class name of the implementation here.", "propertyOrder" : 5000, "required" : false, "type" : "string", "exampleValue" : "" }, "oidc-keystore-location" : { "title" : "KeyStore Location", "description" : "For RSA-signed tokens, the filesystem or classpath location of the KeyStore containing signing key entry<br><br>For RSA-signed tokens, the KeyStore location, password, signing-key alias, and signing key password must be specified. The client secret is not required for RSA-signed tokens.", "propertyOrder" : 3800, "required" : true, "type" : "string", "exampleValue" : "" }, "oidc-signature-key-password" : { "title" : "Signature Key Password", "description" : "", "propertyOrder" : 4200, "required" : true, "type" : "string", "format" : "password", "exampleValue" : "" } } } } }