How To

How do I transform an OIDC token to a SAML2 assertion in OpenAM 12.x using REST STS?

Last updated Dec 17, 2018

The purpose of this article is to provide information on configuring a REST STS (Secure Token Service) instance in OpenAM 12.x for transforming an OpenID Connect (OIDC) token to SAML2. This article assumes OpenAM is acting as the OAuth Authorization server (OAuth2 provider), an OIDC token provider, and a REST STS consumer, and provides the necessary configuration steps for this setup; you can exclude the relevant steps where you are using other providers in place of OpenAM.


Archived

This article has been archived and is no longer maintained by ForgeRock.

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 OpenAM as the OAuth2 provider)
  4. Create an OIDC client (skip this step if you are not using OpenAM as the OIDC server)
  5. Create an OIDC authentication module (skip this step if you are not using OpenAM as the OIDC server)
  6. Transform an OIDC token to SAML2

Known issue in OpenAM 12.0.0, 12.0.1 and 12.0.2

Caution

There is a known security issue in OpenAM 12.0.0, 12.0.1 and 12.0.2, which is detailed as Issue #201601-05: Business Logic Vulnerability in OpenAM Security Advisory #201601.

If you are using OpenAM 12.0.0, 12.0.1 or 12.0.2 and want to use this functionality, you should upgrade to OpenAM 12.0.3 or later, download the appropriate patch to fix the issue or use the workaround outlined in the Security Advisory to ensure your implementation is not vulnerable to this security issue.

Creating a REST STS instance

You can create a REST STS instance as follows (you can view example screenshots of this configuration in test_sts_instance.pdf):

  1. Navigate to: Access Control > [Realm Name] > STS > Rest STS Instances and click Add.
  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): 
    • The Issuer Name: sp.example.com
    • Supported Token Transforms:
      UNT -> SAML2; invalidate interim OpenAM session
      OPENIDCONNECT -> SAML2; invalidate interim OpenAM session
    • Deployment Url Element: test-sts
    • Service Provider Entity Id:  sp
    • Token Lifetime (Seconds): 60000 - it is recommended to set this high to start with for testing purposes.
  3. Restart the web application container in which OpenAM 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/OpenAM (All versions) using ssoadm? - you should use the settings described above.

Creating a Service Provider

You can create a Service Provider as follows:

  1. Navigate to: Common Tasks > Create Hosted Service Provider
    • Name: sp
    • New Circle of Trust: cot

Creating an OAuth2 provider

If OpenAM is acting as the OAuth2 provider, you should create this in the same realm as you created the REST STS instance (you can view screenshots of this example configuration in oauth2_provider.pdf): 

  1. Navigate to: Common Tasks > Configure OAuth2/OpenID Connect and populate the relevant details.
  2. Navigate to: Access Control > [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 OpenAM is acting as the OIDC server, you should create an OIDC client in the same realm as you created the REST STS instance (you can view example screenshots of this configuration in myClient.pdf):  

  1. Navigate to: Access Control > [Realm Name] > Agents > OAuth 2.0/OpenID Connect Client and click New.
  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: myClient.
    • Client Password: password
    • Client Password: password
    • Redirection URI's: http://sp.example.com:8080/openam/oauth2c/OAuthProxy.jsp
    • Scope(s): cn, openid, profile
    • Default Scope(s): cn, openid, profile
    • ID Token Signed Response Algorithm: HS256 
Note

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

Creating an OIDC authentication module

If OpenAM 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 (you can view example screenshots of this configuration in oidc_module.pdf). You can do this via the OpenAM console or ssoadm:

Console

  1. Navigate to: Access Control > [Realm Name] > Authentication > Module Instances and click New.
  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):
    • Configuration type: please select either 1.the issuer discovery url, 2. the issuer jwk url, or 3. the client_secret:  client_secret
    • The discovery url, or jwk url, or the client_secret, corresponding to the selection above: password
    • Name of OpenID Connect ID Token Issuer: http://sp.example.com:8080/openam/oauth2
    • Audience name: myClient
    • List of accepted authorized parties:  myClient
    • Mapping of local LDAP attributes to jwt attributes: change the mapping to sub=uid and delete uid=sub

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 OpenIdConnect
    replacing [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=password
    openam-auth-openidconnect-crypto-context-type=client_secret
    openam-auth-openidconnect-issuer-name=http://sp.example.com:8080/openam/oauth2
    openam-auth-openidconnect-audience-name=myClient
    openam-auth-openidconnect-local-to-jwt-attribute-mappings=sub=uid
    openam-auth-openidconnect-accepted-authorized-parties=myClient
    You can add other attributes if required as per the available ones detailed in OpenAM Administration Guide › Defining Authentication Services › Hints for the OpenID Connect id_token bearer Module.
Note

Setting openam-auth-openidconnect-crypto-context-type (OpenID Connect validation configuration type) to anything other than the default does not work. There is a known issue associated with the client_secret value: OPENAM-7887 (Unsupported Signing Algorithm, SHA256withRSA with Google issued JWT's).

  1. 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_FILE
    replacing [adminID], [passwordfile] and [realmname] with appropriate values.
  2. 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 oidc
    replacing [adminID], [passwordfile] and [realmname] with appropriate values.​

Transforming an OIDC token to SAML2

Restart your OpenAM server before testing to ensure that all changes have been captured.

To perform the transformation, you make a REST call to the following endpoint:

/openam/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 obtains an OIDC token and then uses the REST STS instance (called testSTS 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 (you must use this format as it uses the client_secret_post authentication method):
    $ 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_token
    
    Example 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 /openam/rest-sts/employees/testSTS?_action=translate endpoint:
    $ curl -X POST -H "Content-Type: application/json" -H "Cache-Control: no-cache" -d '{ "input_token_state": { "token_type": "OPENIDCONNECT", "oidc_id_token": "eyAidHlwIjogIkpXVCIsICJhbGciOiAiSFMyNTYiLCAiY3R5IjogIkpXVCIsICJraWQiOiAiYTM3ZjE3YTItNjkzMi00YjAxLWFkZDUtOTM1YmU0N2E3NTI3IiB9.eyAidG9rZW5OYW1lIjogImlkX3Rva2VuIiwgImF6cCI6ICJteU9BdXRoMkNsaWVudCIsICJzdWIiOiAiZGVtbyIsICJhdF9oYXNoIjogIkVxV1JzNzlDMUVMVHBYazd6MU9pYVEiLCAiaXNzIjogImh0dHA6Ly9vYXV0aDJwcm92aWRlci5leGFtcGxlLm5ldDo1ODA4MC9vcGVuYW0vb2F1dGgyIiwgImlhdCI6IDE0NDE3MzI4NTMsICJhdXRoX3RpbWUiOiAxNDQxNzMyODUzLCAiZXhwIjogMTQ0MTczMzQ1MywgInRva2VuVHlwZSI6ICJKV1RUb2tlbiIsICJyZWFsbSI6ICIvIiwgImF1ZCI6IFsgIm15T0F1dGgyQ2xpZW50IiBdLCAib3BzIjogIjVmOGMyYWUzLTdkOTctNDNmNi04NGQ3LTI4YjgzYjNjNmUxNSIgfQ.wDh5UET7KuDLWc-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/testSTS?_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

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

Using the REST STS in AM/OpenAM

OpenAM Security Advisory #201601

OpenAM Administration Guide › The RESTful Security Token Service

OpenAM Developer's Guide › RESTful Secure Token Service

OpenAM Administration Guide › Defining Authentication Services › Hints for the OpenID Connect id_token bearer Module

Related Training

N/A

Related Issue Tracker IDs

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

OPENAM-6461 (Federation, SAE, & WSSAuthModule missing in new realm after default initial configuration)

OPENAM-6319 (OAuth2 scopes behaviour affected by the upgrade)



Copyright and TrademarksCopyright © 2018 ForgeRock, all rights reserved.
Loading...