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.