SAML Assertion Requirements

RelayState

Oracle Utilities sends a RelayState parameter in the SAML assertion sent to the Solution Extension partner. In IdP-initiated SSO, utility clients or Oracle Utilities can send a URL in the RelayState parameter to redirect users to a specific page after login. Upon receiving a SAML assertion from the utility containing a RelayState URL hosted by a Solution Extension portal, Oracle Utilities forwards that assertion to the Solution Extension’s SP endpoint.

In SP-initiated SSO, the Solution Extension partner must provide a RelayState parameter to the Oracle Utilities IdP. The IdP sends the RelayState parameter back without any modifications, as stated in the SAML 2.0 specification.

SAML Data Elements

SAML Subject

The SAML subject must contain a user identifier. This value must match the web_user_id value. The Solution Extension partner must use this identifier to determine which accounts to display to the user.

SAML Attributes

There are several fields that may be provided as SAML attributes within the assertion. These attributes are listed below.

Fields for Multi-account Users

To support scenarios where web users have access to multiple customer accounts, the SAML assertion contains additional fields to verify that the correct information is displayed. These additional fields are defined during integration and may include the following:

  • initialCustomerId: Customer ID associated with the account, which may be displayed upon initial login. This must match the customer_id value from the Oracle Utilities billing data file.
  • initialPremiseId: Premise ID associated with the account, which may be displayed upon initial login. This must match the premise_id value from the Oracle Utilities billing data file.
  • initialAccountId: Account ID associated with the account, which may be displayed upon initial login. This must match the account_id value from the Oracle Utilities billing data file. This field is not typically used by Oracle Utilities to identify customers but may be passed through to downstream partners.
  • initialServicePointId: Service Point ID associated with the account which may be displayed upon initial login. This must match the service_point_id value from the Oracle Utilities billing data file. This field is not typically used by Oracle Utilities to identify customers but may be passed through to downstream partners.

Back to Top

Additional User Information

The SAML assertion may contain additional information about the user account, which can be used for display purposes only. Any of the following fields, if provided, can be used to present relevant information about the web user on the portal but are transient and not persisted beyond the user's current session.

  • userName
  • firstName
  • lastName
  • emailAddress
  • phoneNumber

Back to Top

Multiple Language Support

If Oracle Utilities and the Solution Extension portal support multiple languages, additional information about the user's preferred display language may be provided in the SAML. When supported, multiple language support and the user experience are determined between Oracle Utilities and the Solution Extension partner during integration.

  • languagePreference: Preferred display language for the web user. This must consist of a valid ISO 639-1 2-letter language code and a valid ISO 3166-1 2-letter country code, concatenated with an underscore (_) character. For example, en_US represents English for the United States. The languagePreference is optional and only applicable to utilities that allow their customers to view the Energy Efficiency Web Portal in multiple languages. See the Oracle Utilities Opower Multiple Language Support Configuration Guide for more information.

Back to Top

Security

Security for SAML is done through several mechanisms:

  • SAML assertions sent using POST binding from the IdP must be digitally signed with the IdP’s private key using an XML signature. This is a requirement per the SAML specifications. The Solution Extension SP verifies 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.
  • Data is encrypted via HTTPS during transfer.
  • During SP-initiated exchanges, the RelayState parameter is not a plaintext URL when it is passed between the Solution Extension partner and Oracle Utilities. The parameter is instead a reference to the desired URL which is stored on the Solution Extension federation server. This prevents unauthorized parties from tampering with the destination URL during transit.

Back to Top