Enabling XML Signing and Decryption in the OpenSSO Java Fedlet

The OpenSSO Fedlet is a small archive of JARs and metadata (stored in flat files) that can be embedded into a service provider's Java EE web application to allow for single sign-on between an identity provider instance of OpenSSO and the service provider application - WITHOUT installing OpenSSO on the service provider side. The Fedlet is created using the OpenSSO console. More information is in the OpenSSO Enterprise 8.0 Deployment Planning Guide or in the OpenSSO Enterprise 8.0 Technical Overview. Additional information can be found in the blog entry, The Fedlet Cyrkle of Information.

About XML Signing

XML signatures verify the identity of the sender and/or receiver in XML transactions. To create a digital signature, the data to be signed is transformed by an algorithm that takes as input the sender's private key. The verification process on the receiver side checks the signature using the signed message and the sender's public key (sent with the signed message). Assuming the data is verified using the sender's public key, the recipient of the transformed data can be confident of the identity of the sender. (A certificate issued by a Certificate Authority can also be included to assert that the public key does indeed correspond to the subject that claims it.) Thus, in the case of XML signatures:

  1. The sender of the message uses its own private key to digitally sign the message to be sent.
  2. The receiver of the message uses the sender's corresponding public key to verify the signature.

About XML Encryption

XML encryption provides a secure way in which applications can exchange structured data. There are two pieces of data in an encrypted response: an encrypted key and the encrypted data. The encrypted key is a symmetric key encrypted using the receiver's public key. The encrypted data is the XML element (an assertion, name identifier or attribute) encrypted using the symmetric key. The receiver uses its private key to decrypt the symmetric key and then uses the symmetric key to decrypt the encrypted data. No entity (other than the one that owns the corresponding private key) can decrypt the message. (A certificate issued by a Certificate Authority can also be included to assert that the private key does indeed correspond to the subject that claims it.) Thus, in the case of XML encryption:

  1. The sender of the message uses the receiver's public key to encrypt the key which encrypts the content.
  2. The receiver of the message uses the corresponding private key, which it owns, to decrypt the key which is then used to decrypt the content.

XML Signing and Encryption in the Fedlet

The Fedlet now supports XML signature verification, and decryption of encrypted assertion and nameid elements (and their corresponding attributes). Before the Fedlet is deployed though, you need to set up your environment and enable the appropriate attributes. The following sections contain the procedures.

Setting Up for XML Signing and Encryption on the Fedlet Side

This procedure assumes a Fedlet has been created using the identity provider's OpenSSO console, sent to the appropriate service provider, and deployed by the service provider.

NOTE: Instructions for creating the Fedlet can be found in the blog entry, The Fedlet Cyrkle of Information.

The steps below need to be completed by the service provider.

  1. Create a keystore file named keystore.jks using the keytool command line interface. Instructions on how to create a keystore can be found in the OpenSSO Enterprise 8.0 documentation.
  2. Add the private key (and public certificate if applicable) used for signing and the private key (and public certificate if applicable) used for encryption to the keystore.jks.
  3. Create a .storepass file.
  4. Use one of the following options to populate .storepass with the password used to access keystore.jks.
    1. Add the password to .storepass in clear text.
    2. Add an encrypted password to .storepass by following this sub procedure.
      1. Encrypt the password and save it to .storepass.
      2. Write a customized implementation of the com.sun.identity.saml.xmlsig.PasswordDecoder service provider interface (SPI). Be sure to include the
        public String getDecodedPassword (String encodedPwd); method which takes the encrypted password and returns it in clear text.
      3. Add the implementation class to the /fedlet/WEB-INF/classes configuration directory.
      4. Set the value of the com.sun.identity.saml.xmlsig.passwordDecoder property in /fedlet/FederationConfig.properties to the class path of the password decoder implementation class.
      5. Restart the web container on which the Fedlet is deployed. NOTE: If you use this encrypted password sub procedure, you do not need to restart the web container until you have made the additional changes below.
  5. Create a .keypass file.
  6. Use one of the following options to populate .keypass with the password to access the private key used for signing and the password to access the private key used for encryption.
    1. Add the password to .keypass in clear text.
    2. Add an encrypted password to .keypass using this sub procedure.
      1. Encrypt the password and save it to .keypass.
      2. Provide a customized implementation of the com.sun.identity.saml.xmlsig.PasswordDecoder SPI. Be sure to include the
        public String getDecodedPassword (String encodedPwd); method which takes the encrypted password and returns it in clear text.
      3. Add the implementation class to the ((/fedlet/WEB-INF/classes}} directory.
      4. Set the value of the com.sun.identity.saml.xmlsig.passwordDecoder property in /fedlet/FederationConfig.properties to the class path of the password decoder implementation class.
      5. Restart the web container on which the Fedlet is deployed. NOTE: If you use this encrypted password sub procedure, you do not need to restart the web container until you have made the additional changes below.
  7. Set the appropriate path in the following attributes in /fedlet/FederationConfig.properties.
    • com.sun.identity.saml.xmlsig.keystore=path/keystore.jks
    • com.sun.identity.saml.xmlsig.storepass=path/.storepass
    • com.sun.identity.saml.xmlsig.keypass=path/.keypass
  8. Use keytool to export the signing certificate. For example:
    keytool -export -keystore keystore.jks -rfc -alias test
    You will be prompted to enter the password used to access keystore.jks. The certificate will then be generated.
    Sample Certificate
    --BEGIN CERTIFICATE--
MIICQDCCAakCBEeNB0swDQYJKoZIhvcNAQEEBQAwZzELMAkGA1UEBhMCVVMxEzARBgNVBAgTCkNh
bGlmb3JuaWExFDASBgNVBAcTC1NhbnRhIENsYXJhMQwwCgYDVQQKEwNTdW4xEDAOBgNVBAsTB09w
ZW5TU08xDTALBgNVBAMTBHRlc3QwHhcNMDgwMTE1MTkxOTM5WhcNMTgwMTEyMTkxOTM5WjBnMQsw
CQYDVQQGEwJVUzETMBEGA1UECBMKQ2FsaWZvcm5pYTEUMBIGA1UEBxMLU2FudGEgQ2xhcmExDDAK
BgNVBAoTA1N1bjEQMA4GA1UECxMHT3BlblNTTzENMAsGA1UEAxMEdGVzdDCBnzANBgkqhkiG9w0B
AQEFAAOBjQAwgYkCgYEArSQc/U75GB2AtKhbGS5piiLkmJzqEsp64rDxbMJ+xDrye0EN/q1U5Of\+
RkDsaN/igkAvV1cuXEgTL6RlafFPcUX7QxDhZBhsYF9pbwtMzi4A4su9hnxIhURebGEmxKW9qJNY
Js0Vo5+IgjxuEWnjnnVgHTs1+mq5QYTA7E6ZyL8CAwEAATANBgkqhkiG9w0BAQQFAAOBgQB3Pw/U
QzPKTPTYi9upbFXlrAKMwtFf2OW4yvGWWvlcwcNSZJmTJ8ARvVYOMEVNbsT4OFcfu2/PeYoAdiDA
cGy/F2Zuj8XJJpuQRSE6PtQqBuDEHjjmOQJ0rV/r8mO1ZCtHRhpZ5zYRjhRC9eCbjx9VrFax0JDC
/FfwWigmrW0Y0Q==
--END CERTIFICATE--
  9. Repeat the previous step to export the encryption certificate if applicable. You can also use the same certificate for both.
  10. Create a KeyDescriptor XML block and add the signing certificate to it. Note the use=signing tag of the KeyDescriptor element.
    Sample KeyDescriptor Code for Signing
    <KeyDescriptor use="signing">
<ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
<ds:X509Data>
<ds:X509Certificate>
MIICQDCCAakCBEeNB0swDQYJKoZIhvcNAQEEBQAwZzELMAkGA1UEBhMCVVMxEzARBgNVBAgTCkNh
bGlmb3JuaWExFDASBgNVBAcTC1NhbnRhIENsYXJhMQwwCgYDVQQKEwNTdW4xEDAOBgNVBAsTB09w
ZW5TU08xDTALBgNVBAMTBHRlc3QwHhcNMDgwMTE1MTkxOTM5WhcNMTgwMTEyMTkxOTM5WjBnMQsw
CQYDVQQGEwJVUzETMBEGA1UECBMKQ2FsaWZvcm5pYTEUMBIGA1UEBxMLU2FudGEgQ2xhcmExDDAK
BgNVBAoTA1N1bjEQMA4GA1UECxMHT3BlblNTTzENMAsGA1UEAxMEdGVzdDCBnzANBgkqhkiG9w0B
AQEFAAOBjQAwgYkCgYEArSQc/U75GB2AtKhbGS5piiLkmJzqEsp64rDxbMJ+xDrye0EN/q1U5Of\+
RkDsaN/igkAvV1cuXEgTL6RlafFPcUX7QxDhZBhsYF9pbwtMzi4A4su9hnxIhURebGEmxKW9qJNY
Js0Vo5+IgjxuEWnjnnVgHTs1+mq5QYTA7E6ZyL8CAwEAATANBgkqhkiG9w0BAQQFAAOBgQB3Pw/U
QzPKTPTYi9upbFXlrAKMwtFf2OW4yvGWWvlcwcNSZJmTJ8ARvVYOMEVNbsT4OFcfu2/PeYoAdiDA
cGy/F2Zuj8XJJpuQRSE6PtQqBuDEHjjmOQJ0rV/r8mO1ZCtHRhpZ5zYRjhRC9eCbjx9VrFax0JDC
/FfwWigmrW0Y0Q==
</ds:X509Certificate>
</ds:X509Data>
</ds:KeyInfo>
</KeyDescriptor>
  11. Create a KeyDescriptor XML block and add the encryption certificate to it. Note the use=encryption tag of the KeyDescriptor element. You may choose a different KeySize or EncryptionMethod.
    Sample KeyDescriptor Code for Encryption
    <KeyDescriptor use="encryption">
<KeyInfo xmlns="http://www.w3.org/2000/09/xmldsig#">
<X509Data>
<X509Certificate>
MIICQDCCAakCBEeNB0swDQYJKoZIhvcNAQEEBQAwZzELMAkGA1UEBhMCVVMxEzARBgNVBAgTCkNh
bGlmb3JuaWExFDASBgNVBAcTC1NhbnRhIENsYXJhMQwwCgYDVQQKEwNTdW4xEDAOBgNVBAsTB09w
ZW5TU08xDTALBgNVBAMTBHRlc3QwHhcNMDgwMTE1MTkxOTM5WhcNMTgwMTEyMTkxOTM5WjBnMQsw
CQYDVQQGEwJVUzETMBEGA1UECBMKQ2FsaWZvcm5pYTEUMBIGA1UEBxMLU2FudGEgQ2xhcmExDDAK
BgNVBAoTA1N1bjEQMA4GA1UECxMHT3BlblNTTzENMAsGA1UEAxMEdGVzdDCBnzANBgkqhkiG9w0B
AQEFAAOBjQAwgYkCgYEArSQc/U75GB2AtKhbGS5piiLkmJzqEsp64rDxbMJ+xDrye0EN/q1U5Of\+
RkDsaN/igkAvV1cuXEgTL6RlafFPcUX7QxDhZBhsYF9pbwtMzi4A4su9hnxIhURebGEmxKW9qJNY
Js0Vo5+IgjxuEWnjnnVgHTs1+mq5QYTA7E6ZyL8CAwEAATANBgkqhkiG9w0BAQQFAAOBgQB3Pw/U
QzPKTPTYi9upbFXlrAKMwtFf2OW4yvGWWvlcwcNSZJmTJ8ARvVYOMEVNbsT4OFcfu2/PeYoAdiDA
cGy/F2Zuj8XJJpuQRSE6PtQqBuDEHjjmOQJ0rV/r8mO1ZCtHRhpZ5zYRjhRC9eCbjx9VrFax0JDC
/FfwWigmrW0Y0Q==
</X509Certificate>
</X509Data>
</KeyInfo>
<EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#aes128-cbc">
<KeySize xmlns="http://www.w3.org/2001/04/xmlenc#">128</KeySize>
</EncryptionMethod>
</KeyDescriptor>
  12. Add the XML blocks with the signing and encryption certificates to /fedlet/sp.xml. Put the blocks under the SPSSODescriptor element.
    Sample SPSSODescriptor Element
    {{<EntityDescriptor entityID="fedlet" xmlns="urn:oasis:names:tc:SAML:2.0:metadata">
<SPSSODescriptor AuthnRequestsSigned="true" WantAssertionsSigned="false"
protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
<b><KeyDescriptor use="signing">
<ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
<ds:X509Data>
<ds:X509Certificate>
MIICQDCCAakCBEeNB0swDQYJKoZIhvcNAQEEBQAwZzELMAkGA1UEBhMCVVMxEzARBgNVBAgTCkNh
bGlmb3JuaWExFDASBgNVBAcTC1NhbnRhIENsYXJhMQwwCgYDVQQKEwNTdW4xEDAOBgNVBAsTB09w
ZW5TU08xDTALBgNVBAMTBHRlc3QwHhcNMDgwMTE1MTkxOTM5WhcNMTgwMTEyMTkxOTM5WjBnMQsw
CQYDVQQGEwJVUzETMBEGA1UECBMKQ2FsaWZvcm5pYTEUMBIGA1UEBxMLU2FudGEgQ2xhcmExDDAK
BgNVBAoTA1N1bjEQMA4GA1UECxMHT3BlblNTTzENMAsGA1UEAxMEdGVzdDCBnzANBgkqhkiG9w0B
AQEFAAOBjQAwgYkCgYEArSQc/U75GB2AtKhbGS5piiLkmJzqEsp64rDxbMJ+xDrye0EN/q1U5Of\+
RkDsaN/igkAvV1cuXEgTL6RlafFPcUX7QxDhZBhsYF9pbwtMzi4A4su9hnxIhURebGEmxKW9qJNY
Js0Vo5+IgjxuEWnjnnVgHTs1+mq5QYTA7E6ZyL8CAwEAATANBgkqhkiG9w0BAQQFAAOBgQB3Pw/U
QzPKTPTYi9upbFXlrAKMwtFf2OW4yvGWWvlcwcNSZJmTJ8ARvVYOMEVNbsT4OFcfu2/PeYoAdiDA
cGy/F2Zuj8XJJpuQRSE6PtQqBuDEHjjmOQJ0rV/r8mO1ZCtHRhpZ5zYRjhRC9eCbjx9VrFax0JDC
/FfwWigmrW0Y0Q==
</ds:X509Certificate>
</ds:X509Data>
</ds:KeyInfo>
</KeyDescriptor></b>
<b><KeyDescriptor use="encryption">
<KeyInfo xmlns="http://www.w3.org/2000/09/xmldsig#">
<X509Data>
<X509Certificate>
MIICQDCCAakCBEeNB0swDQYJKoZIhvcNAQEEBQAwZzELMAkGA1UEBhMCVVMxEzARBgNVBAgTCkNh
bGlmb3JuaWExFDASBgNVBAcTC1NhbnRhIENsYXJhMQwwCgYDVQQKEwNTdW4xEDAOBgNVBAsTB09w
ZW5TU08xDTALBgNVBAMTBHRlc3QwHhcNMDgwMTE1MTkxOTM5WhcNMTgwMTEyMTkxOTM5WjBnMQsw
CQYDVQQGEwJVUzETMBEGA1UECBMKQ2FsaWZvcm5pYTEUMBIGA1UEBxMLU2FudGEgQ2xhcmExDDAK
BgNVBAoTA1N1bjEQMA4GA1UECxMHT3BlblNTTzENMAsGA1UEAxMEdGVzdDCBnzANBgkqhkiG9w0B
AQEFAAOBjQAwgYkCgYEArSQc/U75GB2AtKhbGS5piiLkmJzqEsp64rDxbMJ+xDrye0EN/q1U5Of\+
RkDsaN/igkAvV1cuXEgTL6RlafFPcUX7QxDhZBhsYF9pbwtMzi4A4su9hnxIhURebGEmxKW9qJNY
Js0Vo5+IgjxuEWnjnnVgHTs1+mq5QYTA7E6ZyL8CAwEAATANBgkqhkiG9w0BAQQFAAOBgQB3Pw/U
QzPKTPTYi9upbFXlrAKMwtFf2OW4yvGWWvlcwcNSZJmTJ8ARvVYOMEVNbsT4OFcfu2/PeYoAdiDA
cGy/F2Zuj8XJJpuQRSE6PtQqBuDEHjjmOQJ0rV/r8mO1ZCtHRhpZ5zYRjhRC9eCbjx9VrFax0JDC
/FfwWigmrW0Y0Q==
</X509Certificate>
</X509Data>
</KeyInfo>
<EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#aes128-cbc">
<KeySize xmlns="http://www.w3.org/2001/04/xmlenc#">128</KeySize>
</EncryptionMethod>
</KeyDescriptor></b>
<NameIDFormat>urn:oasis:names:tc:SAML:2.0:nameid-format:transient</NameIDFormat>
<AssertionConsumerService index="1" Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
Location="http://server.sun.com:7070/fedlet/fedletapplication"/>
</SPSSODescriptor>
</EntityDescriptor>

    Note that the AuthnRequestsSigned attribute is set to true configuring the Fedlet to sign all authentication requests.

  13. Set the values of the following attributes in the Fedlet's extended metadata located in /fedlet/sp-extended.xml.
    • signingCertAlias contains the alias of the XML signing certificate in the keystore. In this procedure, test was used.
    • encryptionCertAlias contains the alias of the XML encryption certificate in the keystore. In this procedure, test was used.
  14. Send the newly modified sp.xml metadata file to the identity provider. See the note regarding modifications to SAMLv2 metadata at the bottom of this article for information on conveying the changes made in sp-extended.xml to the identity provider.
  15. Restart the web container on which the Fedlet is deployed.
  16. After the metadata has been properly integrated on the identity provider side, test the setup by running single sign-on initiated by the Fedlet.

Configuring the Fedlet for XML Signing and Encryption

By default, the Fedlet decrypts all encrypted elements it receives. It does not though define (or enforce) a particular element for decryption. In the same manner, the Fedlet does not define any particular elements for signing. The following instructions will configure these attributes.

To enforce what the service provider/Fedlet wants encrypted, modify the sp-extended.xml metadata on the Fedlet side by setting the value of the following attributes to true.

  • wantAssertionEncrypted
  • wantNameIDEncrypted
  • wantAttributeEncrypted

To enforce what the service provider/Fedlet will (and wants) signed, modify the sp.xml and sp-extended.xml metadata on the Fedlet side by setting the value of the following attributes to true.

  • wantAuthnRequestsSigned in the identity provider standard metadata tells the Fedlet what to sign.
  • AuthnRequestsSigned and WantAssertionsSigned in the service provider standard metadata tells the identity provider what the Fedlet will sign.
  • wantArtifactResolveSigned in the identity provider extended metadata tells the Fedlet what to sign.
  • wantArtifactResponseSigned in the service provider extended metadata tells the Fedlet what to sign.


NOTE REGARDING MODIFICATIONS TO SAMLv2 METADATA

Be sure to convey information regarding any changes made in the service provider metadata to the identity provider so it can make the corresponding changes to its own configuration. A modified sp.xml file may be sent to the identity provider but any modifications made to sp-extended.xml should be conveyed to the identity provider using a different method. Once the identity provider receives the appropriate standard and extended metadata values, it can make the changes using the OpenSSO console. Information on customizing SAMLv2 providers using the OpenSSO console is available in the OpenSSO Enterprise 8.0 documentation.

If the identity provider is using a different product, they would make the changes according to their product's documentation.
In This Article

Labels

security security Delete
saml2 saml2 Delete
xml xml Delete
signing signing Delete
encryption encryption Delete
fedlet fedlet Delete
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.

Sign up or Log in to add a comment or watch this page.


The individuals who post here are part of the extended Sun Microsystems community and they might not be employed or in any way formally affiliated with Sun Microsystems. The opinions expressed here are their own, are not necessarily reviewed in advance by anyone but the individual authors, and neither Sun nor any other party necessarily agrees with them.

Copyright 1994-2009 Sun Microsystems, Inc.
Powered by Atlassian Confluence Sun Guidelines on Public Discourse Privacy Policy Terms of Use Trademarks Site Map Employment Investor Relations Contact