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

This is part 4 of our series What is The Green Button API initiative and How It Took OAuth To An Entirely New Level. In part 3 we described the building blocks of Green Button technology with respect to authorization of access to data provided to third parties.

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.
   

Retail Customer Starts at Data Custodian

Remember, there are two scenarios: The customer starts with the data custodian or 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.

Figure 1: Data Custodian Point of View

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.

Figure 3: Third Party Point of View

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.

UML Sequence Diagram

Figure 4: Retail Customer Starts at Third Party

This is part 4 of our series What is The Green Button API initiative and How It Took OAuth To An Entirely New Level. In part 5, we'll discuss how Green Button made the "pull-only" OAuth standard support push APIs too. This series was co-authored by Dr. David Wollman, Deputy Director, Smart Grid and Cyber-Physical Systems Program Office, National Institute of Standards and Technology.

Marty Burns is an Electronic Engineer, Smart Grid and Cyber-Physical Systems Program Office, National Institute of Standards and Technology

Comments