How To
ForgeRock Identity Platform
Does not apply to Identity Cloud

How do I add and configure a REST STS instance in AM (All versions) using ssoadm?

Last updated Apr 13, 2021

The purpose of this article is to provide assistance with adding and configuring a REST STS (Secure Token Service) instance in AM using ssoadm.

1 reader recommends this article

Adding a REST STS instance

Firstly you should create a data file (in this example, DATA_FILE) and populate it with the required attribute values for the new REST STS instance. You can use the attached DATA_FILE to get started.

You can then add a REST STS instance using ssoadm as follows:

$ ./ssoadm create-sub-cfg -s RestSecurityTokenService -e [realmname] -b [subconfigname] -g [parentconfigID] -u [adminID] -f [passwordfile] -D DATA_FILE

replacing [realmname], [subconfigname], [parentconfigID], [adminID] and [passwordfile] with appropriate values, where:

  • [subconfigname] is the REST STS instance name. If you want to have a REST STS instance name that follows the same convention used when creating a REST STS instance via the console (that is, realm/deployment-url), you can set this to: "realm/deployment-uri".
  • [parentconfigID] is the ID of the parent configuration (SubSchema name), as defined in restSTS.xml (located in the /path/to/tomcat/webapps/openam/WEB-INF/classes directory where AM is deployed). The SubSchema name is serverconfig by default.


To create a REST STS instance called testSTS in the employees realm, you would use the following command:

  • AM 7 and later: $ ./ssoadm create-sub-cfg -s RestSecurityTokenService -e employees -b "employees/testSTS" -g serverconfig -u uid=amAdmin,ou=People,dc=openam,dc=forgerock,dc=org -f pwd.txt -D DATA_FILE
  • Pre-AM 7: $ ./ssoadm create-sub-cfg -s RestSecurityTokenService -e employees -b "employees/testSTS" -g serverconfig -u amadmin -f pwd.txt -D DATA_FILE

Configuring a REST STS instance

You can use the ssoadm get-sub-cfg command to check what attributes are available and then update them using set-sub-cfg.


  1. Run the ssoadm get-sub-cfg command to check which attributes are available:
    • AM 7 and later: $ ./ssoadm get-sub-cfg -s RestSecurityTokenService -e employees -g "employees/testSTS" -u uid=amAdmin,ou=People,dc=openam,dc=forgerock,dc=org -f pwd.txt
    • Pre-AM 7: $ ./ssoadm get-sub-cfg -s RestSecurityTokenService -e employees -g "employees/testSTS" -u amadmin -f pwd.txt

Example output (where only saml2-token-lifetime-seconds has been set to the default value of 600):saml2-custom-attribute-statements-provider-class-name= saml2-attribute-map= supported-token-transforms=OPENAM|SAML2|false supported-token-transforms=OPENIDCONNECT|SAML2|true supported-token-transforms=USERNAME|SAML2|true supported-token-transforms=X509|SAML2|true saml2-sign-assertion= saml2-name-id-format= issuer-name= deployment-realm= saml2-encryption-key-alias= saml2-custom-subject-provider-class-name= saml2-encrypt-nameid= saml2-keystore-filename= saml2-signature-key-password= deployment-auth-target-mappings=X509|module|cert_module|x509_token_token_auth_target_header_key=client_cert deployment-auth-target-mappings=OPENIDCONNECT|module|oidc|oidc_id_token_auth_target_header_key=oidc_id_token deployment-auth-target-mappings=USERNAME|service|ldapService deployment-tls-offload-engine-hosts= saml2-encryption-algorithm= saml2-custom-attribute-mapper-class-name= saml2-encryption-algorithm-strength= saml2-custom-authz-decision-statements-provider-class-name= saml2-custom-conditions-provider-class-name= saml2-token-lifetime-seconds=600 saml2-encrypt-assertion= saml2-sp-entity-id= saml2-custom-authn-context-mapper-class-name= deployment-url-element= saml2-sp-acs-url= saml2-signature-key-alias= saml2-encrypt-attributes= deployment-offloaded-two-way-tls-header-key= saml2-keystore-password= saml2-custom-authentication-statements-provider-class-name= Sub Configuration emp/testSTS was retrieved from realm employees

  1. Change the lifetime of the SAML2 token that is created by REST STS to 5 minutes (instead of the default 10 minutes) using the following command:
    • AM 7 and later: $ ./ssoadm set-sub-cfg -s RestSecurityTokenService -e employees -g "employees/testSTS" -u uid=amAdmin,ou=People,dc=openam,dc=forgerock,dc=org -f pwd.txt -o set -a saml2-token-lifetime-seconds=300
    • Pre-AM 7: $ ./ssoadm set-sub-cfg -s RestSecurityTokenService -e employees -g "employees/testSTS" -u amadmin -f pwd.txt -o set -a saml2-token-lifetime-seconds=300

See Also

Using the REST STS in AM

Security Token Service Guide

Related Training


Related Issue Tracker IDs


Copyright and Trademarks Copyright © 2021 ForgeRock, all rights reserved.