Skip to main content
InterSystems IRIS Data Platform 2021.1 > Security > Security for Developers > Securing Web Services > Creating and Adding SAML Tokens

Creating and Adding SAML Tokens

This topic describes how to add a SAML token to the WS-Security header element.

Also see the class reference for %SAML.AssertionOpens in a new window and related classes.

Full SAML support is not implemented. “SAML support in InterSystems IRIS” refers only to the details listed in “WS-Security Support in InterSystems IRIS,” in the first topic.

Overview

With InterSystems IRIS 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, InterSystems IRIS 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.X509CredentialsOpens in a new window, as described in “Retrieving Credential Sets Programmatically,” earlier in this book.

    This InterSystems IRIS credential set must contain your own certificate. For example:

     Set x509alias = "servercred" 
 Set pwd = "mypassword" 
 Set credset = ##class(%SYS.X509Credentials).GetByAlias(x509alias,pwd)
    Copy code to clipboard

  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.BinarySecurityTokenOpens in a new window. For example:

     set bst=##class(%SOAP.Security.BinarySecurityToken).CreateX509Token(credset)
    Copy code to clipboard

    Where credset is the InterSystems IRIS 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)
    Copy code to clipboard

  5. Create a signed SAML assertion based on the binary security token. To do so, call the CreateX509() class method of %SAML.AssertionOpens in a new window. For example:

     set assertion=##class(%SAML.Assertion).CreateX509(bst)
    Copy code to clipboard

    This method returns an instance of %SAML.AssertionOpens in a new window. InterSystems IRIS 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.AssertionOpens in a new window:

    • For IssueInstant, specify the date and time when this assertion is issued.

    • For Issuer, create an instance of %SAML.NameIDOpens in a new window. Specify properties of this instance as needed and set the Issuer property of your assertion equal to this instance.

  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.SignatureOpens in a new window 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)
    Copy code to clipboard

    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:

  • Skip steps 2 and 3. That is, do not create and add a <BinarySecurityToken>.

  • In step 4, use the credential set (rather than a binary security token) as the first argument to CreateX509(). For example:

     set assertion=##class(%SAML.Assertion).CreateX509(credset,referenceOption)
    Copy code to clipboard

    For referenceOption, optionally specify a value as described in “Reference Options for X.509 Credentials,” earlier in this book. Use any value except $$$SOAPWSReferenceDirect.

    If you specify a credential set as the first argument (as we are doing in this variation), the default reference option is the thumbprint of the certificate.

Variation: Creating an Unsigned SAML Assertion

To create an unsigned SAML assertion, use the preceding steps, with the following changes:

  • Skip steps 1, 2, and 3. That is, do not create and add a <BinarySecurityToken>.

  • For step 4, use the Create() method instead of CreateX509(). This method takes no arguments. For example:

     set assertion=##class(%SAML.Assertion).Create()
    Copy code to clipboard

    This method returns an instance of %SAML.AssertionOpens in a new window. InterSystems IRIS automatically sets the SAMLID and Version properties of this instance. The Signature property is null.

Adding SAML Statements

To add SAML statements to your instance of %SAML.AssertionOpens in a new window:

  1. Create one or more instances of the appropriate statement classes:

  2. Specify properties of these instances as needed.

    For %SAML.AttributeStatementOpens in a new window, the Attribute property is an instance of either %SAML.AttributeOpens in a new window or %SAML.EncryptedAttributeOpens in a new window.

    %SAML.AttributeOpens in a new window carries attribute values in its AttributeValue property, which is a list of %SAML.AttributeValueOpens in a new window instances.

    To add attribute values to a %SAML.AttributeOpens in a new window instance:

    1. Create instances of %SAML.AttributeValueOpens in a new window.

    2. Use methods of %SAML.AttributeValueOpens in a new window 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.AssertionOpens in a new window:

  1. Create a new instance of %SAML.SubjectOpens in a new window.

  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.AssertionOpens in a new window, 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.X509CredentialsOpens in a new window 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.BinarySecurityTokenOpens in a new window. For example:

     set bst=##class(%SOAP.Security.BinarySecurityToken).CreateX509Token(credset)
    Copy code to clipboard

    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
    Copy code to clipboard

    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
    Copy code to clipboard

    For method, specify $$$SAMLSenderVouches, $$$SAMLHolderOfKey or $$$SAMLBearer.

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.X509CredentialsOpens in a new window 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
    Copy code to clipboard

    For the argument, use the instance of %SYS.X509CredentialsOpens in a new window 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)
    Copy code to clipboard

    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.BinarySecretOpens in a new window:

    set binsec=##class(%SOAP.WST.BinarySecret).Create()
    Copy code to clipboard

  3. Call the AddBinarySecretConfirmation() method of the Subject property of your SAML assertion object:

    set status=assertion.Subject.AddBinarySecretConfirmation(binsec)
    Copy code to clipboard

    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.AssertionOpens in a new window:

  1. Create an instance of %SAML.ConditionsOpens in a new window.

  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.AssertionOpens in a new window:

  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.

Previous sectionUsing WS-ReliableMessagingTroubleshooting Security ProblemsNext section
FeedbackOpens in a new window