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 thecustomer_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 thepremise_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 theaccount_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 theservice_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.
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
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. ThelanguagePreference
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.
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.