This book provides information on using the REST STS (Secure Token Service) in AM.
How do I add and configure a REST STS instance in AM (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 using ssoadm.
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:
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.
Example
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
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:
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
How do I transform an AM session token to an OIDC token in AM (All versions) using REST STS?
The purpose of this article is to provide information on configuring a REST STS (Secure Token Service) instance in AM for transforming an AM session token to OpenID Connect (OIDC) token.
Overview
This article covers the following steps to configure the REST STS and then transform the session token to OIDC token:
AM 6 and later console: navigate to Realms > [Realm Name] > STS and click Add REST STS.
Pre-AM 6 console: navigate to Realms > [Realm Name] > STS > Rest STS Instances and click Add.
Complete the configuration of the STS instance; you should specify the following settings (in AM 6 and later, some of these settings are only available once you have created the instance):
Persist Issued Tokens in Core Token Store: leave this option unselected.
Deployment URL Element: a string that identifies the REST STS instance, for example: sts-oidc. This string is used in the REST STS instance's endpoint.
The OpenID Connect Token Provider Issuer Id: the OpenID Connect agent name, which should also match the protocol://hostname:port/deploymentcontext, for example: http://host1.example.com:8080/openam/oauth2
Token Signature Algorithm: an algorithm suitable for your deployment, for example HMAC SHA 256 (which is suitable for testing but not for production).
Client Secret: the client secret used as the HMAC key - this is mandatory for HMAC-signed tokens.
Issued Tokens Audience: oidc_client
The authorized party (optional): oidc_client
Claim Map: set if required, for example, email=mail
Save this configuration. You do not need to restart the server if the Persist Issued Tokens in Core Token Store option is unselected.
Transforming a session token to OIDC token
To perform the transformation, you make a REST call to the following endpoint:
/rest-sts/[instance]?_action=translate
where [instance] is the name of the REST STS instance, including the realm in which it exists. For example: internal/sts-oidc.
Example using curl
The following example obtains an AM session token and then uses the REST STS instance (called sts-oidc in the internal realm) to transform that session token to an OIDC token:
Authenticate your user to obtain the AM session token. For example: $ curl -X POST -H "X-OpenAM-Username: demo" -H "X-OpenAM-Password: changeit" -H "Content-Type: application/json" -H "Accept-API-Version: resource=2.1" http://host1.example.com:8080/openam/json/realms/root/authenticate
Example response: {"tokenId":"AQIC5wM2LY4SfcxsuvGEjcsppDSFR8H8DYBSouTtz3m64PI.*AAJTSQACMDIAAlNLABQtNTQwMTU3NzgxODI0NzE3OTIwNAEwNDU2NjE0*","successUrl":"/openam/console","realm":"/"}
Transform the received session token to an OIDC token by making a REST call to the /rest-sts/internal/sts-oidc?_action=translate endpoint. For example: $ curl -X POST -H "Content-Type: application/json" -H "Cache-Control: no-cache" -d '{
"input_token_state": { "token_type": "OPENAM", "session_id": "AQIC5wM2LY4Sfcxs...EwNDU2NjE0*"},
"output_token_state": { "token_type": "OPENIDCONNECT", "nonce": "12345678", "allow_access": true }
}' 'http://host1.example.com:8080/openam/rest-sts/internal/sts-oidc?_action=translate' Example OIDC token returned: {"issued_token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJhdWQiOiJvaWRjX2NsaWVudCIsInN1YiI6ImRlbW8iLCJhenAiOiJvaWRjX2NsaWVudCIsImF1dGhfdGltZSI6MTUyMTYyNTM0MywiaXNzIjoiaHR0cDovL2VjMi0zNC0yMTQtMTY4LTIwLnVzLXdlc3QtMi5jb21wdXRlLmFtYXpvbmF3cy5jb206ODA4MC9vcGVuYW0vb2F1dGgyIiwiZXhwIjoxNTIxNjI1OTQzLCJpYXQiOjE1MjE2MjUzNDMsIm5vbmNlIjoiMTIzNDU2NzgiLCJqdGkiOiI5Mjc3N2Y0NS1mNzU2LTRkZmMtOTgyZi1iZmVlMDJhZTg5OTAiLCJlbWFpbCI6ImRlbW8hQGFiYy5jb20ifQ.hFLc4hK-rWxYVFGhaZU8c7ifXZM07uRMLQKIlgPVHII"}
You can decode this token (for example, using https://jwt.davetonge.co.uk/), which shows it contains the following information:
How do I transform an OIDC token to a SAML2 assertion in AM (All versions) using REST STS?
The purpose of this article is to provide information on configuring a REST STS (Secure Token Service) instance in AM for transforming an OpenID Connect (OIDC) token to a SAML2 assertion. This article assumes AM is acting as the OAuth Authorization server (OAuth2 provider), an OIDC token provider, and a REST STS consumer; it provides the necessary configuration steps for this setup, but you can exclude the relevant steps if you are using other providers in place of AM.
Overview
This article covers the following steps to configure the REST STS and then transform the OIDC token to SAML2:
AM 6 and later console: navigate to Realms > [Realm Name] > STS and click Add REST STS.
Pre-AM 6 console: navigate to Realms > [Realm Name] > STS > Rest STS Instances and click Add.
Complete the configuration of the STS instance; you should specify the following settings at a minimum (for settings that are specific to your environment, example values have been given instead):
Persist Issued Tokens in Core Token Store: enable this option.
Supported Token Transforms:UNT -> SAML2; invalidate interim AM session
OPENIDCONNECT -> SAML2; invalidate interim AM session
Deployment Url Element: a string that identifies the REST STS instance, for example: test-sts. This string is used in the REST STS instance's endpoint.
The SAML2 issuer Id: Idp_entityID
Service Provider Entity Id: sp_entityID
Token Lifetime (Seconds): 60000 (it is recommended to set this high to start with for testing purposes)
OpenID Connect Token Provider ID: oidc (the ID of the OIDC agent)
Token Lifetime (Seconds): 60000 (again set this high to start with for testing purposes)
Token signature algorithm: the HMAC or RSA signing algorithm, for example, HMAC SHA 256
Client secret: the client secret used as the HMAC key (mandatory for HMAC-signed tokens)
Issued Tokens Audience: myClient (this is the name of the OIDC client)
Restart the web application container in which AM runs to complete this configuration.
Navigate to Realms > [Realm Name] > Applications > Federation > Circles of Trust, click Add Circle of Trust and enter a name for the new COT, for example, cot.
Navigate to Realms > [Realm Name] > Applications > Federation > Entity Providers, click Add Entity Provider, select Hosted and enter the required details; including an entity ID (for example, sp_entityID) and selecting the COT you just created.
Pre-AM 7
Navigate to: Realms > [Realm Name] > Common Tasks > Configure SAMLv2 Provider > Create Hosted Service Provider
Name: sp_entityID
New Circle of Trust: cot
Creating an OAuth2 provider
If AM is acting as the OAuth2 provider, you should create this in the same realm as you created the REST STS instance:
Navigate to: Realms > [Realm Name] > Common Tasks > Configure OAuth Provider > Configure OAuth 2.0 and populate the relevant details.
Navigate to: Realms > [Realm Name] > Services > OAuth2 Provider and specify the supported scopes. You may need to add this service if it does not already exist.
Creating an OIDC client
If AM is acting as the OIDC server, you should create an OIDC client in the same realm as you created the REST STS instance:
Create a new OIDC client using the console:
AM 7 and later console: navigate to Realms > [Realm Name] > Applications > OAuth 2.0 > Clients and click Add Client.
AM 5.5 and 6.x console: navigate to Realms > [Realm Name] > Applications > OAuth 2.0 and click Add Client.
AM 5 and 5.1.x console: navigate to Realms > [Realm Name] > Applications > OAuth 2.0 and click New.
Complete the configuration of the OIDC client; you should specify the following settings at a minimum (for settings that are specific to your environment, example values have been given instead):
Name: sp_entityID
Scope(s): cn, openid
Default Scope(s): cn, openid
Token Endpoint Authentication Method: client_secret_post - you must select this option if you use scope=openid%20profile with the resource owner password credentials grant type otherwise you will get an error when you do a POST request to the oauth2/access_token endpoint (invalid_client error when requesting an OAuth 2.0 access token in AM (All versions)).
If AM is acting as the OIDC server, you should create an OpenID Connect id_token bearer authentication module in the same realm as you created the REST STS instance:
Console
Navigate to: Realms > [Realm Name] > Authentication > Modules and click Add Module.
Name the module oidc, select OpenID Connect id_token bearer and click OK. The module name mustbe oidc (all in lowercase) as this is used by REST STS to know which authentication context is used to validate the OpenID Connect token.
Complete the configuration of the OpenID Connect id_token bearer authentication module; you should specify the following settings at a minimum (for settings that are specific to your environment, example values have been given instead):
OpenID Connect validation configuration value: password (this is the password of the OIDC client)
Name of OpenID Connect ID Token Issuer: http://sp.example.com:8080/openam/oauth2
Mapping of jwt attributes to local LDAP attributes: sub=uid
Audience name: myClient (this is the name of the OIDC client)
List of accepted authorized parties: myClient
ssoadm
Use the following ssoadm command to create the OpenID Connect id_token bearer type authentication module: $ ./ssoadm create-auth-instance -u [adminID] -f [passwordfile] -e [realmname] -m oidc -t OpenIdConnectreplacing [adminID], [passwordfile] and [realmname] with appropriate values. The module name mustbe oidc (all in lowercase) as this is used by REST STS to know which authentication context is used to validate the OpenID Connect token.
Create a data file (called data_file to match the next command) with the following contents, or download the sample data_file: openam-auth-openidconnect-crypto-context-value=http://sp.example.com:8080/openam/oauth2/.well-known/openid-configuration
openam-auth-openidconnect-issuer-name=http://sp.example.com:8080/openam/oauth2
openam-auth-openidconnect-audience-name=http://sp.example.com:8080/openam
openam-auth-openidconnect-accepted-authorized-parties=http://sp.example.com:8080/openamYou can add other attributes if required as per the available ones detailed in OpenID Connect id_token bearer Module.
Run the following command to configure your new oidc module with these settings: $ ./ssoadm update-auth-instance -u [adminID] -f [passwordfile] -e [realmname] -m oidc -D data_filereplacing [adminID], [passwordfile] and [realmname] with appropriate values.
You can check the settings for your new oidc module using the following command if required: $ ./ssoadm get-auth-instance -u [adminID] -f [passwordfile] -e [realmname] -m oidcreplacing [adminID], [passwordfile] and [realmname] with appropriate values.
Transforming an OIDC token to SAML2
Restart your AM server before testing to ensure that all changes have been captured.
To perform the transformation, you make a REST call to the following endpoint:
/rest-sts/[instance]?_action=translate
where [instance] is the name of the REST STS instance, including the realm in which it exists. For example: employees/test-sts.
Example using curl
The following example obtains an OIDC token and then uses the REST STS instance (called test-sts in the employees realm) to transform that OIDC token to a SAML2 assertion:
Request an OIDC token by making a REST call to the oauth2/access_token endpoint, which uses the client_secret_post authentication method. For example: $ curl -X POST -d '{
"client_id=myClientID&client_secret=changeit&grant_type=password&username=jdoe&password=changeit&scope=openid%20profile"
}' http://host1.example.com:8080/openam/oauth2/access_tokenExample response: {"scope":"openid profile","expires_in":599,"token_type":"Bearer","id_token":"eyAidHlwIjogIkpXVCIsICJhbGciOiAiSFMyNTYiLCAiY3R5IjogIkpXVCIsICJraWQiOiAiYTM3ZjE3YTItNjkzMi00YjAxLWFkZDUtOTM1YmU0N2E3NTI3IiB9.eyAidG9rZW5OYW1lIjogImlkX3Rva2VuIiwgImF6cCI6ICJteU9BdXRoMkNsaWVudCIsICJzdWIiOiAiZGVtbyIsICJhdF9oYXNoIjogIkVxV1JzNzlDMUVMVHBYazd6MU9pYVEiLCAiaXNzIjogImh0dHA6Ly9vYXV0aDJwcm92aWRlci5leGFtcGxlLm5ldDo1ODA4MC9vcGVuYW0vb2F1dGgyIiwgImlhdCI6IDE0NDE3MzI4NTMsICJhdXRoX3RpbWUiOiAxNDQxNzMyODUzLCAiZXhwIjogMTQ0MTczMzQ1MywgInRva2VuVHlwZSI6ICJKV1RUb2tlbiIsICJyZWFsbSI6ICIvIiwgImF1ZCI6IFsgIm15T0F1dGgyQ2xpZW50IiBdLCAib3BzIjogIjVmOGMyYWUzLTdkOTctNDNmNi04NGQ3LTI4YjgzYjNjNmUxNSIgfQ.wDh5UET7KuDLWc-enRpkLigqttYZ14PG2UIbmHOgAaM","access_token":"238beab2-b545-4fee-80fa-63f224bc56f6"}
Transform the received OIDC token to a SAML2 assertion by making a REST call to the /rest-sts/employees/test-sts?_action=translate endpoint. For example: $ curl -X POST -H "Content-Type: application/json" -d '{
"input_token_state": { "token_type": "OPENIDCONNECT", "oidc_id_token": "eyAidHlwIjogIkp...-enRpkLigqttYZ14PG2UIbmHOgAaM" },
"output_token_state": { "token_type": "SAML2", "subject_confirmation": "BEARER", "service_provider_assertion_consumer_service_url": "http://sp.example.com:8080/openam/users/metaAlias/sp" }
}' 'http://host1.example.com:8080/openam/rest-sts/employees/test-sts?_action=translate'Example SAML2 assertion returned: {"issued_token":"<saml:Assertion xmlns:saml=\"urn:oasis:names:tc:SAML:2.0:assertion\" ID=\"s259f7ac265f109b3ddcc265267c3f3f3e80af4657\" IssueInstant=\"2015-09-08T17:21:27Z\" Version=\"2.0\">\n<saml:Issuer>ForgeRock</saml:Issuer><saml:Subject>\n<saml:NameID Format=\"urn:oasis:names:tc:SAML:1.0:nameid-format:unspecified\">jdoe</saml:NameID><saml:SubjectConfirmation Method=\"urn:oasis:names:tc:SAML:2.0:cm:bearer\">\n<saml:SubjectConfirmationData NotOnOrAfter=\"2015-09-08T17:31:27Z\"/></saml:SubjectConfirmation>\n</saml:Subject><saml:Conditions NotBefore=\"2015-09-08T17:21:27Z\" NotOnOrAfter=\"2015-09-08T17:31:27Z\">\n<saml:AudienceRestriction>\n<saml:Audience>sp</saml:Audience>\n</saml:AudienceRestriction>\n</saml:Conditions>\n<saml:AuthnStatement AuthnInstant=\"2015-09-08T17:21:27Z\"><saml:AuthnContext><saml:AuthnContextClassRef>urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport</saml:AuthnContextClassRef></saml:AuthnContext></saml:AuthnStatement></saml:Assertion>"}
How do I transform an AM session token to a SAML2 assertion in AM (All versions) using REST STS?
The purpose of this article is to provide information on transforming an AM session token to a SAML2 assertion in AM using REST STS (Secure Token Service). It assumes you have already successfully configured a REST STS instance for SAML2 transformations.
Transforming a session token to a SAML2 token
To perform the transformation, you make a REST call to the following endpoint:
/rest-sts/[instance]?_action=translate
where [instance] is the name of the REST STS instance, including the realm in which it exists. For example: employees/testSTS.
Example using curl
The following example authenticates the demo user to AM in order to generate a valid session token. It then uses the REST STS instance (called testSTS in the employees realm) to transform that session token to a SAML2 assertion:
Authenticate as the demo user. For example:$ curl -X POST -H "X-OpenAM-Username: demo" -H "X-OpenAM-Password: changeit" -H "Content-Type: application/json" -H "Accept-API-Version: resource=2.1" http://host1.example.com:8080/openam/json/realms/root/authenticate
Example response: {"tokenId":"AQIC5wM2LY4SfcxsuvGEjcsppDSFR8H8DYBSouTtz3m64PI.*AAJTSQACMDIAAlNLABQtNTQwMTU3NzgxODI0NzE3OTIwNAEwNDU2NjE0*","successUrl":"/openam/console","realm":"/"}
Transform the received session token to a SAML2 assertion by making a REST call to the /rest-sts/employees/testSTS?_action=translate endpoint. For example: $ curl -X POST -H "Content-Type: application/json" -d '{
"input_token_state": { "token_type": "OPENAM", "session_id": "AQIC5wM2LY4Sfcxs...EwNDU2NjE0*" },
"output_token_state": { "token_type": "SAML2", "subject_confirmation": "BEARER", "service_provider_assertion_consumer_service_url": "http://sp.example.com:8080/openam/users/metaAlias/sp" }
}' 'http://host1.example.com:8080/openam/rest-sts/employees/testSTS?_action=translate' Example SAML2 assertion returned: {"issued_token":"<saml:Assertion xmlns:saml=\"urn:oasis:names:tc:SAML:2.0:assertion\" ID=\"s2a1033a774e80d5f09c8aaebe5fddc337184f950f\" IssueInstant=\"2015-08-03T23:15:18Z\" Version=\"2.0\">\n<saml:Issuer>Example</saml:Issuer><saml:Subject>\n<saml:NameID Format=\"urn:oasis:names:tc:SAML:1.0:nameid-format:unspecified\">demo</saml:NameID><saml:SubjectConfirmation Method=\"urn:oasis:names:tc:SAML:2.0:cm:bearer\">\n<saml:SubjectConfirmationData NotOnOrAfter=\"2015-08-10T21:55:18Z\" Recipient=\"http://sp.example.com:8080/openam/users/metaAlias/sp\"/></saml:SubjectConfirmation>\n</saml:Subject><saml:Conditions NotBefore=\"2015-08-03T23:15:18Z\" NotOnOrAfter=\"2015-08-10T21:55:18Z\">\n<saml:AudienceRestriction>\n<saml:Audience>ExampleEmployeesSP</saml:Audience>\n</saml:AudienceRestriction>\n</saml:Conditions>\n<saml:AuthnStatement AuthnInstant=\"2015-08-03T23:15:18Z\"><saml:AuthnContext><saml:AuthnContextClassRef>urn:oasis:names:tc:SAML:2.0:ac:classes:PreviousSession</saml:AuthnContextClassRef></saml:AuthnContext></saml:AuthnStatement></saml:Assertion>"}