How To
ForgeRock Identity Platform
Does not apply to Identity Cloud

How do I transform an OIDC token to a SAML2 assertion in AM (All versions) using REST STS?

Last updated Jan 16, 2023

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.


2 readers recommend this article

Overview

This article covers the following steps to configure the REST STS and then transform the OIDC token to SAML2:

  1. Create a REST STS instance
  2. Create a Service Provider
  3. Create an OAuth2 provider (skip this step if you are not using AM as the OAuth2 provider)
  4. Create an OIDC client (skip this step if you are not using AM as the OIDC server)
  5. Create an OIDC authentication module (skip this step if you are not using AM as the OIDC server)
  6. Transform an OIDC token to SAML2
Note

If you are using IG as an OAuth2 client (in place of the OIDC client in step 4), you should refer to the documentation for the required setup instead: Transform OpenID Connect ID tokens into SAML Assertions.

Creating a REST STS instance

You can create a REST STS instance as follows:

  1. Create a new REST STS instance using the AM admin UI by navigating to Realms > [Realm Name] > STS and click Add REST STS.
  2. 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)
  3. Restart the web application container in which AM runs to complete this configuration.
Note

You can also create a REST STS instance via ssoadm as detailed in How do I add and configure a REST STS instance in AM (All versions) using ssoadm? - you should use the settings described above.

Creating a Service Provider

You can create a Service Provider as follows:

AM 7 and later

  1. 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.
  2. 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.

AM 6.x

  1. Navigate to: Realms > [Realm Name] > Common Tasks > Configure SAMLv2 Provider > Create Hosted Service Provider and enter the required details:
    • 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:

AM 7 and later

See Authorization server configuration for further information.

AM 6.x

  1. Navigate to: Realms > [Realm Name] > Common Tasks > Configure OAuth Provider > Configure OAuth 2.0 and populate the relevant details.
  2. 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:

  1. Create a new OIDC client using the AM admin UI:
    • AM 7 and later admin UI: navigate to Realms > [Realm Name] > Applications > OAuth 2.0 > Clients and click Add Client.
    • AM 6.x admin UI: navigate to Realms > [Realm Name] > Applications > OAuth 2.0 and click Add Client.
  2. 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)).
    • ID Token Signing Algorithm: RS256
Note

You can also create an OIDC client using REST as detailed in How do I create and update an Agent in AM (All versions) using the REST API? - you should use the settings described above.

Creating OIDC authentication module

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:

AM admin UI

  1. Navigate to: Realms > [Realm Name] > Authentication > Modules and click Add Module.
  2. Name the module oidc, select OpenID Connect id_token bearer and click OK. The module name must be oidc (all in lowercase) as this is used by REST STS to know which authentication context is used to validate the OpenID Connect token.
  3. 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 type: client_secret
    • OpenID Connect validation configuration value: password (this is the password of the OIDC client)
    • Name of OpenID Connect ID Token Issuer: https://sp.example.com:8443/am/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

  1. 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 must be oidc (all in lowercase) as this is used by REST STS to know which authentication context is used to validate the OpenID Connect token.
  2. 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=https://sp.example.com:8443/am/oauth2/.well-known/openid-configuration openam-auth-openidconnect-issuer-name=https://sp.example.com:8443/am/oauth2 openam-auth-openidconnect-audience-name=https://sp.example.com:8443/am openam-auth-openidconnect-accepted-authorized-parties=https://sp.example.com:8443/amYou can add other attributes if required as per the available ones detailed in OpenID Connect id_token bearer module.
  3. 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.
  4. 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: ​

  1. 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" }' https://am.example.com:8443/am/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"}
  2. 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": "https://sp.example.com:8443/am/users/metaAlias/sp" } }' 'https://am.example.com:8443/am/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>"}

See Also

Using the REST STS in AM

invalid_client error when requesting an OAuth 2.0 access token in AM (All versions)

Security Token Service

Related Training

N/A

Related Issue Tracker IDs

OPENAM-7887 (Unsupported Signing Algorithm, SHA256withRSA with Google issued JWT's)


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