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. 

In some instances of SP-initiated SSO, Oracle Utilities will not send a RelayState parameter. For example, this occurs when the user clicks on the Sign In link on the Energy Efficiency Web Portal home page. In these situations, the Identity Provider should use the Dashboard URL for the RelayState.

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). Oracle Utilities will describe the exact value required for this field based on the implementation plan. It will be one or more of the fields passed in the historical and iterative data files about the particular customer. Oracle Utilities will use this identifier to determine which account to display to the customer.

SAML Attribute for Single Account SSO

A SAML attribute can provide additional attributes that are associated with a particular customer. The name of the attribute must be userDataXML and must have <sso_user_properties> as its value. Be aware that the attribute value must be enclosed in a CDATA block, which is demonstrated below, or alternatively use escaped XML characters. In the following example, the attribute value contains a <property> tag that specifies customer preferences or characteristics, such as a preferred language.

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>

A more complete code sample is defined in the appendix. See XML Schema for Single Account SSO for more information.

Note: The language preference specification shown in the code sample above is optional and only applicable to utilities that allow their customers to view the Energy Efficiency Web Portal in different languages. See the Oracle Utilities Opower Multilingual Configuration Guide for more information.

Back to Top

SAML Attribute for Multiple Account SSO

A SAML attribute provides additional attributes that are associated with the particular customer. The information contained within the SAML attribute is what Oracle Utilities uses to determine which accounts a customer should be able to view once they are logged in. The name of the attribute must be userDataXML. The required values of the attribute, such as the <authorized_accounts> and <user> elements, are defined in the schema in SAML Assertion XML Schemas.

The SAML Attribute and Account ID values come from one or more of the fields passed in the historical and iterative data files about the particular customer. The transfer of these data files is set up with Oracle Utilities at the beginning of your program. The fields passed in the SAML must uniquely identify a customer record. While the required fields vary for each client, the fields customer_id and premise_id are commonly used to identify each customer record. If multiple fields are required, the values are concatenated and separated with a hyphen (-).

The SAML attribute also defines the initial account that should be shown to the customer after they are logged in. This is done using the <initial_account id> tag. An initial account must be defined regardless of whether the customer has access to one account or many accounts.

For example, the following is an example of the XML Oracle Utilities is expecting within the SAML attribute in a successful SAML assertion. Be aware that the attribute value must be enclosed in a CDATA block, which is demonstrated below, or alternatively use escaped XML characters. The example represents a scenario where two fields are required to uniquely identify a customer record:

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" ?>
      <authorized_accounts>
        <user>
          <display_name>John Smith</display_name>
            <language_preference>en_us</language_preference>
        </user>
        <initial_account id="123456-987654"/>
        <accounts>
          <account id="123456-987654">
            <name>Primary Residence</name>
          </account>
          <account id="123456-987655">
            <name>Secondary Residence</name>
          </account>
        </accounts>
      </authorized_accounts>
    ]]></saml:AttributeValue>
  </saml:Attribute>
</saml:AttributeStatement>

Note: The language preference specification shown in the code sample above is optional and only applicable to utilities that allow their customers to view the Energy Efficiency Web Portal in different languages. See the Oracle Utilities Opower Multilingual Configuration Guide for more information.

The following is an example of the XML Oracle Utilities is expecting within the SAML attribute for an unsuccessful SAML assertion:

Copy 
<authorized_accounts>
  <error>Error - No such user</error>
</authorized_accounts>

Note that this XML is optional. An example of this code in the context of the larger schema is available in the appendix. See XML Schema for Multiple Account SSO for more information.

Back to Top

Account Data Selector Formatting

When an SSO customer with multiple accounts goes to the Energy Efficiency Web Portal, their request to sign in is re-routed through a federation server, which goes back to the utility to ensure that the customer’s credentials are correct. When the customer is returned to the Energy Efficiency Web Portal, Oracle Utilities is passed certain information about the customer in a SAML assertion. Information that Oracle Utilities gathers includes:

  • User Display Name: The name that should be displayed at the top of the Energy Efficiency Web Portal, immediately after the Logged in as… text.
  • Primary Account: The account that should be the default account to display in the account selector.
  • Account ID: Represents the account identification for each customer. This number is created by the utility.
  • Account Name: Indicates the name to use for the account. For example, a customer could name one account “Home” and another account “Office”.

An example of this formatting is:

Copy 
<authorized_accounts>
  <user>
    <display_name>John Smith</display_name>
  </user>
  <initial_account id="123456-987654"/>
  <accounts>
    <account id="123456-987654">
      <name>Primary Residence</name>
    </account>
    <account id="123456-987655">
      <name>Secondary Residence</name>
    </account>
  </accounts>
</authorized_accounts>

Back to Top

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 which is stored on the Oracle Utilities federation server. This prevents unauthorized parties from tampering with the destination URL during transit.

Back to Top