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
Term

Function Block

FB
Term

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_35_39;
ÊIntervalDuration=900_3600;BlockDuration=Daily; HistoryLength= 34128000;SubscriptionFrequency=Daily;
Ê AccountCollection=5;BR=1;”

Example 2:

Scope = “FB=1_3_4_5_7_8_13_14_15_18_19_31_32_34_35_37_38_39_40;
ÊIntervalDuration=300_900_3600;BlockDuration=Daily_BillingPeriod_Weekly_Monthly; HistoryLength=63072000;SubscriptionFrequency=Daily;
Ê AccountCollection=5;BR=1;”

Example 3:

Scope = “FB=1_3_4_5_8_13_14_18_19_31_34_35_39_40;
ÊIntervalDuration=300_900_3600;BlockDuration=Daily_BillingPeriod_Weekly_Monthly; HistoryLength=94608000;SubscriptionFrequency=Daily;
Ê 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;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”



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.