How do I add and configure a REST STS instance in AM/OpenAM (All versions) using ssoadm?
The purpose of this article is to provide assistance with adding and configuring a REST STS (Secure Token Service) instance in AM/OpenAM using ssoadm.
Overview
The ssoadm command used to add a REST STS instance differs between versions. In summary, the -b and -g options have swapped round as of OpenAM 13.x and you no longer need to escape the forward slash in the REST STS instance name. However, the ssoadm command to configure a REST STS instance is unchanged.
Adding a REST STS instance (AM and OpenAM 13.x)
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/OpenAM is deployed). The SubSchema name is serverconfig by default.
Example
To create a REST STS instance called testSTS in the employees realm, you would use the following command:
$ ./ssoadm create-sub-cfg -s RestSecurityTokenService -e employees -b "employees/testSTS" -g serverconfig -u amadmin -f pwd.txt -D DATA_FILE
Adding a REST STS instance (OpenAM 12.x)
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] -g [subconfigname] -b [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 should set this to: "realm/deployment-uri" where / escapes the forward slash.
- [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 OpenAM is deployed). The SubSchema name is serverconfig by default.
Example
To create a REST STS instance called testSTS in the employees realm, you would use the following command:
$ ./ssoadm create-sub-cfg -s RestSecurityTokenService -e employees -g "employees/testSTS" -b 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.
Example
- Run the ssoadm get-sub-cfg command to check which attributes are available:
$ ./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=http://www.w3.org/2001/04/xmlenc#aes128-cbc 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
- 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:
$ ./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
Related Training
N/A
Related Issue Tracker IDs
OPENAM-6811 (Support consumption of rest endpoints from ssoadm)