SAML Inbound and Outbound support in API Gateway

[Clench_Paign_James3 (Clench Paign James)]

webMethods API Gateway tutorial

Author: Chandrasekaran, Vallab (vac@softwareag.com)
Supported Versions: 10.0 and above

Overview of the tutorial

This tutorial helps you to walk through the steps to enforce SAML Inbound and SAML Outbound authentication policies in API Gateway.

Required knowledge

The tutorial assumes that the reader has:

• a basic understanding of API Gateway and its policy enforcement
• a basic understanding of SAML authentication mechanism

Prerequisite steps

• Install API Gateway 10.3 advanced edition

Details

SAML Inbound in API Gateway

API Gateway supports Inbound SAML Authentication from version 10.0.  The Subject Confirmation Methods supported in API Gateway Inbound SAML as given below.

• Bearer
• HOK Symmetric
• HOK Asymmetric (not tested as ADFS doesn't support this)

Typically, the Inbound SAML Authentication in API Gateway contains the steps below, as shown in image above.

1. Client sends a request to the STS for a SAML token.
2. STS sends the SAML token to the client.
3. Client with the SAML token embedded in the SOAP header sends the request to API Gateway.
4. API Gateway authenticates the SAML token based on the Subject Confirmation(Bearer,HOK Symmetric ,HOK Asymmetric) used in the inbound SAML policy.
5. API Gateway sends request to native service.
6. Native service sends the response to API Gateway 
7. API Gateway forwards the response to client.
8. The detailed steps for steps 1 to 3 will vary for the different SAML Subject Confirmations configured. We will see them one by one in corresponding sections

Prerequisite Steps

For SAML Inbound, the below prerequisite steps are common for all 3 types of Subject Confirmation Methods. 

Prerequisite configurations in ADFS machine

• In the ADFS machine add a relying party trust with name PolicyGateway using administrator certificate .
• In the Edit Claim Rules of PolicyGateway add the following claims
  • SAM-Account-Name ----> http://integration.fiserv.com/identity/claims/v1/FirstName
    
• Ensure the "Delegation Authorization Rules" is set to "Permit Access to All Users" or specific users in the active directory

Prerequisite configurations in API Gateway machine

• Add the IP address and hostname entry in hosts file. C:\Windows\System32\drivers\etc\hosts for windows. eg: 10.xx.xx.xxx xx.sag.xx.com 
• Download JCE Java library. Extract the zip and copy local_policy.jar, US_export_policy.jar to  "{IS_Installation_Dir}\jvm\jvm\jre\lib\security" folder.
• Also copy the local_policy.jar and US_export_policy.jar  from step 2 to lib/security folder of JVM on which client is running. eg: C:\Program Files\Java\jdk1.8.0_121\jre\lib\security
• Set APIGateway's keystore to adminKeystore. The password is 'password'.
• Set APIGateway's truststore to ADFS_Sign_Machine_Certificate. The password is 'password'
• Configure the keystore and truststore in API Gateway. 
• Add the following 2 lines in {IS Install Directory}\IntegrationServer\instances\default\config\is_jaas.cnf under WSS_Message_IS section. 

com.wm.app.b2b.server.auth.jaas.SamlAssertLoginModule requisite

samlAttributeName="http://integration.fiserv.com/identity/claims/v1/FirstName";

• By adding "http://integration.fiserv.com/identity/claims/v1/FirstName" saml attribute name we are intimating the IS to look for this attribute and match it with IS user
• Add Trusted SAML Token Issuer in Integration Server. Issuer name should be the ADFS trust URL
  
• Restart Integrtion Server

Additional steps

For easy debugging in case of errors during execution of SAML inbound, paste below lines in <Install>\profiles\IS_default\configuration\logging\log_config.xml.

<logger name="org.apache.rampart"> 
<level value="debug" /> 
</logger>

<logger name="org.apache.axis2"> 
<level value="debug" /> 
</logger>

<logger name="org.apache.ws.security"> 
<level value="debug" /> 
</logger>

SAML Inbound - Bearer

• Client sends a request to the STS for a SAML token with KeyType as Bearer
• STS generates a SAML token and signs the token with its private key and sends the SAML token to the client.
• Client with the SAML token embedded in the SOAP header sends the request to the API Gateway.
• API Gateway validates the signature of the SAML token using the public key of the STS 
• Upon successful validation, API Gateway sends request to native service.
• Native service sends the response to API Gateway 
• API Gateway forwards the response to client

Steps - SAML Inbound Bearer

• Create a SOAP API in API Gateway
• Edit the SOAP API and configure teh policy "Inbound Authentication - Message" with below parameter values as shown in image below. Configure the below values in Require SAML Token parameter.

SAML Subject Confirmation : Bearer of Token

WS-Trust : WS-Trust 1.3

SAML Version : 2.0

Issuer Address : https://HOSTNAME.DOMAIN.com/adfs/services/trust/13/UsernameMixed

Encrypt Signature : yes (since our ADFS encrypts)

Algorithm Suite : Basic256 (this is also ADFS based)

For configuring Require Security Token Template Parameters, go through http://docs.oasis-open.org/ws-sx/ws-trust/200512/ws-trust-1.3-os.html#_Toc162064989

• Configure "Add Require Encryption" ->  "Add Encrypted Parts"  as in image below. Configure "Header Name" as Assertion. Configure "Header Namespace" as  "urn:oasis:names:tc:SAML:2.0:assertion"

• Activate the service.
• Go to the ADFS machine and add the Gateway endpoint URL of the API Gateway API as a new Relying Party identifier in Relying Party Trusts

• In SAMLClient client project, configure the following.
  • In src\samlhokclient\TestSAMLBearer.java, configure locations of STS_POLICY_XML, CLIENT_BEARER_POLICY_XML, CLIENT_KEYSTORE and SSL_TRUSTSTORE_PROP
  • Set SIMPLE_SERVICE_EPR as endpoint of the above Gateway Service 
  • Set options.setTo(new EndpointReference(x)) where x is the endpoint of the above Gateway Service 
  • In SAMLClient\resources\client_bearer_policy.xml, configure the below in <rampart:encryptionCrypto><rampart:property name="org.apache.ws.security.crypto.merlin.truststore.file">C:\Work\Installations\keystoreTruststore\adminKeystore.jks</rampart:property>
• Execute the TestSAMLBearer.java. You will receive successful response.

SAML Inbound - Holder Of Key (Symmetric)

• Client sends a request to the STS for a SAML token with KeyType as SymmetricKey
• STS does the following.
  • STS generates a symmetric key as the proof key.
  • STS embeds the proof key to the SAML token and encrypts with relying party’s (API Gateway's) public key
  • STS signs the SAML token with its private key
  • STS Sends the SAML token and also the proof key in a separate element to the Client. 
• The proof key sent to the Client will be same that is encrpted and attached in the SAML token.
• The client embeds the SAML token in SOAP header, signs the SOAP request using the proof key and sends to API Gateway
• API Gateway does the following.
  • API Gateway validates the signature of the SAML token using the public key of the STS
  • API Gateway fetches the proof key by decrypting using its private key
  • API Gateway validates whether  signature from the client is matching with the proof key
• Upon successful validation, API Gateway sends request to native service.
• Native service sends the response to API Gateway 
• API Gateway forwards the response to client

Steps - SAML Holder Of Key (Symmetric)

• Create a SOAP API in API Gateway. 
• Edit the SOAP API and configure teh policy "Inbound Authentication - Message" with below parameter values as shown in image below.
  • Configure the below values in Require SAML Token parameter.

SAML Subject Confirmation : Holder of Key - Symmetric

WS-Trust : WS-Trust 1.3

SAML Version : 2.0

Issuer Address : https://HOSTNAME.DOMAIN.com/adfs/services/trust/13/UsernameMixed

Encrypt Signature : yes (since our ADFS encrypts)

Algorithm Suite : Basic256 (this is also ADFS based)

For configuring Require Security Token Template Parameters, go through http://docs.oasis-open.org/ws-sx/ws-trust/200512/ws-trust-1.3-os.html#_Toc162064989

• Activate the service.
• Go to the ADFS machine and add the Gateway endpoint URL of the API Gateway API as a new Relying Party identifier in Relying Party Trusts

• In SAMLClient client project, configure the following.
  • In src\samlhokclient\TestSAMLHOKSymmetric.java, configure locations of STS_POLICY_XML, CLIENT_HOK_POLICY_XML, CLIENT_KEYSTORE and SSL_TRUSTSTORE_PROP
  • Set SIMPLE_SERVICE_EPR as endpoint of the above Gateway Service 
  • Set options.setTo(new EndpointReference(x)) where x is the endpoint of the above Gateway Service 
  • In SAMLClient\resources\client_bearer_policy.xml, configure the below in <rampart:encryptionCrypto><rampart:property name="org.apache.ws.security.crypto.merlin.truststore.file">Location of adminKeystore.jks</rampart:property>
• Execute the TestSAMLHOKSymmetric.java. You will receive successful response

SAML Inbound - Holder Of Key (Public)

• Client sends a request to the STS for a SAML token with KeyType as PublicKey
• STS does the following.
  • STS uses Client’s public key as a proof key
  • STS embeds the proof key to the SAML token.
  • STS signs the SAML token with its private key
  • STS sends the SAML token to the Client. 
• The client embeds the SAML token in SOAP header, signs using its private key and sends the request to API Gateway.
• API Gateway does the following.
  • API Gateway validates the signature of the SAML token using the public key of STS
  • API Gateway fetches the proof key.
  • API Gateway validates whether signature from the client is matching with the proof key
• Upon successful validation, API Gateway sends request to native service.
• Native service sends the response to API Gateway 
• API Gateway forwards the response to client.

Steps - SAML Holder Of Key (Public)

• Create a SOAP API in API Gateway. 
• Edit the SOAP API and configure teh policy "Inbound Authentication - Message" with below parameter values as shown in image below.
  • Configure the below values in Require SAML Token parameter.

SAML Subject Confirmation : Holder of Key - Public

WS-Trust : WS-Trust 1.3

SAML Version : 2.0

Issuer Address : https://HOSTNAME.DOMAIN.com/adfs/services/trust/13/UsernameMixed

Encrypt Signature : yes (since our ADFS encrypts)

Algorithm Suite : Basic256 (this is also ADFS based)

For configuring Require Security Token Template Parameters, go through http://docs.oasis-open.org/ws-sx/ws-trust/200512/ws-trust-1.3-os.html#_Toc162064989

• Activate the service.
• Go to the ADFS machine and add the Gateway endpoint URL of the API Gateway API as a new Relying Party identifier in Relying Party Trusts
  
  
• In SAMLClient client project, configure the following.
  • In src\samlhokclient\TestSAMLHOKASymmetric.java, configure locations of STS_POLICY_XML, CLIENT_HOK_ASSYMMETRIC_POLICY_XML, CLIENT_KEYSTORE and SSL_TRUSTSTORE_PROP
  • Set SIMPLE_SERVICE_EPR as endpoint of the above Gateway Service 
  • Set options.setTo(new EndpointReference(x)) where x is the endpoint of the above Gateway Service 
  • In SAMLClient\resources\client_bearer_policy.xml, configure the below in <rampart:encryptionCrypto> and in <rampart:signatureCrypto><rampart:property name="org.apache.ws.security.crypto.merlin.truststore.file">Location of adminKeystore.jks</rampart:property> 
• Execute the TestSAMLHOKASymmetric.java. You will receive successful response.

Note: Only Holder Of Key (Symmetric) and Bearer are supported in ADFS. So we have tested SAML Inbound only for these two.
However, we can use this client zip package and use it for testing HoK(Public) when we get a ADFS setup or some other SAML Provider that supports HOK(Public).

SAML Outbound in API Gateway

API Gateway supports Outbound SAML Authentication from version 10.0.   The Subject Confirmation Methods supported in API Gateway Outbound SAML are given below.

1. Bearer
2. HOK Symmetric
3. HOK Asymmetric (not tested as ADFS doesn't support this)

Typically, the Outbound SAML Authentication in API Gateway follows the steps below, as shown in image above.

1. Client sends a request to API Gateway
2. API Gateway requests STS for SAML Token
3. STS sends the SAML token to the API Gateway.
4. API Gateway with the SAML token embedded in the SOAP header sends the request to native server
5. Native server authenticates the SAML token based on the Subject Confirmation(Bearer,HOK Symmetric ,HOK Asymmetric) used in the outbound SAML policy configured in API Gateway.
6. Upon successful authentication, native service sends the response to API Gateway 
7. API Gateway forwards the response to client.

Prerequisite Steps

Use steps in section 2.2.1 to configure prerequisites in ADFS machine (i.e, STS Provider). Also make sure, the certificates of Native Server (eg: administrator certificate) is configured in the keystore and certificates of STS is stored in truststore of  Relying party of STS (i.e, Native Server)

Prerequisite configurations in ADFS machine

• In the ADFS machine add a relying party trust with name PolicyGateway using administrator certificate
• In the Edit Claim Rules of PolicyGateway add the following claims
  • SAM-Account-Name ----> http://integration.fiserv.com/identity/claims/v1/FirstName

• Ensure the "Delegation Authorization Rules" is set to "Permit Access to All Users" or specific users in the active directory

Configurations in API Gateway

Configure Certificates in API Gateway

• Configure keystore in IS to adminKeystore. (Security → Keystore → Create Keystore Alias). The password is 'password'.
• Configure truststore in IS to samlOutboundTruststore.jks (Security → Keystore → Create Truststore Alias). The password is 'changeit'
• Go to "API Gateway → Security → Keystore/Truststore". Configure KeystoreAlias, KeyAlias (administrator) and Truststore Alias which is created in above 2 steps.

Configure SAML Issuer Alias in API Gateway

• Go to API Gateway → Administration → Security (tab) → SAML Issuer (on left pane)
• Click on "Add SAML Issuer" button.
• Configure the values for SAML Issuer as below
  • Choose "Normal Client"
  • Choose "Communicate Using" parameter as 'WSS Username'
  • Provide the credentials of the ADFS machine in "Custom Credentials"
  • Configure Endpoint uri as "https://vmchnadfs02w.sag.vmchnadfs20w.com/adfs/services/trust/13/usernamemixed"
  • Configure SAML Version as "2.0" and WS Trust Version 1.3
  • Click save.

SAML Outbound - Bearer and HOK (Symmetric)

Do the following steps for both Bearer and HOK (Symmetric) types.

• Create an API using the Native Service from the Native Server which acts as a SAML Relying Party and protects its service using SAML
• Go to the api and configure "Soap 1.2" as SOAP version in Policies → Transport Level → "Require HTTP/HTTPS" policy
  
• Go to Policies → Routing and add "Outbound Authentication - Message" policy. Configure the below values.
  • Select "Authentication Scheme" as "SAML"
  • Select the SAML issuer configured in step 2.2.2.2 for "SAML Issuer"  (eg: samlIssuer1)
  • Configure the Encryption Configurations using the truststore configured in API Gateway in step "Configure Certificates in API Gateway"

SAML Outbound - HOK (Public)

SAML Outbound - HOK (Public) is not tested in API Gateway as ADFS doesn't support SAML with HOK(Public).

Limitations

• SAML authentication is supported only for SOAP APIs and not supported for REST and Websocket APIs

Downloadable artifacts

• SAMLClient.zip
• ADFS_Sign_Machine_Cert.jks
• Administrator.der
• adminKeystore.jks
• adminKeystore.pfx
• JCE Java library.zip
• samlOutboundTruststore.jks

ADFS_Sign_Machine_Cert.jks (826 Bytes)

Administrator.der (1.2 KB)

adminKeystore.jks (935 Bytes)

adminKeystore.pfx (2.53 KB)

JCE Java library.zip (8.21 KB)

SAMLClient.zip (139 KB)

samlOutboundTruststore.jks (1.69 KB)