Virtual Federation (as known as Secure Attributes Exchange or SAE) : Sample
This sample demonstrates usage of Virtual Federation feature.
Actors :
(1) OpenAM-IDP : OpenAM setup as samlv2 IDP.
(2) OpenAM-SP : OpenAM setup as samlv2 SP.
(3) samplesaml2cot : Circle of Trust comprising OpenAM-IDP and OpenAM-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 --- OpenAM-IDP -|- samlv2 -|- OpenAM-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 OpenAM-IDP.
- Setting up trust relationship between SP-App and OpenAM-SP.
- Passing user Authentication information from IDP-App to OpenAM-IDP.
- Passing user attribute information from IDP-App to OpenAM-IDP.
- Using OpenAM-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 OpenAM 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 OpenAM-IDP instance and saeAppSP.jsp on OpenAM-SP instances. In this case, assume
IDP-App_protocol=OpenAM-IDP_protocol
IDP-App_host=OpenAM-IDP_host
IDP-App_port=OpenAM-IDP_port
IDP-App_uri=OpenAM-IDP_uri
SP-App_protocol=OpenAM-SP_protocol
SP-App_host=OpenAM-SP_host
SP-App_port=OpenAM-SP_port
SP-App_uri=OpenAM-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 OpenAM-IDP via Symmetric Method or Asymmetric Method.
Symmetric Method :
(3a) Choose a shared secret to be used between IDP-App and OpenAM-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 OpenAM-IDP. e.g. "demo".
(iv) initialize the idpAppName variable to a string that uniquely identifies this IDP-App.
(v) initialize the saeServiceURL parameter to : <OpenAM-IDP_protocol>://<OpenAM-IDP_host>:<OpenAM-IDP_port>/<OpenAM-IDP_uri>/idpsaehandler/metaAlias/idp
[Note: here we assume the meta alias for OpenAM-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 OpenAM-IDP, goto "Federation" tab, then click the hosted OpenAM-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 OpenAM-IDP instance) of the shared secret between IDP-app and OpenAM-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 OpenAM-IDP, goto "Federation" tab, then click the remote OpenAM-SP entity.
Goto the "Assertion Processing" tab, and add the attributes to be sent as part of the saml assertion to OpenAM-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:
<OpenAM-SP_protocol>://<OpenAM-SP_host>:<OpenAM-SP_port>/<OpenAM-SP_uri>/spsaehandler/metaAlias/sp
[Note: here we assume the meta alias for OpenAM-SP is "sp"]
Asymmetric Method :
(3a) Obtain a private-public key pair to be used between the IDP-App and OpenAM-IDP. Store the key pair in a secure keystore on IDP-App side.
Add the public key to the keystore in OpenAM-IDP (see saml2 docs), write down the certificate alias which is needed in step (3c).
If plan to use data encryption, add OpenAM-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 OpenAM-IDP. e.g. "demo".
(iv) initialize the idpAppName variable to a string that uniquely identifies this IDP-App
(v) initialize the saeServiceURL parameter to : <OpenAM-IDP_protocol>://<OpenAM-IDP_host>:<OpenAM-IDP_port>/<OpenAM-IDP_uri>/idpsaehandler/metaAlias/idp
[Note: here we assume the meta alias for OpenAM-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 OpenAM-IDP.
(3c) Logon to the administration console of OpenAM-IDP, goto "Federation" tab, then click the hosted OpenAM-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 OpenAM-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 OpenAM-IDP, goto "Federation" tab, then click the remote OpenAM-SP entity.
Goto the "Assertion Processing" tab, and add the attributes to be sent as part of the saml assertion to OpenAM-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:
<OpenAM-SP_protocol>://<OpenAM-SP_host>:<OpenAM-SP_port>/<OpenAM-SP_uri>/spsaehandler/metaAlias/sp
[Note: here we assume the meta alias for OpenAM-SP is "sp"]
Step 4 : Establish trust between SP-App and OpenAM-SP via Symmetric Method or Asymmetric Method.
Symmetric Method:
(4a) Choose a shared secret to be used between SP-App and OpenAM-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 OpenAM-SP, goto "Federation" tab, then click the hosted OpenAM-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 OpenAM-SP instance) of the shared secret between SP-app and OpenAM-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 OpenAM-SP. Store the key pair in a secure keystore on SP-App side.
Add OpenAM-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 OpenAM-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 OpenAM-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 OpenAM-SP, goto "Federation" tab, then click the hosted OpenAM-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=<OpenAM-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";
<OpenAM-SP_signing_certalias> is the alias name of the OpenAM-SP signing certificate stored in the key store of OpenAM-SP. If you don't configure OpenAM-SP signing certificate here, it will use the signing certificate configured in OpenAM-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 OpenAM-IDP :
logged in username, attributes (mail, branch).
Clicking on "Send Attributes" will securely invoke saeAppSP.jsp on SP-App.
Troubleshooting
OpenAM 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 OpenAM session.
--