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 tab 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.

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.

Optionally include the %soap.inc include file, which defines macros you might need to use.
Create an instance of %SYS.X509CredentialsOpens in a new tab, as described in Retrieving Credential Sets Programmatically.
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)
```
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 tab. For example:
```
 set bst=##class(%SOAP.Security.BinarySecurityToken).CreateX509Token(credset)
```
Where credset is the InterSystems IRIS credential set you created in the previous step.
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)
```
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 tab. For example:
```
 set assertion=##class(%SAML.Assertion).CreateX509(bst)
```
This method returns an instance of %SAML.AssertionOpens in a new tab. InterSystems IRIS automatically sets the Signature, SAMLID, and Version properties of this instance.
This instance represents the <Assertion> element.
Specify the following basic properties of your instance of %SAML.AssertionOpens in a new tab:
- For IssueInstant, specify the date and time when this assertion is issued.
- For Issuer, create an instance of %SAML.NameIDOpens in a new tab. Specify properties of this instance as needed and set the Issuer property of your assertion equal to this instance.
Add SAML statements, as described in Adding SAML Statements.
Add a <Subject> element to the SAML assertion, as described in Adding a <Subject> Element.
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.
Specify the SAML <Conditions> element, as described in Adding a <Conditions> Element.
Optionally add <Advice> elements, as described in Adding <Advice> Elements.
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.
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 tab 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.
Send the SOAP message. See the general comments in Adding Security Header Elements.

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)
```
For referenceOption, optionally specify a value as described in Reference Options for X.509 Credentials. 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()
```
This method returns an instance of %SAML.AssertionOpens in a new tab. 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 tab:

Create one or more instances of the appropriate statement classes:
Specify properties of these instances as needed.
For %SAML.AttributeStatementOpens in a new tab, the Attribute property is an instance of either %SAML.AttributeOpens in a new tab or %SAML.EncryptedAttributeOpens in a new tab.
%SAML.AttributeOpens in a new tab carries attribute values in its AttributeValue property, which is a list of %SAML.AttributeValueOpens in a new tab instances.
To add attribute values to a %SAML.AttributeOpens in a new tab instance:
1. Create instances of %SAML.AttributeValueOpens in a new tab.
2. Use methods of %SAML.AttributeValueOpens in a new tab 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.
Create a list that contains these statement instances.
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 tab:

Create a new instance of %SAML.SubjectOpens in a new tab.
Set properties of the subject as needed.
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 tab, 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:

Create an instance of %SYS.X509CredentialsOpens in a new tab as described in Retrieving Credential Sets Programmatically.
Or use the same credential set that you use to sign the assertion.
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 tab. 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.
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.

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:

Set the NameID property of the Subject property of your SAML assertion object.
Call the AddConfirmation() method of the Subject property of your SAML assertion object.
```
method AddConfirmation(method As %String) as %Status
```
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:

Create an instance of %SYS.X509CredentialsOpens in a new tab as described in Retrieving Credential Sets Programmatically.
Or use the same credential set that you use to sign the assertion.
Set the NameID property of the Subject property of your SAML assertion object.
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.X509CredentialsOpens in a new tab 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:

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.
Create a BinarySecret. To do so, call the Create() method of %SOAP.WST.BinarySecretOpens in a new tab:
```
set binsec=##class(%SOAP.WST.BinarySecret).Create()
```
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.AssertionOpens in a new tab:

Create an instance of %SAML.ConditionsOpens in a new tab.
Specify properties of this instance as needed.
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 tab:

Create instances of one or more of the following classes:
Specify properties of these instances as needed.
Create a list that contains these advice instances.
Set the Advice property of your assertion object equal to this list.

Troubleshooting Security Problems

Using WS-ReliableMessaging