OpenID Connect Single Sign-On (SSO) Configuration

You can implement OpenID Connect for SSO purposes to support embedded widgets integrated using custom elements. To implement SSO with OpenID Connect, the utility website acts as the Relying Party (RP) and must have an integrated authentication server that conforms to the OpenID Connect specification. This documentation refers to these authentication servers as OpenID Providers.

Note: Standalone Oracle Utilities products rely on SAML for SSO implementation. A utility must use OpenID Connect to implement SSO for embedded widgets. Refer to the Oracle Utilities Opower Digital Self Service - Energy Management Embeddable Widgets Integration Guide for information on embedding widgets using custom elements.

On this page:

Utility Configuration Checklist

SSO relies on standards-based communication between an OpenID Provider authentication server managed by the utility and the server managed by Oracle Utilities. The following steps are required to set up and configure SSO for OpenID Connect.

Note: Oracle Utilities supports configuration with multiple authorization servers. In this scenario, the following configuration checklist must be completed for each authorization server.

  • Set up two OpenID Providers, one stage server and one production server.
  • Implement customer Access Tokens which must be passed in through an Opower API for webpages that embed widgets. For information on the separate embedding process, see the Oracle Utilities Opower Digital Self Service - Energy Management Embeddable Widgets Integration Guide.
  • Complete the steps for Creating a UserInfo Endpoint with Custom Claims.
  • Provide the UserInfo Endpoint URI, the applicable public key URI, and an optional subscription key to the Oracle Utilities Delivery Team. The public key URI is made available by the OpenID Provider, commonly through the use of a discovery endpoint. Confirm this URI with the OpenID Provider if required. Refer to Access Tokens for information on UserInfo Endpoint URI requirements based on your setup.
  • Enable VPN access and test login accounts for the Oracle Utilities Delivery Team to your stage environment. This access is used to complete required testing and troubleshooting. If your test site is behind a firewall, ensure that you add the Oracle Utilities IP address to your allowlist. Contact your Delivery Team to retrieve the Oracle Utilities IP address value.

Back to Top

Access Tokens

Your web portal system must be able to supply an access token of the currently logged in user to Oracle Utilities embedded widgets. Oracle Utilities does not support refreshed access tokens that have expired. Your web portal system must support subsequent access token requests to retrieve a new access token when the previous access token has expired (see Authenticated Connection Storage).

JSON Web Token Access Tokens

Oracle Utilities recommends supporting access tokens as JSON Web Token (JWT), which conform to the JWT standard, as it allows for additional security validations as compared to opaque access tokens.

You must define the following JWT registered payload claims:

  • aud: The list of Audiences, which are authorized to call an Oracle Utilities Opower API endpoint. Audiences are defined by the OpenID Provider. Confirm the audience values with the OpenID Provider and provide the values to the Oracle Utilities Delivery Team.
  • iat and exp: These two claims define the access token expiration timeout. The iat claim defines the time the access token was issued, and the exp claim defines when the access token should expire. Be aware that Oracle Utilities enforces a maximum access token expiration timeout of 24 hours. If the difference between iat and exp claims in the token exceeds 24 hours, the 24 hour maximum from iat time is enforced.

Warning: Failure to provide valid aud, exp, or iat claims results in an authentication error.

Opaque Access Tokens

Oracle Utilities supports the use of opaque access tokens but discourages their use as they do not benefit from the security advantages of JWT access tokens.

Opaque access tokens do not provide a uniform method to describe access token expiration. Therefore, Oracle Utilities allows for the configuration of a token expiration. If no expiration is specified, Oracle Utilities enforces a default expiration of 15 minutes.

Back to Top

Creating a UserInfo Endpoint with Custom Claims

You must create a UserInfo API endpoint, which is used by Oracle Utilities to retrieve additional user information. After validating a JWT access token (see Access Tokens), Oracle Utilities sends an HTTPS GET request with the Authorization: Bearer OP_issued_access_token header to the URI that you have provided. Oracle Utilities calls this endpoint to:

Note: While the OpenID Connect standards require a POST method, Oracle Utilities does not require a POST method to support the OpenID Connect workflow. Therefore its definition is out of scope of this documentation.

Be aware that this secure GET request is a service-to-service request which uses the access token in the header section. No data or information is sent as part of the GET query parameters through the requested URL. The GET request must use HTTPS and thus SSL verification is also required for the UserInfo Endpoint.

Note: In addition to the security provided by the access token, you can also request a subscription key to be provided as part of the GET request. The subscription key must be retrieved from your OpenID Provider and then must be sent to your Oracle Utilities Delivery Team using the methods described in Contacting Your Delivery Team.

A sample UserInfo GET Endpoint is provided below, along with a table of possible responses.

GET /userinfo
Authorization: Bearer OP_issued_access_token

Status Code Response Comments
200 {
"sub": "248289761001",
"user_accounts": [
  {
   "id": "434343",
   "display_name": "My Home"
  },
   {
    "id": "1212121",
   "display_name": "My Office"
   }
  ]
}

sub: Required. This is any unique identifier for the logged in web user. Oracle Utilities recommends that you keep this value consistent with the web user. Oracle Utilities does not use this identifier for customer lookup.

user_accounts: A minimum of one account is required for this custom claim.

  • id: Required. The field or fields passed in this account ID must uniquely identify a customer record for retrieval. The most common value to pass in as the account ID is customer_id-premise_id. If multiple fields are required, as is the case with this example, the values are concatenated and separated with a hyphen. This account ID is what is sent to Oracle Utilities through the billing file integration between the utility and Oracle Utilities.
  • display_name: Optional. This is the account name that can be displayed in the user interface.
401 {
 "error": "invalid_token",
 "error_description": ""
} 		The bearer token has expired.

Back to Top

JSON Schemas

The example JSON schema specifies the structure and elements that Oracle Utilities expects in the JSON for the /userinfo endpoint, which is required in support of OpenID Connect implementation of SSO for embedded widgets. For more information on the /userinfo endpoint, see Creating a UserInfo Endpoint with Custom Claims.

{
	"definitions": {},
	"$schema": "http://json-schema.org/draft-07/schema#",
	"$id": "http://example.com/root.json",
	"type": "object",
	"title": "The Root Schema",
	"required": [
		"sub",
		"user_accounts"
	],
	"properties": {
		"sub": {
			"$id": "#/properties/sub",
			"type": "string",
			"title": "Unique identifier of currently logged in user",
			"default": "",
			"pattern": "^(.+)$"
		},
		"user_accounts": {
			"$id": "#/properties/user_accounts",
			"type": "array",
			"title": "The user_accounts Schema",
			"items": {
				"$id": "#/properties/user_accounts/items",
				"type": "object",
				"title": "The Items Schema",
				"minProperties": 1,
				"required": [
					"id"
				],
				"properties": {
					"id": {
						"$id": "#/properties/user_accounts/items/properties/id",
						"type": "string",
						"title": "account id",
						"pattern": "^(.+)$"
					},
					"display_name": {
						"$id": "#/properties/user_accounts/items/properties/display_name",
						"type": "string",
						"title": "The display_name Schema",
						"default": ""
					}
				}
			}
		}
	}
}

Authenticated Connection Storage

Oracle Utilities stores access tokens and user information after user validation. Any subsequent calls to Oracle Utilities services while the access token is still valid re-use the stored information. After expiration, Oracle Utilities requires a new token to initiate another authenticated connection. For information on supplying access tokens, see the Oracle Utilities Opower Digital Self Service - Energy Management Embeddable Widgets Integration Guide.

Back to Top

OpenID Connect Workflow

The following diagram describes the overall workflow that is completed to support OpenID Connect authentication. This includes a user's initial log in to the utility portal through the final display of a widget. A step-by-step description of the workflow is provided along with the diagram.

Note: The workflow described below assumes the use of JWT access tokens (see JSON Web Token Access Tokens). Access token validation steps are not applied by Oracle Utilities if opaque access tokens are used, and any opaque access token validation is the responsibility of the utility.

OpenID Connect workflow diagram, refer to accompanying documentation for a full description of steps in this workflow

When a user accesses embedded widget content and an active user session is not available, the authentication process using OpenID Connect is started. This process involves the user, the utility portal hosting the embedded widget, the utility OpenID Provider, the embedded widget, and Oracle Utilities services and data.

  1. The process begins with a user accessing a utility portal page with an embedded widget. A user access token is required for Oracle Utilities to authenticate the user and display an embedded widget. A user access token can be obtained by following the example steps below for OpenID Connect, or using other means:
    1. The utility portal redirects the user to a login page hosted by the utility OpenID Provider to begin the authorization process.
    2. The utility OpenID Provider redirects the authenticated user to the utility portal with an authorization code.
    3. The utility portal requests an OpenID Connect token from the utility OpenID Provider by providing a clientID and client secret and an authorization code.
    4. The utility OpenID Provider returns an access token to the utility portal. This completes the user's log in to the utility portal.
  2. After a valid access token is retrieved by the utility portal, the utility portal makes a request to load the embedded widget for the user.
  3. An embedded widget emits browser window event opower:unauthorized.
  4. The utility portal must respond to this event with a user access token. For more information on these requirements, see Access Tokens.
  5. The embedded widget provides the user access token to Oracle Utilities using an API call.
  6. Oracle Utilities starts user access token validation for JWT access tokens, which first requests the applicable public keys from the utility OpenID Provider.
  7. The utility OpenID Provider public key URI provides the public key information to Oracle Utilities.
  8. Oracle Utilities validates the signature of the user JWT access token with the information provided by the utility.
  9. Oracle Utilities requests user information from the UserInfo endpoint that is provided by the utility.
  10. The utility portal provides the requested user information through a UserInfo Endpoint. For more information on these requirements, see Creating a UserInfo Endpoint with Custom Claims. Be aware that the user information request uses a timeout of 10 seconds.
  11. Oracle Utilities retrieves the applicable user data.
  12. Oracle Utilities provides the user data to the embedded widget.
  13. The embedded widget updates on the utility portal to reflect and display applicable user data.

Back to Top