SAML Single Sign-On Assertion Requirements

The SAML assertion for an SSO implementation requires a RelayState parameter, as well as specific data elements and security information. Many of these requirements are the same for both single and multiple account SSO. The main differences are in the required data elements, which are identified in the following sections.

On this page:

RelayState Parameter

Identity Providers must send Oracle Utilities a RelayState parameter in the SAML assertion sent to Oracle Utilities. In IdP-initiated SSO, utilities can set up links that will take users directly to a specific page by sending the appropriate URL in the RelayState. Oracle Utilities will provide utilities with our Dashboard URL to be used as a default RelayState parameter. The Dashboard is an appropriate general page to send customers to once they log in. Utilities must use this Dashboard URL or another valid URL as the RelayState URL when using IdP-initiated SSO. 

In SP-initiated SSO, if Oracle Utilities sends a RelayState parameter to the Identity Provider, the Identity Provider must send the RelayState parameter back to Oracle Utilities without any modifications, as stated in the SAML 2.0 specification. When Oracle Utilities sends a RelayState parameter in SP-initiated SSO, it will be an alpha-numeric token that refers to saved state information on the Oracle Utilities federation server, and the RelayState will not be a URL. 

Back to Top

SAML Data Elements

The required SAML data elements include the SAML subject and the SAML attribute. The elements of the SAML attributes can vary slightly depending on your implementation.

Warning: Ensure that carriage return characters are not included in SAML responses. Inclusion of carriage returns can cause errors such as signature mismatches.

SAML Subject

The SAML subject must contain an anonymous user identifier, such as a GUID, that is used for the login process. This identifier must not contain any personally identifiable information (PII). Additionally, the user identifier must uniquely identify users in the identity management system and must remain static upon creation. In other words, modifications to the user identifier referenced in the SAML subject are not supported.

SAML Attributes for All Account Types

The following attributes are included for all account types.

  • groups: This optional attribute controls the user landing page for groups of users. For example a DSSUserGroup group can support all users of Digital Self Service - Transactions, including utility customers and customer service representatives who can masquerade as utility customers.
  • firstName: This required attribute is the user’s first name, which can be displayed to the user, such as in welcome messages for a logged in user.
  • lastName: This required attribute is the user’s last name, which can be displayed to the user, such as in welcome messages for a logged in user.
  • email: This required attribute is the user’s email address.
  • username: This required attribute is the user's username, which is used to sign in to and access their account.

Back to Top

Copy 
<saml:AttributeStatement xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <saml:Attribute NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic" Name="userDataXML">
    <saml:AttributeValue xsi:type="xs:string" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"><![CDATA[<?xml version="1.0" encoding="UTF-8" ?>
    <sso_user_properties> 
          <property> 
                <name>language_preference</name> 
                <value>zh_HK</value> 
          </property> 
    </sso_user_properties>
    ]]></saml:AttributeValue>
  </saml:Attribute>
</saml:AttributeStatement>

Security Requirements

Security for SAML is achieved through several mechanisms. First, SAML assertions sent using POST binding from the Identity Provider must be digitally signed with the Identity Provider’s private key using XML signature. This is a requirement per the SAML specifications. Oracle Utilities will then verify the source with the corresponding public key. Assertions that fail this verification process are rejected. This mechanism ensures that only assertions originating from the proper utility client are accepted. Furthermore, data is encrypted via HTTPS during transfer. In addition, the RelayState parameter does not include a full URL when it is passed from Oracle Utilities to the utility and then back, but it is a reference to the desired URL. This prevents unauthorized parties from tampering with the destination URL during transit.

Back to Top