How The Green Button API Initiative Takes Advantage of OAuth's Scope Parameter

December 9, 2016

MyData API Patterns: OAUTH for Green Button

The article is being updated to reflect the current Function Block values.
Please do not assume accuracy until this message is gone.

Part 4

OAuth uses the term scope to describe the depth or level of authorization permitted or required in a data-centric transaction. As applied to Green Button, an open data project to manage the interchange of information for energy data between utilities, third-party providers, and consumers, scope has specific needs. Start with the Green Button background, and follow along as we define its underlying technologies.

In this article, we explain the structure of Green Buttons’ scope parameters and illustrate the data exchanges and protocol used to implement Green Button’s scope negotiation.

Note that there are two scenarios:

Retail customer starts at data custodian: This may occur when the retail customer is looking for a service and asks the energy service provider what third party providers are available. For instance, the customer might ask the utility company to suggest a solar company who is equipped to service his house.
Retail customer starts at third party: This may occur when the retail customer is pursuing a specific service provider. In this scenario, the customer and solar company might discuss the options available, and need access to information from the utility company in order to negotiate rates and cost savings.

The exchanges described here utilize the same web browser redirections used by OAuth 2.0. They share the express goal of identifying the third party and data custodian to one other and determining which available scopes the third party can use in the OAuth 2.0 authorization sequence after scope negotiation is completed.

Green Button SCOPE Syntax

As shown in the scope negotiations that follow, the data custodian is obligated to provide one or more scope strings to the third party. Usually, this is often only one option. However, it is possible to offer more than one from which a third party can choose.

OAuth defines the scope parameter as a string (see OAuth RFC 6749, section 3.3 “space-delimited, case sensitive strings”).

The following tables define how to encode a scope string using Extended Backus–Naur Form (EBNF). Note that the Function block terms (FBTerms) represent sets of behavioral and data requirements that allow for different provisions by data custodians. For example, function block 5 indicates support for electricity metering; function block 10 indicates support for gas metering. These tables illustrate the potential diversity of Green Button data and how its availability can be conveyed to the third party. Note that there is no personally identifiable information (PII) in the scope string so it is inherently anonymous.

Here are two examples of a scope parameter for Green Button assembled with the syntax description that follows:

Electricity Interval Metering of hourly load profile blocked monthly for 13 months and a usage summary:

Scope = "FB=1_3_4_5_13_14_15_19_37_39;IntervalDuration=3600;BlockDuration=monthly; HistoryLength=94608000"

Monthly-only electricity metering including summaries and costs for 13 months:

Scope = "FB=1_3_4_5_13_14_15_16_19_37_39;IntervalDuration=monthly; BlockDuration=monthly; HistoryLength=94608000"

If the data custodian and retail customer offer both strings to the third party, the redirect (see below) contains:

.../Scope = "FB=1_3_4_5_13_14_15_19_37_39;IntervalDuration=3600;BlockDuration=monthly; HistoryLength=94608000" & Scope = "FB=1_3_4_5_13_14_15_16_19_37_39;IntervalDuration=monthly; BlockDuration=monthly; HistoryLength=94608000"

Term	Expansion
Scope	[ FBTerms ], [ ValueTerms ], [ ResourceTerms ];
FBTerms	“FB=“, { [FBTerm], ”_”} , FBTerm, ScopeDelimiter ;/td>
FBTerm	“1” \| “2” \| “3” \| “4” \| “5” \| “6” \| “7” \| “8” \| “9” \| “10” \| “11” \| “12” \| “13” \| “14” \| “15” \| “16” \| “17” \| “18” \| “19” \| “27” \| “28” \| “29” \| “32” \| “33” \| “34” \| “35” \| “36” \| “37” \| “38” \| “39” \| “40” \| “41” \| “44”
ValueTerms	{ ( "IntervalDuration=", namedOrNumber,{“_”, namedOrNumber}),
	\| ( "BlockDuration=", namedOrNumber,{“_”, namedOrNumber}),
	\| ( "HistoryLength=", nonNegativeNumber),
	\| ( "SubscriptionFrequency=", nonNegativeNumber \| namedFrequency), ScopeDelimiter };
ResourceTerms	{ (“AccountCollection=”, nonNegativeNumber) \| “BR=”, brId), ScopeDelimiter}
ScopeDelimiter	“;”
namedFrequency	“billingPeriod” \| “daily” \| “monthly” \| “seasonal” \| “weekly” \|
namedOrNumber	nonNegativeNumber \| namedFrequency;
brID	Character, {Character}*;
nonNegativeNumber	digit, { digit };
Digit	0 \| "1" \| "2" \| "3" \| "4" \| "5" \| "6" \| "7" \| "8" \| "9" ;
Character	Digit \| “-” \| "A" \| "B" \| "C" \| "D" \| "E" \| "F" \| "G" \| "H" \| "I" \| "J" \| "K" \| "L" \| "M" \| "N" \| "O" \| "P" \| "Q" \| "R" \| "S" \| "T" \| "U" \| "V" \| "W" \| "X" \| "Y" \| "Z" \| "a" \| "b" \| "c" \| "d" \| "e" \| "f" \| "g" \| "h" \| "i" \| "j" \| "k" \| "l" \| "m" \| "n" \| "o" \| "p" \| "q" \| "r" \| "s" \| "t" \| "u" \| "v" \| "w" \| "x" \| "y" \| "z" ;

Where:

Term	Expansion
ResourceTerms	If a Bulk Resource is specified via the “BR” term, the value of the {bulkId} is provided after the equals sign (“=”). There could be one or more terms in this list that express the granularity of notifications about resource changes. If the Subscription has more than one UsagePoint, the AccountCollection term can indicate the number of UsagePoints included
FBTerms	The function blocks supported
ValueTerms	These are parameterized terms
IntervalDuration	The minimum default length of an interval in seconds (e.g. 900 for 15 minutes, 3600 for one hour, and so on)
BlockDuration	The length of a block that contains the intervals (based on enumeration of MacroPeriodKind in ESPI above as namedFrequency)
HistoryLength	The length of history buffer seconds
AccountCollection	Used where the data custodian wants to provide for the reporting of multiple UsagePoints in a single Subscription. The number of UsagePoints is represented by the value in the assignment statement; for example 4 UsagePoints would be AccountCollection=4.

The function block referenced above works with these values:

FB Term	Function Block	FB Term	Function Block
1	[FB_1] Common Data Custodian Required of all data custodian implementations.	19	[FB_19] Partial update data Support for partial updates of data consisting of only new IntervalBlock resources.
2	[FB_2] Green Button Download My Data Support for retail customer file download from data custodian website.	27	[FB_27] Usage Summary with Demands and Previous Day Attributes Support for extra measurements in UsageSummary resource.
3	[FB_3] Core Green Button Connect My Data Support for the authorization and automated REST web services for Green Button data.	28	[FB_28] Usage Summary Costs for Current Billing Period Support for “current billing period” summary costs.
4	[FB_4] Interval Metering Support for Interval (time based) series of measurements.	29	[FB_29] Temperature Support for Temperature measurements readings.
5	[FB_5] Interval Electricity Metering Specific support for Wh interval readings.	30	[FB_30] Common User Experience Common user experience for DMD.
6	[FB_6] Demand Electricity Metering Support for W, VAR, and VA measurements	32	[FB_32] Resource Level REST Support for APIs that access by resource types.
7	[FB_7] Net Metering Support for NET metering measurements.	33	[FB_33] Management REST Interfaces Support for management REST interface that allows all APIs without further authorization.
8	[FB_8] Forward and Reverse Metering Support for separate forward and reverse channels in interval data.	34	[FB_34] SFTP for Bulk Support for bulk data using SFTP to pull data from data custodian (single access of all resources authorized under single bulkId).
9	[FB_9] Register Values Support for “dial” reading.	35	[FB_35] REST for Bulk Support for bulk data using REST GET to pull data from data custodian (single access of all resources authorized under single bulkId).
10	[FB_10] Gas Support for Gas Therm consumption readings.	36	[FB_36] Third Party (Client) Dynamic Registration Support for dynamic registration of third parties via API.
11	[FB_11] Water Support for water consumption readings.	37	[FB_37] Query Parameters Support for updated and published max and min date query parameters in REST requests.
12	[FB_12] Cost of Interval Data Interval data has cost-attributed to each interval.	38	[FB_38] On Demand Requests Support for On-Demand REST requests (without need for prior Notification).
13	[FB_13] Security and Privacy classes In CMD, required security and privacy.	39	[FB_39] PUSH model Support for data custodian notification of available resources followed by GET by third party
14	[FB_14] Authorization and Authentication Support for OAuth 2.0 and related requirements.	40	[FB_40] Offline Authorization Support for non-API-based authorizations (no OAuth).
15	[FB_15] Usage Summary Support for the UsageSummary resource.	41	[FB_41] Manage Authorization Resource Ability to PUT and DELETE the Authorization resource to make updates to an authorization.
16	[FB_16] Usage Summary with Cost Support for cost elements of the UsageSummary resource.	44	[FB_44] Manage ApplicationInformation Resource Ability to PUT and DELETE the ApplicationInformation resource to make updates to the third party / data custodian relationship.
17	[FB_17] Power Quality Summary Support for the PowerQualitySummary resource		…
18	[FB_18] Multiple Usage Points Support for multiple UsagePoint resources in a single file.		There are more Function Blocks; see this page for a deep dive into FBs.

Retail Customer Starts at Data Custodian

Remember, there are two scenarios: The customer starts with the data custodian or the third party. In ESPI version 3.3 and later, the customer MUST start at the third party; although the data custodian could give a link to the customer that takes the customer to the third party website to start the process there with the third party.

Let’s walk through each process graphically, starting where the retail customer begins with the utility company. Or in formal terms, at the web Portal of the data custodian. Note that in each scenario, what is required is that the retail customer browser and at both the data custodian and retail customer site. Depending on the needs of the services being provided, these steps may require retail customer interaction, or may be “click-through” without additional need for interaction.

The following steps represent “transitions” between the data custodian and third party application initiated by the data custodian’s retail customer. The steps below enumerate the actions taken by the retail customer, starting with her initial browser selection to the start of the “OAuth 2.0 Authorization Phase” sequence:

The retail customer selects the data custodian’s website.
The retail customer completes her login and completes all the data custodian’s required documents.

For example, the data custodian may require the retail customer to navigate through its webpages to determine the availability of customer data the third party may access. These interactions are not a requirement of the Green Button implementation.

At an appropriate step, determined by the data custodian, the customer is redirected to the selected third party. Contained within the HTTP redirection message are query parameters that identify the data custodian and the resources the retail customer granted to the third party during the “OAuth 2.0 Authorization Phase.”

(Scope={ScopeString}&[scope={ScopeString}&])

At the third party site, the retail customer completes her login (as needed). Based on scopes contained within the data custodian’s redirect message, the third party provides the retail customer with a webpage or dialog, allowing her to select which data custodian resource scopes she wants to share. If there is only one acceptable choice, the third party may proceed to the next step without displaying those choices.
After that selection is complete, the next step is a HTTP redirection message to the data custodian’s OAuth 2.0 authorization Endpoint.

UML Sequence Diagram

Figure 2: Data Custodian Point of View UML Model

Retail Customer Starts at Third Party

In the second scenario, the customer begins the process with the third party provider. Let’s step through each part of the process.

The following steps represent “transitions” between the data custodian and the third party application, initiated by the third party’s retail customer.

Note that if the third party seeks to obtain authorization from multiple data custodians, it can repeat portions of this process to maximize the quality of the customer experience.
Here are the actions taken by the retail customer, starting with his initial browser selection:

Retail customer begins at the third party’s website.
The retail customer completes his login and completes any documents required by the third party.

The third party may have the retail customer navigate through any number of webpages to meet its own needs. These interactions are not a requirement of the Green Button ESPI implementation.

The third party presents the retail customer with a webpage or dialog box in which he selects which data custodian the third party is authorized to access. After he does so, the retail customer’s browser is redirected to the selected data custodian’s scope selection endpoint. Contained within the HTTP redirection message is a query parameter that identifies the third party to the data custodian.
Once directed to the data custodian site by his chosen third party, the retail customer completes the login process, as well as fills in any documents the data custodian requires.

Again, that process may include as many webpages as the data custodian deems are necessary to determine the availability of customer data or permit access. These interactions are not a requirement of the Green Button ESPI implementation.

Once that’s done, at an appropriate step the data custodian determines, the customer is redirected (back) to the selected third party. Contained within the HTTP redirection message are query parameters that identify the data custodian and the resources the third party may be granted access to by the Retail Customer during the “Oauth 2.0 Authorization Phase.”

(Scope=={ScopeString}&[scope={ScopeString}&])

Based on scopes contained within the data custodian’s redirect message, the third party displays a webpage to the retail customer with a web screen, wherein he is asked to select which data custodian resource scopes he is willing to share. (If there is only one acceptable choice, that step may be skipped.)
With all permissions granted, the next step is a HTTP redirection message to the data custodian’s OAuth 2.0 authorization endpoint.