Skip to main content

Managing the XUA Registry

Cross-Enterprise User Assertion (XUA) is an IHE profile that supports user authentication across enterprise boundaries using the SAML 2.0 Identity Assertion to verify claims about an authenticated identity. SAML tokens are sent in the security headers of SOAP calls.

To enable creation of outbound SAML Assertions using the XUA registry:

  1. Create one or more XUA configurations in the XUA registry (documented in the next section).

  2. Select an XUA Configuration in the appropriate Service Registry entry.

    For XCA and XDS.b, the Service Registry entry should be one that has a Device Function set to either XCA.Retrieve or XDSb.Retrieve.

  3. Select a style of SAML Assertion in the Send SAML Assertion field in the Service Registry entry. See “SOAP Service Settings” in the chapter Managing the Service Registry for details on the various styles of assertions.

Setting up SAML in the Service Registry allows different SAML Assertion types to be sent to different repositories (which may come from different vendors). For example, if you request documents from different XDS.b repositories or different XCA Home Communities, the same consumer operation can be used for all of the requests. By assigning a different XUA configuration to each Service Registry entry, the SAML creator can be customized for each system. Health Connect uses the repository OID or the Home Community OID in the document request to identify which Service Registry entry (and XUA configuration) to use for that request.

Note:

The XDS.b consumer operation contains SendSAMLAssertion and SAMLCreator settings, but these have been deprecated in favor of XUA configurations and the settings on the Service Registry as they provide for more flexibility.

To enable inbound SAML Assertion processing, create an XUA configuration that identifies the sending organization using the organization OID or URL found in the assertion.

Creating or Editing an XUA Configuration

An XUA configuration defines how to create an outbound SAML Assertion and how to process an inbound SAML Assertion. To create or edit an XUA configuration:

  1. Log in to the Management Portal as a user with the %HS_Administrator role.

  2. Select your Foundation namespace.

  3. Select Health > IHE Configuration > XUA Configuration Registry.

  4. Select a configuration from the table to edit an existing configuration or select Add Configuration to create a new one.

  5. Enter appropriate values in the various settings and select Save. The settings are described in the next section.

XUA Configuration Settings

The image below is the XUA Configuration screen:

The first block of settings relates to creating an outbound SAML Assertion. The second block of settings relates to processing an inbound SAML Assertion.

XUA Settings for Creating a SAML Assertion

Name

The name of the configuration. Only Name is required to save a configuration, but several additional settings are required in order to make the XUA configuration functional for creating or processing assertions.

CreatorClass

The name of the class that creates the SAML Assertion. This setting is required for creating assertions. The creator class may be HS.IHE.XUA.Creator.cls or a custom class that extends HS.IHE.XUA.CreatorOpens in a new tab. An example is provided in the class HS.IHE.XUA.SHINNY.Creator.cls.

Issuer or IssuerX509

The string to use for the name of the SAML Issuer. Set either one property or the other:

  • Issuer — a string containing the distinguished name of the organization’s certificate.

  • IssuerX509 — the alias of an X.509 certificate that references the organization’s certificate. If Sign Assertion is selected, then the X.509 certificate is used to sign the SAML token.

If both Issuer and IssuerX509 are empty, an error is reported when creating new tokens. If both values are set, IssuerX509 takes precedence over Issuer.

Sign Assertion

Select this to ensure that each SAML token is signed by the X.509 certificate indicated in the IssuerX509 setting. If Sign Assertion is selected, then IssuerX509 must have a value.

Sign Using

Whether to sign the message using the WSSecuritySignature or Signature. Signing with both causes problems validating the Signature, because the Signature signs the assertion when only a placeholder WSSecuritySignature is present, but would be validated against a message containing the full WSSecuritySignature. This defaults to WSSecuritySignature.

As part of the signature verification process, the XUA processor checks that the WSSecuritySignature or Signature actually signs the entire assertion by comparing the reference URI to the assertion ID, based on SAML 2.0 specOpens in a new tab, section 5.4.2.

XUA Settings for Processing an Inbound SAML Assertion

OrganizationOID or OrganizationURL

Select the code of an OID registry entry identifying the organization in the OrganizationOID field. Optionally set the URL of the organization in the OrganizationURL setting.

An inbound SAML Assertion should contain an organization identifier of some kind. This may be in the form of an OID or a URL. InterSystems uses the organization identifier to identify which XUA configuration should process the assertion. InterSystems recognizes the following forms of attribute name for the organization identifier:

  • IHE: urn:oasis:names:tc:xspa:1.0:subject:organization-id

  • SHIN-NY: UserOrganizationOID

If you receive SAML Assertions that use a different attribute naming convention, write a custom method to locate the organization identifier in the assertion and assign the method to OrgURLAttributeCode in the web service. The method should return an organization identifier in the form of an OID or URL. An example method is provided in GetOrganizationID() in the class HS.IHE.XUA.SHINNY.Processor.

ProcessorClass

The name of the class that processes inbound SAML Assertions. This setting is required for processing assertions. The processor class may be HS.IHE.XUA.Processor.cls or a custom class that extends HS.IHE.XUA.ProcessorOpens in a new tab. An example is provided in the class HS.IHE.XUA.SHINNY.Processor.cls.

DomainPrefix and DefaultSecurityDomain

DefaultSecurityDomain is the name of the default security domain. This is optional.

InterSystems uses information from the SAML attributes along with the optional DomainPrefix to locate the appropriate security domain where the SAML users are defined. It searches in the following order for a domain identified by the value of DomainPrefix concatenated with the:

  1. OID registry code for the organization-id from the SAML Assertion

  2. organization name directly from the SAML assertion

  3. OID registry code for the homeCommunityId of the sender from the SAML Assertion

The provided value for DomainPrefix is “%HS ” for the internal security domains.

If InterSystems locates an appropriately named security domain, it searches for the users there. Otherwise it uses the value in DefaultSecurityDomain, without the domain prefix, to locate users.

For example, if all SAML users are identified in your system in security domains that begin with “SAML_”, enter SAML_ in the DomainPrefix field. For a SAML Assertion with the following attributes:

  • an organization attribute of “XYZ”

  • an organization-id of “1.2.3” which resolves to “XYZ-Organization” in the OID registry

  • a homeCommunityID of “4.5.6” which resolves to “RHIO-A” in the OID registry

InterSystems would look in the following order for domains named:

  1. “SAML_XYZ-Organization”

  2. “SAML_XYZ”

  3. “SAML_RHIO-A”

If none of those domains are found, InterSystems looks in the default domain.

You can change this behavior by overriding the GetDomain() method in your processor class. In the provided example, HS.IHE.XUA.SHINNY.Processor.cls, the following scheme is used:

  1. DomainPrefix_UserOrganizationOID

  2. DomainPrefix_UserOrganizationName

  3. DomainPrefix_UserRHIO (which is an OID)

Require Signature

Select this to require that inbound SAML Assertions be signed by an X.509 certificate in order to be processed.

Check Signer Identity

If selected (the default), the XUA processor inspects the KeyInfo property of the signature of an inbound SAML assertion as part of signature validation. The assertion will only pass validation if the following two conditions are met:

  • it is possible to identify the signer from the KeyInfo.

  • the signer's credentials are trusted.

    Important:

    If an RSA public key is used in lieu of an X.509 certificate, it must be added to the Trusted RSA Key Registry.

If not selected, assertions that are signed with only an RSA public key or with symmetric encryption will pass validation without attempting to identify the signer.

FeedbackOpens in a new tab