Virtual Federation (as known as Secure Attributes Exchange or SAE) : Sample

This sample demonstrates usage of Virtual Federation feature.

Actors :
(1) OpenSSO-IDP : OpenSSO setup as samlv2 IDP.
(2) OpenSSO-SP : OpenSSO setup as samlv2 SP.
(3) samplesaml2cot : Circle of Trust comprising OpenSSO-IDP and OpenSSO-SP.
(4) IDP-App : A web application hosted on IDP end (saeIDPApp.jsp).
(5) SP-App : A web application hosted on SP end (saeSPApp.jsp).


IDP-App --- sae --- OpenSSO-IDP -|- samlv2 -|- OpenSSO-SP --- sae --- SP-App

The detailed steps listed below will help you learn the following aspects of Virtual Federation:
- Setting up trust relationship between IDP-App and OpenSSO-IDP.
- Setting up trust relationship between SP-App and OpenSSO-SP.
- Passing user Authentication information from IDP-App to OpenSSO-IDP.
- Passing user attribute information from IDP-App to OpenSSO-IDP.
- Using OpenSSO-IDP as a gateway to access SP-App.
- Consuming authentication and attribute data in SP-App.

Detailed Steps

Step 1 : Perform initial SAMLv2 install & setup as in OpenSSO SAMLv2 Sample Setup section.
In effect we are creating two domains that will communicate over SAMLv2.

Step 2 : Deploy saeAppIDP.jsp and saeAppSP.jsp on the respective domains. For simplicity you may choose to use the predeployed saeAppIDP.jsp on OpenSSO-IDP instance and saeAppSP.jsp on OpenSSO-SP instances. In this case, assume
IDP-App_protocol=OpenSSO-IDP_protocol
IDP-App_host=OpenSSO-IDP_host
IDP-App_port=OpenSSO-IDP_port
IDP-App_uri=OpenSSO-IDP_uri
SP-App_protocol=OpenSSO-SP_protocol
SP-App_host=OpenSSO-SP_host
SP-App_port=OpenSSO-SP_port
SP-App_uri=OpenSSO-SP_uri
in the following configuration steps. A more common deployment scenario is to install them in their own web applications.

Step 3 : Establish trust between IDP-App and OpenSSO-IDP via Symmetric Method or Asymmetric Method.
Symmetric Method :
(3a) Choose a shared secret to be used between IDP-App and OpenSSO-IDP. If data encryption is used, the same secret is used for data encryption as well.
(3b) saeIDPApp.jsp is factored as a form that will prompt for these values, but you may choose to edit it to :
(i) initialize cryptotype variable to "symmetric"
(ii) initialize the secret variable to shared secret string.
[ Note - in a real deployment the app should store this secret on disk by encrypting it in a file and keeping the file safe. ]
(iii) initialize the userid variable to the user id on the OpenSSO-IDP. e.g. "demo".
(iv) initialize the idpAppName variable to a string that uniquely identifies this IDP-App.
(v) initialize the saeServiceURL parameter to : <OpenSSO-IDP_protocol>://<OpenSSO-IDP_host>:<OpenSSO-IDP_port>/<OpenSSO-IDP_uri>/idpsaehandler/metaAlias/idp
[Note: here we assume the meta alias for OpenSSO-IDP is "idp"]
(vi) initialize the spapp variable to the SP-App URL, e.g. <SP-App_protocol>://<SP-App_host>:<SP-App_port>/<SP-App_uri>/samples/saml2/sae/saeSPApp.jsp
(vii) If data encryption is used, change encryptionAlg and encryptionStrength if needed. encSecret is set to be the same as secret.
(3c) Logon to the administration console of OpenSSO-IDP, goto "Federation" tab, then click the hosted OpenSSO-IDP entity.
Goto the "Advanced" tab, and add following value to the "Per Application Security Configuration" field:
url=<IDP-App_URL>|type=symmetric|secret=<encoded_shared_secret>[|encryptionalgorithm=<encAlg>|encryptionkeystrength=<encStrength>]
where <IDP-App_URL> is the IDP-App URL, e.g. <IDP-App_protocol>://<IDP-App_host>:<IDP-App_port>/<IDP-App_uri>/samples/saml2/sae/saeIDPApp.jsp,
<encoded_shared_secret> is the encoded value (using encode.jsp from browser or ampassword from CLI on OpenSSO-IDP instance) of the shared secret between IDP-app and OpenSSO-IDP,
if data encryption is enabled, configure encryptionalgorithm and encryptionkeystrength attributes such as: encryptionalgorithm=DES|encryptionkeystrength=56
Click "Save" button to save the change.
(3d) Logon to the administration console of OpenSSO-IDP, goto "Federation" tab, then click the remote OpenSSO-SP entity.
Goto the "Assertion Processing" tab, and add the attributes to be sent as part of the saml assertion to OpenSSO-SP in the "Attribute Map" field. Click "Save" to store the change.
[Note: one of the attributes configured here will be used as auto federation attribute in step (4c).]
Goto the "Advanced" tab, set value for the "SP URL" field as follows:
<OpenSSO-SP_protocol>://<OpenSSO-SP_host>:<OpenSSO-SP_port>/<OpenSSO-SP_uri>/spsaehandler/metaAlias/sp
[Note: here we assume the meta alias for OpenSSO-SP is "sp"]
Asymmetric Method :
(3a) Obtain a private-public key pair to be used between the IDP-App and OpenSSO-IDP. Store the key pair in a secure keystore on IDP-App side.
Add the public key to the keystore in OpenSSO-IDP (see saml2 docs), write down the certificate alias which is needed in step (3c).
If plan to use data encryption, add OpenSSO-IDP's public key to the keystore on IDP-App side. Write down the certificate alias which is needed in step (3c).
(3b)saeIDPApp.jsp is factored as a form that will prompt for these values, but you may choose to edit it to :
(i) initialize cryptotype variable to "asymmetric"
(ii) initialize the secret variable to IDP-App private key alias string.
[Note - in a real deployment the app should store private key in a secure keystore. ]
(iii) initialize the userid variable to the user id on the OpenSSO-IDP. e.g. "demo".
(iv) initialize the idpAppName variable to a string that uniquely identifies this IDP-App
(v) initialize the saeServiceURL parameter to : <OpenSSO-IDP_protocol>://<OpenSSO-IDP_host>:<OpenSSO-IDP_port>/<OpenSSO-IDP_uri>/idpsaehandler/metaAlias/idp
[Note: here we assume the meta alias for OpenSSO-IDP is "idp"]
(vi) initialize the spapp variable to the SP-App URL, e.g. <SP-App_protocol>://<SP-App_host>:<SP-App_port>/<SP-App_uri>/samples/saml2/sae/saeSPApp.jsp
(vii) If data encryption is used, change encSecret, encryptionAlg and encryptionStrength if needed. encSecret is the public key alias of OpenSSO-IDP.
(3c) Logon to the administration console of OpenSSO-IDP, goto "Federation" tab, then click the hosted OpenSSO-IDP entity.
Goto the "Advanced" tab, and add following value to the "Per Application Security Configuration" field:
url=<IDP-App_URL>|type=asymmetric|pubkeyalias=<IDP-App_public_key_certalias>[|encrytionalgorithm=<encAlg>|encryptionkeystrength=<encStrength>]
where <IDP-App_URL> is the IDP-App URL, e.g. "<IDP-App_protocol>://<IDP-App_host>:<IDP-App_port>/<IDP-App_uri>/samples/saml2/sae/saeIDPApp.jsp";
<IDP-App_public_key_certalias> is the alias name of the IDP-App public certificate stored in the key store of OpenSSO-IDP done in step (3a).
If data encryption is used, configure encryptionalgorithm and encryptionkeystrength attributes. Click "Save" button to save the change.
(3d) Logon to the administration console of OpenSSO-IDP, goto "Federation" tab, then click the remote OpenSSO-SP entity.
Goto the "Assertion Processing" tab, and add the attributes to be sent as part of the saml assertion to OpenSSO-SP in the "Attribute Map" field. Click "Save" to store the change.
Goto the "Advanced" tab, set value for the "SP URL" field as follows:
<OpenSSO-SP_protocol>://<OpenSSO-SP_host>:<OpenSSO-SP_port>/<OpenSSO-SP_uri>/spsaehandler/metaAlias/sp
[Note: here we assume the meta alias for OpenSSO-SP is "sp"]


Step 4 : Establish trust between SP-App and OpenSSO-SP via Symmetric Method or Asymmetric Method.
Symmetric Method:
(4a) Choose a shared secret to be used between SP-App and OpenSSO-SP. If data encryption is used, the same shared secret is used for data encryption as well.
(4b) Edit saeSPApp.jsp to :
(i) initialize cryptotype variable to "symmetric"
(ii) initialize the secret variable to the shared secret string.
[ Note - in a real deployment the app should store this secret on disk by encrypting it in a file and keeping the file safe. ].
(iii) If data encryption is used, modify encAlg and encStrength if needed.
(4c) Logon to the administration console of OpenSSO-SP, goto "Federation" tab, then click the hosted OpenSSO-SP entity.
* Goto the "Assertion Processing" tab, and add the attributes mapping in the "Attribute Map" field. Under "Auto Federation" section, check the "Enabled" box, and enter the auto federation attribute name (e.g. "mail") in the "Attribute" field. Click "Save" to store the change.
[Note : the value of the auto federation attribute on the IDP and SP user entries must be the same in order for the auto federation feature to work. In case there is no user exist on SP side, you can goto Access Control -> <your realm> -> Authentication -> Advanced Properties page, and set the "User Profile" filed to "Ignore".]
* Goto the "Advanced" tab, add a value in the "Per Application Security Configuration" field as follows:
url=<SP-App_URL>|type=symmetric|secret=<encoded_shared_secret>[|encryptionalgorithm=<|encryptionkeystrength>]
where <SP-App_URL> is the SP-App URL, e.g. "<SP-App_protocol>://<SP-App_host>:<SP-App_port>/<SP-App_uri>/samples/saml2/sae/saeSPApp.jsp";
<encoded_shared_secret> is the encoded value (using encode.jsp from browser or ampassword from CLI on OpenSSO-SP instance) of the shared secret between SP-app and OpenSSO-SP.
If data encryption is used, configure encryptionalgorithm and encryptionkeystrength attributes, such as encryptionalgorithm=DES|encryptionkeystrength=56
* Set SP-App logout URL in the "SP Logout URL" field if application logout needed. e.g. "<SP-App_protocol>://<SP-App_host>:<SP-App_port>/<SP-App_uri>/samples/saml2/sae/saeSPApp.jsp". Click "Save" button to save the change. .
Asymmetric Method:
(4a) Obtain a private-public key pair to be used between SP-App and OpenSSO-SP. Store the key pair in a secure keystore on SP-App side.
Add OpenSSO-SP's public key to the keystore on SP-App. Write down the certificate alias which is needed in step (4b). If data encryptioned is used, add SP-App public key to the keystore on OpenSSO-SP (see saml2 docs), write down the certificate alias which is needed in step (4c).

(4b) Edit saeSPApp.jsp to :
(i) initialize cryptotype variable to "asymmetric"
(ii) initialize the secret variable to the alias of OpenSSO-SP's public key.
(iii) If data encryption is enabled, initialize the encSecret variable to the alias of SP-App's private key. Modify encAlg and encStrength variables if needed.
(4c) Logon to the administration console of OpenSSO-SP, goto "Federation" tab, then click the hosted OpenSSO-SP entity.
* Goto the "Assertion Processing" tab, and add the attributes mapping in the "Attribute Map" field. Under "Auto Federation" section, check the "Enabled" box, and enter the auto federation attribute name (e.g. "mail") in the "Attribute" field. Click "Save" to store the change.
[Note : the value of the auto federation attribute on the IDP and SP user entries must be the same in order for the auto federation feature to work. In case there is no user exist on SP side, you can goto Access Control -> <your realm> -> Authentication -> Advanced Properties page, and set the "User Profile" filed to "Ignore".]
* Goto the "Advanced" tab, add a value in the "Per Application Security Configuration" field as follows:
url=<SP-App_URL>|type=asymmetric|privatekeyalias=<OpenSSO-SP_signing_certalias>[|pubkeyalias=<SP-App_public_certalias>|encryptionalgorithm=<encAlg>|encryptionkeystrength=<encStrength>]
where <SP-App_URL> is the SP-App URL, e.g. "<SP-App_protocol>://<SP-App_host>:<SP-App_port>/<SP-App_uri>/samples/saml2/sae/saeSPApp.jsp";
<OpenSSO-SP_signing_certalias> is the alias name of the OpenSSO-SP signing certificate stored in the key store of OpenSSO-SP. If you don't configure OpenSSO-SP signing certificate here, it will use the signing certificate configured in OpenSSO-SP's extended metadata.
If data encryption is used, configure pubkeyalias, encryptionalgorithm and encryptionkeystrength. pubkeyalias is SP-App's public certificate alias.
* Set SP-App logout URL in the "SP Logout URL" field if application logout needed. e.g. "<SP-App_protocol>://<SP-App_host>:<SP-App_port>/<SP-App_uri>/samples/saml2/sae/saeSPApp.jsp". Click "Save" button to save the change.


Step 5 : Execute the sample.
Start a browser and access <IDP-App_protocol>://<IDP-App_host>:<IDP-App_port>/<IDP-App_uri>/samples/saml2/sae/saeIDPApp.jsp
Fill up the form with the values you want communicated to OpenSSO-IDP :
logged in username, attributes (mail, branch).
Clicking on "Send Attributes" will securely invoke saeAppSP.jsp on SP-App.

Troubleshooting
OpenSSO Debug files : Virtual Federation and samlv2 on IDP and SP ends.
dumpcookies.jsp can be deployed on SP/IDP ends to view http headers and OpenSSO session.
--