Securing Caché Web Services
Creating and Adding SAML Tokens
[Back] [Next]
   
Server:docs1
Instance:LATEST
User:UnknownUser
 
-
Go to:
Search:    

This chapter describes how to add a SAML token to the WS-Security header element. It discusses the following topics:

Also see the class reference for %SAML.Assertion and related classes.
Full SAML support is not implemented. “SAML support in Caché” refers only to the details listed in WS-Security Support in Caché,” in the first chapter.
Overview
With Caché SOAP support, you can add a SAML token to the WS-Security header element.
Optionally, you can use this SAML token as key material for signing or encryption. If you do so, Caché follows the WS-Security SAML Token Profile specification. The key material comes from the <SubjectConfirmation> element of the SAML assertion with the Holder-of-key (HOK) method and <SubjectConfirmationData> or <KeyInfoConfirmationData> with a <KeyInfo> subelement.
Alternatively, you can add a <SubjectConfirmation> with the Sender-vouches (SV) method; in this case, the subject does not include a key. To protect the assertion in this case, it is recommended that you add a security token reference from the message signature to the SAML token.
Basic Steps
To create a SAML token and add it to outbound SOAP messages, you can use the basic procedure here or the variations described in the subsections.
  1. Optionally include the %soap.inc include file, which defines macros you might need to use.
  2. Create an instance of %SYS.X509Credentials, as described in Retrieving Credential Sets Programmatically,” earlier in this book.
    This Caché credential set must contain your own certificate. For example:
     Set x509alias = "servercred" 
     Set pwd = "mypassword" 
     Set credset = ##class(%SYS.X509Credentials).GetByAlias(x509alias,pwd)
  3. Create a binary security token that contains the certificate associated with the given credential set. To do so, call the CreateX509Token() class method of %SOAP.Security.BinarySecurityToken. For example:
     set bst=##class(%SOAP.Security.BinarySecurityToken).CreateX509Token(credset)
    Where credset is the Caché credential set you created in the previous step.
  4. Add this token to the WS-Security header element. To do so, call the AddSecurityElement() method of the SecurityOut property of your web client or web service. For the method argument, use the token you just created. For example:
     do ..SecurityOut.AddSecurityElement(bst)
  5. Create a signed SAML assertion based on the binary security token. To do so, call the CreateX509() class method of %SAML.Assertion. For example:
     set assertion=##class(%SAML.Assertion).CreateX509(bst)
    This method returns an instance of %SAML.Assertion. Caché automatically sets the Signature, SAMLID, and Version properties of this instance.
    This instance represents the <Assertion> element.
  6. Specify the following basic properties of your instance of %SAML.Assertion:
  7. Add SAML statements, as described in Adding SAML Statements.”
  8. Add a <Subject> element to the SAML assertion, as described in Adding a <Subject> Element.”
  9. Optionally add a <SubjectConfirmation> element to the <Subject>, as described in Adding a <SubjectConfirmation> Element.”
    You can confirm the subject with either the Holder Of Key method or the Sender Voucher method.
  10. Specify the SAML <Conditions> element, as described in Adding a <Conditions> Element.”
  11. Optionally add <Advice> elements, as described in Adding <Advice> Elements.”
  12. Call the AddSecurityElement() method of the SecurityOut property of your web client or web service. For the method argument, use the SAML token you created.
  13. Optionally sign the SAML assertion by adding a reference from the SOAP message signature to the SAML assertion.
    If the signature is a %XML.Security.Signature object, then you would sign the SAML assertion as follows:
      Set str=##class(%SOAP.Security.SecurityTokenReference).GetSAMLKeyIdentifier(assertion) 
      Set ref=##class(%XML.Security.Reference).CreateSTR(str.GetId()) 
      Do signature.AddReference(ref)
    This step is recommended especially if you add a <SubjectConfirmation> with the Sender Vouches method.
  14. Send the SOAP message. See the general comments in Adding Security Header Elements,” earlier in this book.
Variation: Not Using a <BinarySecurityToken>
A <BinarySecurityToken> contains a certificate in serialized, base-64–encoded format. You can omit this token and instead use information that identifies the certificate; the recipient uses this information to retrieve the certificate from the appropriate location. To do so, use the preceding steps, with the following changes:
Variation: Creating an Unsigned SAML Assertion
To create an unsigned SAML assertion, use the preceding steps, with the following changes:
Adding SAML Statements
To add SAML statements to your instance of %SAML.Assertion:
  1. Create one or more instances of the appropriate statement classes:
  2. Specify properties of these instances as needed.
    For %SAML.AttributeStatement, the Attribute property is an instance of either %SAML.Attribute or %SAML.EncryptedAttribute.
    %SAML.Attribute carries attribute values in its AttributeValue property, which is a list of %SAML.AttributeValue instances.
    To add attribute values to a %SAML.Attribute instance:
    1. Create instances of %SAML.AttributeValue.
    2. Use methods of %SAML.AttributeValue to specify the attribute either as XML, as a string, or as a single child element.
    3. Create a list that contains these attribute value instances.
    4. Set the AttributeValue property of your attribute object equal to this list.
    Or directly specify the AttributeValueOverride property. For the value, use the exact string (an XML mixed content string) needed for the value.
  3. Create a list that contains these statement instances.
  4. Set the Statement property of your assertion object equal to this list.
Adding a <Subject> Element
To add a <Subject> element to your instance of %SAML.Assertion:
  1. Create a new instance of %SAML.Subject.
  2. Set properties of the subject as needed.
  3. Set the Subject property of your assertion object equal to this instance.
Adding a <SubjectConfirmation> Element
To add a <SubjectConfirmation> element to your instance of %SAML.Assertion, use the steps in one of the following subsections.
<SubjectConfirmation> with Method Holder-of-key
To add a <SubjectConfirmation> with the Holder-of-key method, do the following:
  1. Create an instance of %SYS.X509Credentials as described in Retrieving Credential Sets Programmatically,” earlier in this book.
    Or use the same credential set that you use to sign the assertion.
  2. Optionally create and then add a binary security token that contains the certificate associated with the given credential set.
    To create the token, call the CreateX509Token() class method of %SOAP.Security.BinarySecurityToken. For example:
     set bst=##class(%SOAP.Security.BinarySecurityToken).CreateX509Token(credset)
    Where credset is the credential set you created in the previous step.
    To add this token to the WS-Security header element, call the AddSecurityElement() method of the SecurityOut property of your web client or web service. For the method argument, use the token you just created.
  3. Call the AddX509Confirmation() method of the Subject property of your SAML assertion object.
    method AddX509Confirmation(credentials As %SYS.X509Credentials, 
                               referenceOption As %Integer) as %Status
    For credentials, use the binary security token or the credential set. In the former case, do not specify referenceOption. In the latter case, specify a value as described in Reference Options for X.509 Credentials,” earlier in this book.
The <SubjectConfirmation> element is based on an X.509 KeyInfo element.
<SubjectConfirmation> with Method Sender-vouches
To add a <SubjectConfirmation> with the Sender-vouches method, do the following:
  1. Set the NameID property of the Subject property of your SAML assertion object.
  2. Call the AddConfirmation() method of the Subject property of your SAML assertion object.
    method AddConfirmation(method As %String) as %Status
In this case, be sure to sign the SAML assertion to protect it.
<SubjectConfirmation> with <EncryptedKey>
To add a <SubjectConfirmation> that carries a <SubjectConfirmationData> that contains an <EncryptedKey> element, do the following:
  1. Create an instance of %SYS.X509Credentials as described in Retrieving Credential Sets Programmatically,” earlier in this book.
    Or use the same credential set that you use to sign the assertion.
  2. Set the NameID property of the Subject property of your SAML assertion object.
  3. Call the AddEncryptedKeyConfirmation() method of the Subject property of your SAML assertion object.
    method AddEncryptedKeyConfirmation(credentials As %X509.Credentials) as %Status
    For the argument, use the instance of %SYS.X509Credentials that you previously created.
<SubjectConfirmation> with BinarySecret as Holder-of-key
To add a <SubjectConfirmation> with a BinarySecret as Holder-of-key, do the following:
  1. When you sign the SAML assertion, create the signature as follows:
    set sig=##class(%XML.Security.Signature).Create(assertion,$$$SOAPWSIncludeNone,$$$SOAPWSSAML)
    Where assertion is the SAML assertion. Note that you use the Create() method in this scenario. The $$$SOAPWSSAML reference option creates a reference to the SAML assertion.
  2. Create a BinarySecret. To do so, call the Create() method of %SOAP.WST.BinarySecret:
    set binsec=##class(%SOAP.WST.BinarySecret).Create()
  3. Call the AddBinarySecretConfirmation() method of the Subject property of your SAML assertion object:
    set status=assertion.Subject.AddBinarySecretConfirmation(binsec)
    For binsec, use the BinarySecret you created in the previous step.
This adds a <SubjectConfirmation> that contains a <SubjectConfirmationData> that contains a <KeyInfo> that contains the <BinarySecret>.
Adding a <Conditions> Element
To add a <Conditions> element to your instance of %SAML.Assertion:
  1. Create an instance of %SAML.Conditions.
  2. Specify properties of this instance as needed.
  3. Set the Conditions property of your assertion object equal to this instance.
Adding <Advice> Elements
To add <Advice> elements to your instance of %SAML.Assertion:
  1. Create instances of one or more of the following classes:
  2. Specify properties of these instances as needed.
  3. Create a list that contains these advice instances.
  4. Set the Advice property of your assertion object equal to this list.