Oracle Utilities Opower Solution Extension Partner SSO

Oracle Utilities Opower Solution Extension Partner SSO Integration Guide E84763-01 Last Updated: Friday, January 05, 2018

Oracle Utilities Opower Solution Extension Partner SSO Integration Guide Copyright 2016, 2018, Oracle and/or its affiliates. All rights reserved. This software and related documentation are provided under a license agreement containing restrictions on use and disclosure and are protected by intellectual property laws. Except as expressly permitted in your license agreement or allowed by law, you may not use, copy, reproduce, translate, broadcast, modify, license, transmit, distribute, exhibit, perform, publish, or display any part, in any form, or by any means. Reverse engineering, disassembly, or decompilation of this software, unless required by law for interoperability, is prohibited. The information contained herein is subject to change without notice and is not warranted to be error-free. If you find any errors, please report them to us in writing. If this is software or related documentation that is delivered to the U.S. Government or anyone licensing it on behalf of the U.S. Government, then the following notice is applicable: U.S. GOVERNMENT END USERS: Oracle programs, including any operating system, integrated software, any programs installed on the hardware, and/or documentation, delivered to U.S. Government end users are "commercial computer software" pursuant to the applicable Federal Acquisition Regulation and agency- specific supplemental regulations. As such, use, duplication, disclosure, modification, and adaptation of the programs, including any operating system, integrated software, any programs installed on the hardware, and/or documentation, shall be subject to license terms and license restrictions applicable to the programs. No other rights are granted to the U.S. Government. This software or hardware is developed for general use in a variety of information management applications. It is not developed or intended for use in any inherently dangerous applications, including applications that may create a risk of personal injury. If you use this software or hardware in dangerous applications, then you shall be responsible to take all appropriate fail-safe, backup, redundancy, and other measures to ensure its safe use. Oracle Corporation and its affiliates disclaim any liability for any damages caused by use of this software or hardware in dangerous applications. Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may be trademarks of their respective owners. Intel and Intel Xeon are trademarks or registered trademarks of Intel Corporation. All SPARC trademarks are used under license and are trademarks or registered trademarks of SPARC International, Inc. AMD, Opteron, the AMD logo, and the AMD Opteron logo are trademarks or registered trademarks of Advanced Micro Devices. UNIX is a registered trademark of The Open Group. This software or hardware and documentation may provide access to or information about content, products, and services from third parties. Oracle Corporation and its affiliates are not responsible for and expressly disclaim all warranties of any kind with respect to thirdparty content, products, and services unless otherwise set forth in an applicable agreement between you and Oracle. Oracle Corporation and its affiliates will not be responsible for any loss, costs, or damages incurred due to your access to or use of third-party content, products, or services, except as set forth in an applicable agreement between you and Oracle. Documentation Accessibility For information about Oracle's commitment to accessibility, visit the Oracle Accessibility Program website at http://www.oracle.com/pls/topic/lookup?ctx=acc&id=docacc. Access to Oracle Support Oracle customers that have purchased support have access to electronic support through My Oracle Support. For information, visit http://www.oracle.com/pls/topic/lookup?ctx=acc&id=info or visit http://www.oracle.com/pls/topic/lookup?ctx=acc&id=trs if you are hearing impaired. ii

Contents Introduction... 1 Solution Extension Partner Checklist... 1 Data Integration Requirements... 2 General SAML Requirements... 2 SAML Version... 2 SAML Roles... 2 Supported SSO Profiles... 2 SAML Bindings... 3 Identity Provider to Service Provider Binding... 3 Service Provider to Identity Provider Binding... 3 SAML Assertion Requirements... 4 RelayState... 4 SAML Data Elements... 4 SAML Subject... 4 SAML Attributes... 4 Security... 5 Single Logout... 6 SAML Configuration Information... 6 Oracle Utilities Opower SAML Information... 6 Production Information... 6 Staging Information... 6 Information Required by Oracle Utilities from the Solution Extension Partner... 7 Testing Procedures... 7 iii

Introduction This document contains the requirements for implementing single sign-on (SSO) with the Oracle Utilities Identity Provider for Solution Extension partners. SSO makes it easier for customers to access their energy information on the Solution Extension portal by allowing them to use their utility web application username and password. In this setup, Oracle Utilities acts as an identity bridge between the utility as Identity Provider and the Solution Extension as Service Provider. The following diagram shows an example integration with the utility site, Oracle Utilities Opower Energy Efficiency Web Portal - Classic, and Solution Extension partners. With SSO, customers can log into the utility website and navigate to the Energy Efficiency Web Portal - Classic or Solution Extension partner portal without creating an additional account or going through a separate authentication process. If customers attempt to access an Oracle Utilities or Solution Extension portal and are not currently logged in to the utility website, they are automatically directed to the utility website to sign in. After a successful authentication, the customer is returned to the page they were trying to view. SSO relies on communication between federation servers managed at each tier, which includes the utility, Oracle Utilities, and all Solution Extension partners. Solution Extension Partner Checklist This document explains the following Solution Extension partner requirements: If required, data integration between the utility, Oracle Utilities, and the Solution Extension partner is completed. Set up two SAML 2.0 service provider federated servers, one for stage and one for production. Ensure that authentication services are configured for both servers. Provide Oracle Utilities with required data to connect to servers through one of the following methods: 1

o SAML metadata o SSL certificate public key, endpoint URLs for each tier, and entity ID Provide Oracle Utilities with hostname and URL information for customer landing pages. Provide Oracle Utilities with account numbers from the utility data files that can be used for end-to-end testing. If required, provide Oracle Utilities with VPN access to the stage instance of the Solution Extension partner portal. Data Integration Requirements Data integration between the utility, Oracle Utilities, and the Solution Extension partner is a prerequisite for some partners. When data integration is required, it is assumed that both Oracle Utilities and the Solution Extension partner are receiving one or both of the following file extracts, which contain account and customer information from the utility: Customer and billing data, as defined in the Oracle Utilities Opower Platform Billing Data Transfer Standards document Web user accounts, as defined in the Oracle Utilities Opower Web User Association Import Specification document These documents define the customer account identifiers that are exchanged as fields within SAML assertions for SSO. General SAML Requirements SAML Version Oracle Utilities supports Security Assertion Markup Language (SAML) 2.0 to implement SSO with Solution Extension partners. SAML 2.0 was ratified by the OASIS Standard. Oracle Utilities does not support SAML 1.1. If new SAML versions are announced, Oracle Utilities will work to support the latest SAML versions in our product offering. SAML Roles Oracle Utilities acts as the Identity Provider (IdP) and the Solution Extension partner acts as the Service Provider (SP). Supported SSO Profiles IdP-initiated SSO is required. The Solution Extension partner provides landing page URLs for their portal that are used by Oracle Utilities when starting IdP-initiated SSO. 2

Oracle Utilities sends one of these URLs as the RelayState parameter in the SAML assertion. Oracle Utilities strongly recommends that the Solution Extension partner also support SP-initiated SSO. SP-initiated SSO allows users to bookmark pages on the Solution Extension website. To support SP-initiated SSO, the utility must also support SPinitiated SSO on their IdP service that is integrated with the Oracle Utilities SP portion of the bridge. SP-initiated SSO is employed when the user visits a protected page on the Solution Extension portal without having an authenticated session with the Solution Extension partner, regardless of whether they have an authenticated session on either the utility or Oracle Utilities sites. If a user s session on the Solution Extension portal expires while the user still has a window open, SP-initiated SSO allows the user to log in again and automatically return to the resource they requested. Performing SP-initiated SSO requires that the client have a functional SSO URL that Oracle Utilities can access to begin the SSO process. Whether a user attempts to access the Solution Extension portal using IdP-initiated or SP-initiated SSO, the Solution Extension partner must ensure that their federation server only authenticates users that have permission to access its portal. Oracle Utilities does not perform additional validation. The Solution Extension portal must provide a suitable error page or redirect to a landing screen experience for unauthorized users or SAML requests that fail to match known accounts. For further information on SAML SSO Profiles, refer to http://docs.oasisopen.org/security/saml/post2.0/sstc-saml-tech-overview-2.0.html. SAML Bindings Identity Provider to Service Provider Binding The Solution Extension SP must accept SAML assertions from the Oracle Utilities IdP using the HTTP POST binding method. This means that all SAML assertions are sent as HTTP POST requests from the IdP. HTTP redirect and artifact bindings are not supported. Service Provider to Identity Provider Binding If SP-initiated SSO is supported, the Solution Extension SP may use either HTTP redirect binding or HTTP POST binding when sending authentication requests to the Oracle Utilities IdP. It is recommended to use HTTP redirect binding by default. This means that when the Solution Extension portal begins the SP-initiated SSO process, it must issue an HTTP redirect to the user s web browser, which directs them to the Oracle Utilities IdP. The IdP federation service then receives an HTTP GET or POST request from the consumer and initiates the authorization process. HTTP artifact binding is not supported. 3

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 provided in the Oracle Utilities Opower Web User Association Import Specification. 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 4

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. 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. The languagepreference is optional and only applicable to utilities that allow their customers to view the Energy Efficiency Web Portal - Classic in multiple languages. See the Oracle Utilities Opower Multiple Language Support Technical Brief 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. 5

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. Single Logout Single Logout (SLO) is not a supported feature of Solution Extension partner SSO. The SLO profile of the SAML 2.0 specification provides for coordinated and nearsimultaneous logout across applications with a federated authentication context. However, because the integrations between the utility, Oracle Utilities, and Solution Extension partner requires an identity bridge, full end-to-end SLO is not possible. By default, the Energy Efficiency Web Portal - Classic has a user session inactivity timeout of 30 minutes, which is configurable on a per-client basis. The Solution Extension portal must be able to configure user session inactivity timeout to meet utility requirements and offer a consistent experience for the user across all service providers. SAML Configuration Information When implementing SSO, most partners choose to contract with a federation server provider and configure settings through the provider s interface. Configuration details are provided below. Oracle Utilities Opower SAML Information Production Information Oracle Utilities Opower SAML Entity ID: sso.opower.com If the Solution Extension partner has multiple SSO connection, Oracle Utilities can provide a unique entity ID for each connection using a virtual server ID (for example, sso-util.opower.com) Oracle Utilities Opower Public key: Provided by Oracle Utilities during setup Base URL: https://sso2.opower.com/ SAML Single Sign-On Service URL: sp/startsso.ping Staging Information Oracle Utilities Opower SAML Entity ID: sso-stage.opower.com If the Solution Extension partner has multiple SSO connections, Oracle Utilities can provide a unique entity ID for each connection using a virtual server ID (for example, sso-util-stage.opower.com) 6

Oracle Utilities Opower Public key: Provided by Oracle Utilities during setup Base URL: https://sso2-stage.opower.com/ SAML Single Sign-On Service URL: sp/startsso.ping Information Required by Oracle Utilities from the Solution Extension Partner Oracle Utilities recommends that Solution Extension federated server data be provided as SAML metadata. If this information is provided separately, the following data must be provided: Solution Extension partner SAML Entity ID: For example, sso.util.com SSL certificate public keys Assertion Customer Service URLs for each tier Default Target URL (RelayState value) Testing Procedures Oracle Utilities IdP and Solution Extension integration and testing procedures are under active development and will be shared as the project continues. SSO implementations are thoroughly tested by the Solution Extension partner and Oracle Utilities before going live. Oracle Utilities has separate instances of the Energy Efficiency Web Portal - Classic and Federation server specifically for integration testing. This is known as our staging environment. This infrastructure is completely separate from the production Oracle Utilities infrastructure. Before going live with a Solution Extension partner, the Oracle Utilities staging infrastructure is configured to accept SAML assertions from the corresponding utility and Solution Extension partner testing environment. The Solution Extension partner s application and federation server must similarly be configured to send SAML assertions to the Oracle Utilities federation server. To verify a successful connection and assist with troubleshooting, Oracle Utilities needs the ability to login on the Solution Extension partner s stage environment. This may require VPN access if the stage environment is located behind a firewall. It will also require at least one valid login on the stage environment. Once testing is complete, the configurations are migrated to the production applications for both Oracle Utilities and the Solution Extension partner. To verify these connections, Oracle Utilities also needs a test account on production. The stage and production test accounts should be available for the life of the program for continuous verification of end-to-end SSO functionality. 7