Encoding of OAuth 2.0 “scope”
Ref: authorization.docx Section 2.6
The following defines a potential OAuth 2.0 “scope” parameter format. It is based on the Green Button Test Plan function blocks for the data custodian (defines what is in the file).
From the test plan (these are the individual blocks of conformance that will be tested for):
1.1.1 Function Blocks Terms for Scope
FB
|
Function Block |
FB |
Function Block |
1 |
[FB_1] Common Data Custodian |
18 |
[FB_18] Multiple Usage Points |
2 |
[FB_2] Green Button Download My Data |
19 |
[FB_19] Partial update data |
3 |
[FB_3] Core Green Button Connect My Data |
27 |
[FB_27] Usage Summary with Demands and Previous Day Attributes |
4 |
[FB_4] Interval Metering |
28 |
[FB_28] Usage Summary Costs for Current Billing Period |
5 |
[FB_5] Interval Electricity Metering |
29 |
[FB_29] Temperature |
6 |
[FB_6] Demand Electricity Metering |
32 |
[FB_32] Resource Level REST |
7 |
[FB_7] Net Metering |
33 |
[FB_33] Management REST Interfaces |
8 |
[FB_8] Forward and Reverse Metering |
34 |
[FB_34] SFTP for Bulk |
9 |
[FB_9] Register Values |
35 |
[FB_35] REST for Bulk |
10 |
[FB_10] Gas |
36 |
[FB_36] Third Party (Client) Dynamic Registration |
11 |
[FB_11] Water |
37 |
[FB_37] Query Parameters |
12 |
[FB_12] Cost of Interval Data |
38 |
[FB_38] On Demand Requests |
13 |
[FB_13] Security and Privacy classes |
39 |
[FB_39] PUSH model |
14 |
[FB_14] Authorization and Authentication |
40 |
[FB_40] Offline Authorization |
15 |
[FB_15] Usage Summary |
41 |
[FB_41] Manage Authorization Resource |
16 |
[FB_16] Usage Summary with Cost |
42 |
[FB_42] Third Party Core REST Services |
17 |
[FB_17] Power Quality Summary |
43 |
[FB_43] Third Party Management REST Services |
|
|
44 |
[FB_44] Manage ApplicationInformation Resource |
1.1.2 Extended Backus-Naur Form (EBNF) for Scope parameter:[1]
Term |
Expansion |
Scope |
[ FBTerms ], [ ValueTerms ], [ ResourceTerms ]; |
FBTerms |
“FB=“, { [FBTerm], ”_”} , FBTerm, ScopeDelimiter ; |
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” | “42” | “43” |
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:
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 |
This is the minimum default length of an interval in seconds (e.g. 900 for 15 minutes, 3600 for one hour, …) |
BlockDuration |
This is the length of a block that contains the intervals (based on enumeration of MacroPeriodKind in ESPI above as namedFrequency) |
HistoryLength |
This is the length of history buffer seconds |
BulkAccountCollection |
Used where the DC 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 – e.g. 4 UsagePoints would be BulkAccountCollection=4. |
1.1.3 Scope Examples for use In ApplicationInformation
The scope parameter in ApplicationInformation provides the scopes available from the DataCustodian. They are compound in that a particular scope for an authorization may be a subset.
Example 1:
Scope = “FB=1_3_4_5_8_13_18_19_31_34_
ÊIntervalDuration=900_3600;
Ê AccountCollection=5;BR=1;”
Example 2:
Scope = “FB=1_3_4_5_7_8_13_14_15_18_
ÊIntervalDuration=300_900_
Ê AccountCollection=5;BR=1;”
Example 3:
Scope = “FB=1_3_4_5_8_13_14_18_19_31_
ÊIntervalDuration=300_900_
Ê AccountCollection=5;BR=1;”
1.1.4 Scope Examples for Individual Authorizations
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;
Ê 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_
Ê BlockDuration=monthly;
HistoryLength=94608000”
Note: The current is revised from earlier syntax with comma delimiters removed due to some unpredictable behavior in some OAuth code libraries that recognized comma and space as scope delimiters and ESPI wants the scope strings to be atomic.