[Openid-specs-risc] Request for vote on RISC Implementer's Draft

Marius Scurtescu mscurtescu at google.com
Wed Apr 25 01:56:37 UTC 2018


Comments inline...

On Mon, Apr 23, 2018 at 5:15 PM, Mike Jones via Openid-specs-risc <
openid-specs-risc at lists.openid.net> wrote:

> Based a quick skim wearing my foundation secretary hat, I need the
> following things to get these ready to post:
>
>    - Rename risc-secevent to openid-risc-secevent-1_0
>
> renamed to openid-risc-profile-1_0, see bellow



>
>    -
>    - Rename risc-event-types to openid-risc-event-types-1_0
>
> done



>
>    -
>    - Rename oauth-event-types to oauth-event-types_1_0
>
> done



>
>    -
>    - Provide the openid-risc-profile-1_0 to also post
>
> sorry about the confusion, that was risc-secevent, renamed to
openid-risc-profile-1_0



>
>    -
>    - Add “1.0” to the end of each of the spec titles.
>
> done



>
>    -
>    - Optionally, also prefix the first two spec titles with “OpenID”,
>    such as “OpenID RISC Event Types 1.0”.
>
> done



>
>    -
>    - Include a URL for any specification references.  For instance, the
>    RISC-PROFILE should include the URL “http://openid.net/specs/
>    openid-risc-profile-1_0.html”.
>
> done



>
>    -
>    - Include dates and authors in all specification references – both for
>    the WG specs and for IETF specs.  For instance, the SET reference is
>    missing the data and author information (and the URL).
>
> done



>
>    -
>    - Run a spelling and grammar check.  For instance, I’m sure you didn’t
>    mean to say “This document defines the RTISC Event Types”.
>
> done



>
>    -
>    - Provide a copy of the primary source documents for each of the
>    specifications (the .xml files) as well as the .txt and .html output from
>    xml2rfc that you intend for me to post at http:/openid.net/specs/.  If
>    you’re using MarkDown, please also provide me the .md files and the
>    procedure you use to convert the .md files to .xml.  I may verify that they
>    build correctly.
>
> Attached


Thanks a lot Mike!


>
>    -
>
>
>
>                                                                 -- Mike
>
>
>
> *From:* Adam Dawes <adawes at google.com>
> *Sent:* Monday, April 23, 2018 3:49 PM
> *To:* Mike Jones <Michael.Jones at microsoft.com>
> *Cc:* Dick Hardt via Openid-specs-risc <openid-specs-risc at lists.openid.net
> >
> *Subject:* Request for vote on RISC Implementer's Draft
>
>
>
> Hi Mike,
>
>
>
> This is a formal request from the RISC working group to call a vote to
> make the following specs implementers draft:
>
>
>
> RISC secevents
> <https://bitbucket.org/openid/risc/src/98ade8086b82c080e1bcd2060252c20116b44009/risc-secevent.txt?at=master&fileviewer=file-view-default>
>
> RISC event types
> <https://bitbucket.org/openid/risc/src/98ade8086b82c080e1bcd2060252c20116b44009/risc-event-types.txt?at=master&fileviewer=file-view-default>
>
> OAuth event types
> <https://bitbucket.org/openid/risc/src/98ade8086b82c080e1bcd2060252c20116b44009/oauth-event-types.txt?at=master&fileviewer=file-view-default>
>
>
>
> As per our conversation last week, you said that you would review the
> drafts this week for proper formatting/references/etc and would likely come
> back with changes before issuing the specs for a vote.
>
>
>
> The group wanted to take next week's call, 4/30 @9:30, to run through the
> errata changes and lock them down. Would be ideal if you can attend as well.
>
>
>
> Please let me know if you have any other questions.
>
>
>
> thanks,
>
> AD
>
> --
>
> Adam Dawes | Sr. Product Manager | adawes at google.com | +1 650-214-2410
>
>
>
> _______________________________________________
> Openid-specs-risc mailing list
> Openid-specs-risc at lists.openid.net
> http://lists.openid.net/mailman/listinfo/openid-specs-risc
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openid.net/pipermail/openid-specs-risc/attachments/20180424/35f7c3fa/attachment-0004.html>
-------------- next part --------------




                                                            M. Scurtescu
                                                                  Google
                                                              A. Backman
                                                                  Amazon
                                                                 P. Hunt
                                                                  Oracle
                                                              J. Bradley
                                                                  Yubico
                                                          April 24, 2018


                         OAuth Event Types 1.0
                         oauth-event-types-1_0

Abstract

   This document defines the OAuth Event Types.  Event Types are
   introduced and defined in Security Event Token (SET) [SET].

Table of Contents

   1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   1
     1.1.  Notational Conventions  . . . . . . . . . . . . . . . . .   2
   2.  OAuth Specific Subject Identifier Types . . . . . . . . . . .   2
     2.1.  Token Subject Identifier Type . . . . . . . . . . . . . .   2
     2.2.  Client Subject Identifier Type  . . . . . . . . . . . . .   3
   3.  Event Types . . . . . . . . . . . . . . . . . . . . . . . . .   3
     3.1.  Token Issued  . . . . . . . . . . . . . . . . . . . . . .   3
     3.2.  Token Revoked . . . . . . . . . . . . . . . . . . . . . .   4
     3.3.  Tokens Revoked  . . . . . . . . . . . . . . . . . . . . .   6
     3.4.  Client Disabled . . . . . . . . . . . . . . . . . . . . .   7
     3.5.  Client Enabled  . . . . . . . . . . . . . . . . . . . . .   8
     3.6.  Client Credential Changed . . . . . . . . . . . . . . . .   8
   4.  IANA Considerations . . . . . . . . . . . . . . . . . . . . .   8
     4.1.  Subject Identifier Type Registry  . . . . . . . . . . . .   8
   5.  Normative References  . . . . . . . . . . . . . . . . . . . .   9
   Authors' Addresses  . . . . . . . . . . . . . . . . . . . . . . .   9

1.  Introduction

   This specification is based on RISC Profile [RISC-PROFILE] and uses
   the subject identifiers defined there.

   The "aud" claim identifies the OAuth 2 client and its value SHOULD be
   the OAuth 2 [RFC6749] client id.






Scurtescu, et al.       Expires October 26, 2018                [Page 1]


                            oauth-event-types                 April 2018


1.1.  Notational Conventions

   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
   "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
   "OPTIONAL" in this document are to be interpreted as described in BCP
   14 [RFC2119] [RFC8174] when, and only when, they appear in all
   capitals, as shown here.

2.  OAuth Specific Subject Identifier Types

   This section defines OAuth specific Subject Identifier Types.
   Subject identifiers are defined in Section 2 of [RISC-PROFILE].

2.1.  Token Subject Identifier Type

   A Token Subject Identifier Type describes an OAuth 2 token subject
   and it is identified by the name "oauth_token".

   Subject Identifiers of this type MUST contain the following claims:

   o  token_type - required, describes the OAuth 2 token type.  Possible
      values:

      *  access_token

      *  authorization_code

      *  refresh_token

   o  token_identifier_alg - required, describes how is the token string
      in the "token" attribute to be interpreted.  Possible values:

      *  plain - plain token string

      *  prefix - token string prefix

      *  hash_* - token string hash, actual hash algorithms added as a
         suffix.  TODO: create individual values for each hash
         algorithm.

   o  token - required, the token identifier, as described by
      "token_identifier_alg".









Scurtescu, et al.       Expires October 26, 2018                [Page 2]


                            oauth-event-types                 April 2018


   "subject": {
     "subject_type": "oauth_token",
     "token_type": "refresh_token",
     "token_identifier_alg": "plain",
     "token": "7265667265736820746F6B656E20737472696E67"
   }

             Figure 1: Example: Token Subject Identifier Type

2.2.  Client Subject Identifier Type

   A Client Subject Identifier Type describes an OAuth 2 client subject
   and it is identified by the name "oauth_client".

   Subjects identifiers of this type MUST contain the following claim:

   o  client_id - required, the OAuth 2 client id.

   "subject": {
     "subject_type": "oauth_client",
     "client_id": "636C69656E74206964"
   }

             Figure 2: Example: Client Subject Identifier Type

3.  Event Types

   The base URI for OAuth Event Types is:
   https://schemas.openid.net/secevent/oauth/event-type/

3.1.  Token Issued

   Event Type URI:
   https://schemas.openid.net/secevent/oauth/event-type/token-issued

   Token Issued signals that a new token was issued.

   Attributes:

   o  subject - required, a Subjectect Identifier as defined by
      Section 2.1 that identifies the token.

   o  token_subject - optional, a Subject Identifier as defined by
      Section 2.1 of [RISC-PROFILE] that identifies the account
      associated with the token.

   o  TODO: OAuth flow and endpoints involved in the process?  For
      example: redirect_uri, response_type, origin?



Scurtescu, et al.       Expires October 26, 2018                [Page 3]


                            oauth-event-types                 April 2018


   The token SHOULD be uniquely identified by the provided attributes,
   either by "subject" alone or by "subject" in combination with
   "token_subject".  The token is unique in the context of a given
   Transmitter and not globally unique.  TODO: do we need a "iss"
   attribute for the "oauth_token" Subject Type?

   {
     "iss": "https://idp.example.com/",
     "jti": "756E69717565206964656E746966696572",
     "iat": 1508184845,
     "aud": "636C69656E745F6964",
     "events": {
       "https://schemas.openid.net/secevent/oauth/event-type/\
       token-issued": {
         "subject": {
           "subject_type": "oauth_token",
           "token_type": "refresh_token",
           "token_identifier_alg": "token_string",
           "token": "7265667265736820746F6B656E20737472696E67"
         },
         "token_subject" {
           "subject_type": "iss-sub",
           "iss": "https://idp.example.com/",
           "sub": "75736572206964"
         }
       }
     }
   }

   _(the event type URI is wrapped, the backslash is the continuation
   character)_

                      Figure 3: Example: Token Issued

3.2.  Token Revoked

   Event Type URI:
   https://schemas.openid.net/secevent/oauth/event-type/token-revoked

   Token Revoked signals that the token identified by this event was
   revoked.

   Attributes:

   o  subject - required, a Subjectect Identifier as defined by
      Section 2.1 that identifies the token.





Scurtescu, et al.       Expires October 26, 2018                [Page 4]


                            oauth-event-types                 April 2018


   o  token_subject - optional, a Subject Identifier as defined by
      Section 2.1 of [RISC-PROFILE] that identifies the account
      associated with the token.

   o  reason - optional, the reason why the token was revoked.  Possible
      values:

      *  inactive - token was revoked by the issuer because of
         inactivity

      *  too_many - token was revoked by the issuer because an internal
         limit was reached

      *  api - token was revoked through an API call like [RFC7009]

      *  user - token was revoked explicitly by the user

      *  issuer - token was revoked by the issuer for some other reason

      *  TODO: add extension mechanism (either through URIs or IANA
         registry)

   The token SHOULD be uniquely identified by the provided attributes,
   either by "subject" alone or by "subject" in combination with
   "token_subject".  The token is unique in the context of a given
   Transmitter and not globally unique.  TODO: do we need a "iss"
   attribute for the "oauth_token" Subject Type?
























Scurtescu, et al.       Expires October 26, 2018                [Page 5]


                            oauth-event-types                 April 2018


   {
     "iss": "https://idp.example.com/",
     "jti": "756E69717565206964656E746966696572",
     "iat": 1508184845,
     "aud": "636C69656E745F6964",
     "events": {
       "https://schemas.openid.net/secevent/oauth/event-type/\
       token-revoked": {
         "subject": {
           "subject_type": "oauth_token",
           "token_type": "refresh_token",
           "token_identifier_alg": "token_string",
           "token": "7265667265736820746F6B656E20737472696E67"
         },
         "token_subject" {
           "subject_type": "iss-sub",
           "iss": "https://idp.example.com/",
           "sub": "75736572206964"
         },
         "reason": "inactive"
       }
     }
   }

   _(the event type URI is wrapped, the backslash is the continuation
   character)_

                     Figure 4: Example: Token Revoked

3.3.  Tokens Revoked

   Event Type URI:
   https://schemas.openid.net/secevent/oauth/event-type/tokens-revoked

   Tokens Revoked signals that all tokens issued for the account
   identified by the subject have been revoked.

   Attributes:

   o  subject - optional, a Subject Identifier as defined by Section 2.1
      of [RISC-PROFILE] that identifies the account associated with the
      token.

   o  reason - optional, the reason why all the tokens were revoked.
      Possible values:

      *  user - all tokens were revoked explicitly by the user




Scurtescu, et al.       Expires October 26, 2018                [Page 6]


                            oauth-event-types                 April 2018


      *  issuer - all tokens were revoked by the issuer

      *  TODO: add extension mechanism (either through URIs or IANA
         registry)

   {
     "iss": "https://idp.example.com/",
     "jti": "756E69717565206964656E746966696572",
     "iat": 1508184845,
     "aud": "636C69656E745F6964",
     "events": {
       "https://schemas.openid.net/secevent/oauth/event-type/\
       tokens-revoked": {
         "subject": {
           "subject_type": "iss-sub",
           "iss": "https://idp.example.com/",
           "sub": "7375626A656374",
         },
       }
     }
   }

   _(the event type URI is wrapped, the backslash is the continuation
   character)_

                     Figure 5: Example: Tokens Revoked

3.4.  Client Disabled

   Event Type URI:
   https://schemas.openid.net/secevent/oauth/event-type/client-disabled

   Client Disabled signals that the client identified by the "aud" claim
   has been disabled.  The client may be enabled (Section 3.5) in the
   future.

   Attributes: TODO use client subject identifier














Scurtescu, et al.       Expires October 26, 2018                [Page 7]


                            oauth-event-types                 April 2018


   {
     "iss": "https://idp.example.com/",
     "jti": "756E69717565206964656E746966696572",
     "iat": 1508184845,
     "aud": "636C69656E745F6964",
     "events": {
       "https://schemas.openid.net/secevent/oauth/event-type/\
       client-disabled": {}
     }
   }

   _(the event type URI is wrapped, the backslash is the continuation
   character)_

                    Figure 6: Example: Client Disabled

3.5.  Client Enabled

   Event Type URI:
   https://schemas.openid.net/secevent/oauth/event-type/client-enabled

   Client Enabled signals that the client identified by the "aud" claim
   has been enabled.

   Attributes: TODO use client subject identifier

3.6.  Client Credential Changed

   Event Type URI:
   https://schemas.openid.net/secevent/oauth/event-type/client-
   credential-changed

   Client Credential Changed signals that one of the credentials of the
   client identified by the "aud" claim has changed.  For example the
   client secret has changed.

   Attributes: TODO use client subject identifier

4.  IANA Considerations

4.1.  Subject Identifier Type Registry

   TODO: register "oauth_token" and "oauth_client" subject identifier
   types.







Scurtescu, et al.       Expires October 26, 2018                [Page 8]


                            oauth-event-types                 April 2018


5.  Normative References

   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
              Requirement Levels", BCP 14, RFC 2119,
              DOI 10.17487/RFC2119, March 1997, <https://www.rfc-
              editor.org/info/rfc2119>.

   [RFC6749]  Hardt, D., Ed., "The OAuth 2.0 Authorization Framework",
              RFC 6749, DOI 10.17487/RFC6749, October 2012,
              <https://www.rfc-editor.org/info/rfc6749>.

   [RFC7009]  Lodderstedt, T., Ed., Dronia, S., and M. Scurtescu, "OAuth
              2.0 Token Revocation", RFC 7009, DOI 10.17487/RFC7009,
              August 2013, <https://www.rfc-editor.org/info/rfc7009>.

   [RFC8174]  Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
              2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
              May 2017, <https://www.rfc-editor.org/info/rfc8174>.

   [RISC-PROFILE]
              Scurtescu, M., Backman, A., and J. Bradley, "OpenID RISC
              Profile of IETF Security Events 1.0", April 2018,
              <http://openid.net/specs/openid-risc-profile-1_0.html>.

   [SET]      Hunt, P., Ed., Jones, M., Denniss, W., and M. Ansari,
              "Security Event Token (SET)", April 2018,
              <https://tools.ietf.org/html/draft-ietf-secevent-token-
              09>.

Authors' Addresses

   Marius Scurtescu
   Google

   Email: mscurtescu at google.com


   Annabelle Backman
   Amazon

   Email: richanna at amazon.com


   Phil Hunt
   Oracle Corporation

   Email: phil.hunt at yahoo.com




Scurtescu, et al.       Expires October 26, 2018                [Page 9]


                            oauth-event-types                 April 2018


   John Bradley
   Yubico

   Email: secevemt at ve7jtb.com















































Scurtescu, et al.       Expires October 26, 2018               [Page 10]
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openid.net/pipermail/openid-specs-risc/attachments/20180424/35f7c3fa/attachment-0005.html>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: oauth-event-types-1_0.xml
Type: text/xml
Size: 20674 bytes
Desc: not available
URL: <http://lists.openid.net/pipermail/openid-specs-risc/attachments/20180424/35f7c3fa/attachment-0003.xml>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openid.net/pipermail/openid-specs-risc/attachments/20180424/35f7c3fa/attachment-0006.html>
-------------- next part --------------




                                                            M. Scurtescu
                                                                  Google
                                                              A. Backman
                                                                  Amazon
                                                                 P. Hunt
                                                                  Oracle
                                                              J. Bradley
                                                                  Yubico
                                                          April 24, 2018


                      OpenID RISC Event Types 1.0
                      openid-risc-event-types-1_0

Abstract

   This document defines the RISC Event Types.  Event Types are
   introduced and defined in Security Event Token (SET) [SET].

Table of Contents

   1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   1
     1.1.  Notational Conventions  . . . . . . . . . . . . . . . . .   2
   2.  Event Types . . . . . . . . . . . . . . . . . . . . . . . . .   2
     2.1.  Account Credential Change Required  . . . . . . . . . . .   2
     2.2.  Account Purged  . . . . . . . . . . . . . . . . . . . . .   3
     2.3.  Account Disabled  . . . . . . . . . . . . . . . . . . . .   3
     2.4.  Account Enabled . . . . . . . . . . . . . . . . . . . . .   4
     2.5.  Identifier Changed  . . . . . . . . . . . . . . . . . . .   4
     2.6.  Identifier Recycled . . . . . . . . . . . . . . . . . . .   5
     2.7.  Opt Out . . . . . . . . . . . . . . . . . . . . . . . . .   6
       2.7.1.  Opt In  . . . . . . . . . . . . . . . . . . . . . . .   7
       2.7.2.  Opt Out Initiated . . . . . . . . . . . . . . . . . .   7
       2.7.3.  Opt Out Cancelled . . . . . . . . . . . . . . . . . .   8
       2.7.4.  Opt Out Effective . . . . . . . . . . . . . . . . . .   8
     2.8.  Recovery Activated  . . . . . . . . . . . . . . . . . . .   8
     2.9.  Recovery Information Changed  . . . . . . . . . . . . . .   8
     2.10. Sessions Revoked  . . . . . . . . . . . . . . . . . . . .   9
   3.  Normative References  . . . . . . . . . . . . . . . . . . . .   9
   Authors' Addresses  . . . . . . . . . . . . . . . . . . . . . . .   9

1.  Introduction

   This specification is based on RISC Profile [RISC-PROFILE] and uses
   the subject identifiers defined there.






Scurtescu, et al.       Expires October 26, 2018                [Page 1]


                         openid-risc-event-types              April 2018


1.1.  Notational Conventions

   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
   "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
   "OPTIONAL" in this document are to be interpreted as described in BCP
   14 [RFC2119] [RFC8174] when, and only when, they appear in all
   capitals, as shown here.

2.  Event Types

   The base URI for RISC event types is:
   https://schemas.openid.net/secevent/risc/event-type/

2.1.  Account Credential Change Required

   Event Type URI:
   https://schemas.openid.net/secevent/risc/event-type/account-
   credential-change-required

   Account Credential Change Required signals that the account
   identified by the subject was required to change a credential.  For
   example the user was required to go through a password change.

   Attributes: none

   {
     "iss": "https://idp.example.com/",
     "jti": "756E69717565206964656E746966696572",
     "iat": 1508184845,
     "aud": "636C69656E745F6964",
     "events": {
       "https://schemas.openid.net/secevent/risc/event-type/\
       account-credential-change-required": {
         "subject": {
           "subject_type": "iss-sub",
           "iss": "https://idp.example.com/",
           "sub": "7375626A656374",
         }
       }
     }
   }

   _(the event type URI is wrapped, the backslash is the continuation
   character)_

           Figure 1: Example: Account Credential Change Required





Scurtescu, et al.       Expires October 26, 2018                [Page 2]


                         openid-risc-event-types              April 2018


2.2.  Account Purged

   Event Type URI:
   https://schemas.openid.net/secevent/risc/event-type/account-purged

   Account Purged signals that the account identified by the subject has
   been permanently deleted.

   Attributes: none

2.3.  Account Disabled

   Event Type URI:
   https://schemas.openid.net/secevent/risc/event-type/account-disabled

   Account Disabled signals that the account identified by the subject
   has been disabled.  The actual reason why the account was disabled
   might be specified with the nested "reason" attribute described
   below.  The account may be enabled (Section 2.4) in the future.

   Attributes:

   o  reason - optional, describes why was the account disabled.
      Possible values:

      *  hijacking

      *  bulk-account























Scurtescu, et al.       Expires October 26, 2018                [Page 3]


                         openid-risc-event-types              April 2018


   {
     "iss": "https://idp.example.com/",
     "jti": "756E69717565206964656E746966696572",
     "iat": 1508184845,
     "aud": "636C69656E745F6964",
     "events": {
       "https://schemas.openid.net/secevent/risc/event-type/\
       account-disabled": {
         "subject": {
           "subject_type": "iss-sub",
           "iss": "https://idp.example.com/",
           "sub": "7375626A656374",
         },
         "reason": "hijacking",
       }
     }
   }

   _(the event type URI is wrapped, the backslash is the continuation
   character)_

                    Figure 2: Example: Account Disabled

2.4.  Account Enabled

   Event Type URI:
   https://schemas.openid.net/secevent/risc/event-type/account-enabled

   Account Enabled signals that the account identified by the subject
   has been enabled.

   Attributes: none

2.5.  Identifier Changed

   Event Type URI:
   https://schemas.openid.net/secevent/risc/event-type/identifier-
   changed

   Identifier Changed signals that the identifier specified in the
   subject has changed.  The subject type MUST be either "email" or
   "phone" and it MUST specify the old value.

   This event SHOULD be issued only by the provider that is
   authoritative over the identifier.  For example, if the person that
   owns "john.doe at example.com" goes through a name change and wants the
   new "john.row at example.com" email then *only* the email provider




Scurtescu, et al.       Expires October 26, 2018                [Page 4]


                         openid-risc-event-types              April 2018


   "example.com" SHOULD issue an Identifier Changed event as shown in
   the example below.

   If an identifier used as a username or recovery option is changed, at
   a provider that is not authoritative over that identifier, then
   Recovery Information Changed (Section 2.9) SHOULD be used instead.

   Attributes:

   o  new-value - optional, the new value of the identifier.

   {
     "iss": "https://idp.example.com/",
     "jti": "756E69717565206964656E746966696572",
     "iat": 1508184845,
     "aud": "636C69656E745F6964",
     "events": {
       "https://schemas.openid.net/secevent/risc/event-type/\
       identifier-changed": {
         "subject": {
           "subject_type": "email",
           "email": "john.doe at example.com",
         },
         "new-value": "john.roe at example.com",
       }
     }
   }

   The "foo at example.com" email changed to "bar at example.com".  _(the
   event type URI is wrapped, the backslash is the continuation
   character)_

                   Figure 3: Example: Identifier Changed

2.6.  Identifier Recycled

   Event Type URI:
   https://schemas.openid.net/secevent/risc/event-type/identifier-
   recycled

   Identifier Recycled signals that the identifier specified in the
   subject was recycled and now it belongs to a new user.  The subject
   type MUST be either "email" or "phone".

   Attributes: none






Scurtescu, et al.       Expires October 26, 2018                [Page 5]


                         openid-risc-event-types              April 2018


   {
     "iss": "https://idp.example.com/",
     "jti": "756E69717565206964656E746966696572",
     "iat": 1508184845,
     "aud": "636C69656E745F6964",
     "events": {
       "https://schemas.openid.net/secevent/risc/event-type/\
       identifier-recycled": {
         "subject": {
           "subject_type": "email",
           "email": "foo at example.com",
         }
       }
     }
   }

   The 'foo at example.com' email address was recycled.  _(the event type
   URI is wrapped, the backslash is the continuation character)_

                  Figure 4: Example: Identifier Recycled

2.7.  Opt Out

   Users SHOULD be allowed to opt-in and out of RISC events being sent
   for their accounts.  With regards to opt-out an account can be in one
   of these three states:

   1.  opt-in - the account is participating in RISC event exchange.

   2.  opt-out-initiated - the user requested to be excluded from RISC
       event exchanges, but for practical security reasons for a period
       of time RISC events are still exchanged.  The main reason for
       this state is to prevent a hijacker from immediately opting out
       of RISC.

   3.  opt-out - the account is NOT participating in RISC event
       exchange.














Scurtescu, et al.       Expires October 26, 2018                [Page 6]


                         openid-risc-event-types              April 2018


   State changes trigger Opt-Out Events as represented bellow:

   +--------+  opt-out-initiated  +-------------------+
   |        +--------------------->                   |
   | opt-in |                     | opt-out-initiated |
   |        |  pt-out-cancelled   |                   |
   |        <---------------------+                   |
   +---^----+                     +----------+--------+
       |                                     |
       | opt-in                              | opt-out-effective
       |                                     |
       |                          +----------V--------+
       |                          |                   |
       +--------------------------| opt-out           |
                                  |                   |
                                  +-------------------+

                Figure 5: Opt-Out States and Opt-Out Events

   Both Transmitters and Receivers SHOULD manage Opt-Out state for
   users.  Transmitters should send the events defined in this section
   when the Opt-Out state changes.

2.7.1.  Opt In

   Event Type URI:
   https://schemas.openid.net/secevent/risc/event-type/opt-in

   Opt In signals that the account identified by the subject opted into
   RISC event exchanges.  The account is in the "opt-in" state.

   Attributes: none

2.7.2.  Opt Out Initiated

   Event Type URI:
   https://schemas.openid.net/secevent/risc/event-type/opt-out-initiated

   Opt Out Initiated signals that the account identified by the subject
   initiated to opt out from RISC event exchanges.  The account is in
   the "opt-out-initiated" state.

   Attributes: none








Scurtescu, et al.       Expires October 26, 2018                [Page 7]


                         openid-risc-event-types              April 2018


2.7.3.  Opt Out Cancelled

   Event Type URI:
   https://schemas.openid.net/secevent/risc/event-type/opt-out-cancelled

   Opt Out Cancelled signals that the account identified by the subject
   cancelled the opt out from RISC event exchanges.  The account is in
   the "opt-in" state.

   Attributes: none

2.7.4.  Opt Out Effective

   Event Type URI:
   https://schemas.openid.net/secevent/risc/event-type/opt-out-effective

   Opt Out Effective signals that the account identified by the subject
   was effectively opted out from RISC event exchanges.  The account is
   in the "opt-out" state.

   Attributes: none

2.8.  Recovery Activated

   Event Type URI:
   https://schemas.openid.net/secevent/risc/event-type/recovery-
   activated

   Recovery Activated signals that the account identified by the subject
   activated a recovery flow.

   Attributes: none

2.9.  Recovery Information Changed

   Event Type URI:
   https://schemas.openid.net/secevent/risc/event-type/recovery-
   information-changed

   Recovery Information Changed signals that the account identified by
   the subject has changed some of its recovery information.  For
   example a recovery email address was added or removed.

   Attributes: none







Scurtescu, et al.       Expires October 26, 2018                [Page 8]


                         openid-risc-event-types              April 2018


2.10.  Sessions Revoked

   Event Type URI:
   https://schemas.openid.net/secevent/risc/event-type/sessions-revoked

   Sessions Revoked signals that all the sessions for the account
   identified by the subject have been revoked.

   Attributes: none

3.  Normative References

   [JSON]     Bray, T., Ed., "The JavaScript Object Notation (JSON) Data
              Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March
              2014, <https://www.rfc-editor.org/info/rfc7159>.

   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
              Requirement Levels", BCP 14, RFC 2119,
              DOI 10.17487/RFC2119, March 1997, <https://www.rfc-
              editor.org/info/rfc2119>.

   [RFC8174]  Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
              2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
              May 2017, <https://www.rfc-editor.org/info/rfc8174>.

   [RISC-PROFILE]
              Scurtescu, M., Backman, A., and J. Bradley, "OpenID RISC
              Profile of IETF Security Events 1.0", April 2018,
              <http://openid.net/specs/openid-risc-profile-1_0.html>.

   [SET]      Hunt, P., Ed., Jones, M., Denniss, W., and M. Ansari,
              "Security Event Token (SET)", April 2018,
              <https://tools.ietf.org/html/draft-ietf-secevent-token-
              09>.

Authors' Addresses

   Marius Scurtescu
   Google

   Email: mscurtescu at google.com


   Annabelle Backman
   Amazon

   Email: richanna at amazon.com




Scurtescu, et al.       Expires October 26, 2018                [Page 9]


                         openid-risc-event-types              April 2018


   Phil Hunt
   Oracle Corporation

   Email: phil.hunt at yahoo.com


   John Bradley
   Yubico

   Email: secevemt at ve7jtb.com









































Scurtescu, et al.       Expires October 26, 2018               [Page 10]
-------------- next part --------------
A non-text attachment was scrubbed...
Name: openid-risc-event-types-1_0.xml
Type: text/xml
Size: 19603 bytes
Desc: not available
URL: <http://lists.openid.net/pipermail/openid-specs-risc/attachments/20180424/35f7c3fa/attachment-0004.xml>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openid.net/pipermail/openid-specs-risc/attachments/20180424/35f7c3fa/attachment-0007.html>
-------------- next part --------------




                                                            M. Scurtescu
                                                                  Google
                                                              A. Backman
                                                                  Amazon
                                                              J. Bradley
                                                                  Yubico
                                                          April 24, 2018


            OpenID RISC Profile of IETF Security Events 1.0
                        openid-risc-profile-1_0

Abstract

   This spec is a general profile for IETF Security Events [1] and it
   defines:

   o  Subject Identifiers

   o  a configuration information discovery method for Transmitters

   o  a Management API for Event Streams

   This spec also directly profiles several IETF Security Events drafts:

   o  Security Event Token (SET) [SET]

   o  Push-Based SET Token Delivery Using HTTP [DELIVERYPUSH]

   o  Poll-Based SET Token Delivery Using HTTP [DELIVERYPOLL]

Table of Contents

   1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   3
     1.1.  Notational Conventions  . . . . . . . . . . . . . . . . .   3
   2.  Subject Identifiers . . . . . . . . . . . . . . . . . . . . .   3
     2.1.  Subject Identifier Types  . . . . . . . . . . . . . . . .   4
       2.1.1.  Email Subject Identifier Type . . . . . . . . . . . .   4
       2.1.2.  Phone Number Subject Identifier Type  . . . . . . . .   5
       2.1.3.  Issuer and Subject Subject Identifier Type  . . . . .   5
       2.1.4.  ID Token Claims Subject Identifier Type . . . . . . .   5
   3.  Transmitter Configuration Discovery . . . . . . . . . . . . .   5
     3.1.  Transmitter Configuration Metadata  . . . . . . . . . . .   6
     3.2.  Obtaining Transmitter Configuration Information . . . . .   6
       3.2.1.  Transmitter Configuration Request . . . . . . . . . .   7
       3.2.2.  Transmitter Configuration Response  . . . . . . . . .   7
       3.2.3.  Transmitter Configuration Validation  . . . . . . . .   8
   4.  Management API for SET Event Streams  . . . . . . . . . . . .   8



Scurtescu, et al.       Expires October 26, 2018                [Page 1]


                           openid-risc-profile                April 2018


     4.1.  Event Stream Management . . . . . . . . . . . . . . . . .   9
       4.1.1.  Stream Status . . . . . . . . . . . . . . . . . . . .  10
         4.1.1.1.  Reading a Stream's Status . . . . . . . . . . . .  10
         4.1.1.2.  Updating a Stream's Status  . . . . . . . . . . .  11
       4.1.2.  Stream Configuration  . . . . . . . . . . . . . . . .  12
         4.1.2.1.  Reading a Stream's Configuration  . . . . . . . .  13
         4.1.2.2.  Updating a Stream's Configuration . . . . . . . .  15
         4.1.2.3.  Removing a Stream Configuration . . . . . . . . .  18
       4.1.3.  Subjects  . . . . . . . . . . . . . . . . . . . . . .  19
         4.1.3.1.  Adding a Subject to a Stream  . . . . . . . . . .  19
         4.1.3.2.  Removing a Subject  . . . . . . . . . . . . . . .  21
       4.1.4.  Verification  . . . . . . . . . . . . . . . . . . . .  22
         4.1.4.1.  Verification Event  . . . . . . . . . . . . . . .  22
         4.1.4.2.  Triggering a Verification Event.  . . . . . . . .  23
     4.2.  Authorization . . . . . . . . . . . . . . . . . . . . . .  25
     4.3.  Security Considerations . . . . . . . . . . . . . . . . .  25
       4.3.1.  Subject Probing . . . . . . . . . . . . . . . . . . .  25
       4.3.2.  Information Harvesting  . . . . . . . . . . . . . . .  26
       4.3.3.  Malicious Subject Removal . . . . . . . . . . . . . .  26
   5.  Profiles  . . . . . . . . . . . . . . . . . . . . . . . . . .  26
     5.1.  Security Event Token Profle . . . . . . . . . . . . . . .  27
       5.1.1.  Signature Key Resolution  . . . . . . . . . . . . . .  27
       5.1.2.  RISC Event Subject  . . . . . . . . . . . . . . . . .  27
       5.1.3.  Explicit Typing of SETs . . . . . . . . . . . . . . .  27
       5.1.4.  The "exp" Claim . . . . . . . . . . . . . . . . . . .  28
       5.1.5.  The "aud" Claim . . . . . . . . . . . . . . . . . . .  28
       5.1.6.  The "events" claim  . . . . . . . . . . . . . . . . .  29
       5.1.7.  Security Considerations . . . . . . . . . . . . . . .  29
         5.1.7.1.  Distingushing SETs from other Kinds of JWTs . . .  29
     5.2.  SET Token Delivery Using HTTP Profile . . . . . . . . . .  29
       5.2.1.  Stream Configuration Metadata . . . . . . . . . . . .  29
         5.2.1.1.  Push Delivery using HTTP  . . . . . . . . . . . .  30
         5.2.1.2.  Polling Delivery using HTTP . . . . . . . . . . .  30
   6.  IANA Considerations . . . . . . . . . . . . . . . . . . . . .  30
     6.1.  Security Event Subject Identifier Types Registry  . . . .  30
       6.1.1.  Registration Template . . . . . . . . . . . . . . . .  30
       6.1.2.  Initial Registry Contents . . . . . . . . . . . . . .  31
       6.1.3.  Guidance for Expert Reviewers . . . . . . . . . . . .  31
     6.2.  Well-Known URI Registry . . . . . . . . . . . . . . . . .  32
       6.2.1.  Registry Contents . . . . . . . . . . . . . . . . . .  32
   7.  Privacy Considerations  . . . . . . . . . . . . . . . . . . .  32
     7.1.  Subject Information Leakage . . . . . . . . . . . . . . .  32
   8.  References  . . . . . . . . . . . . . . . . . . . . . . . . .  33
     8.1.  Normative References  . . . . . . . . . . . . . . . . . .  33
     8.2.  URIs  . . . . . . . . . . . . . . . . . . . . . . . . . .  35
   Appendix A.  Acknowledgements . . . . . . . . . . . . . . . . . .  35
   Authors' Addresses  . . . . . . . . . . . . . . . . . . . . . . .  35




Scurtescu, et al.       Expires October 26, 2018                [Page 2]


                           openid-risc-profile                April 2018


1.  Introduction

1.1.  Notational Conventions

   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
   "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
   "OPTIONAL" in this document are to be interpreted as described in BCP
   14 [RFC2119] [RFC8174] when, and only when, they appear in all
   capitals, as shown here.

2.  Subject Identifiers

   The RISC profile defines a structure called a Subject Identifier: a
   JSON [RFC7159] object containing a set of claims that collectively
   uniquely identify a subject, according to a simple schema called a
   Subject Identifier Type.  Every Subject Identifier MUST contain a
   "subject_type" claim, whose value MUST be a name that uniquely
   identifies the Subject Identifier Type of the Subject Identifier.
   Any remaining claims within the Subject Identifier MUST be
   interpreted according to the definition of the Subject Identifier
   Type.  A Subject Identifier MUST conform to the Subject Identifier
   Type identified by its "subject_type" claim, and MUST NOT contain any
   claims not defined by its Subject Identifier Type.

   {
     "iss": "https://idp.example.com/",
     "jti": "756E69717565206964656E746966696572",
     "iat": 1520364019,
     "aud": "636C69656E745F6964",
     "events": {
       "https://schemas.openid.net/secevent/risc/event-type/account-\
   enabled": {
         "subject": {
           "subject_type": "email",
           "email": "foo at example.com"
         }
       }
     }
   }

   A Subject Identifier that identifies a subject by email address.

   Figure 1: Example: SET Containing a RISC Event with an Email Subject
                                Identifier







Scurtescu, et al.       Expires October 26, 2018                [Page 3]


                           openid-risc-profile                April 2018


   {
     "iss": "https://idp.example.com/",
     "jti": "756E69717565206964656E746966696572",
     "iat": 1520364019,
     "aud": "636C69656E745F6964",
     "events": {
       "https://schemas.openid.net/secevent/risc/event-type/account-\
   enabled": {
         "subject": {
           "subject_type": "iss_sub",
           "iss": "https://issuer.example.com/",
           "sub": "abc1234"
         }
       }
     }
   }

   A Subject Identifier that identifies a subject by an identifier
   provided by an issuer.

     Figure 2: Example: SET Containing a RISC Event with an Issuer and
                        Subject Subject Identifier

2.1.  Subject Identifier Types

   A Subject Identifier Type is a light-weight schema that describes a
   set of claims that uniquely identifies a subject.  Every Subject
   Identifier Type MUST have a unique name registered in the IANA
   "Security Event Subject Identifier Types" registry established by
   Section 6.1.  A Subject Identifier Type MAY contain more claims than
   are strictly necessary to uniquely identify a subject, however a
   Subject Identifier MUST contain all of the claims required by its
   type (See Privacy Considerations).

   The following Subject Identifier Types are registered in the IANA
   "Security Event Subject Identifier Types" registry established by
   Section 6.1.

2.1.1.  Email Subject Identifier Type

   The Email Subject Identifier Type describes a subject by email
   address.  Subject Identifiers of this type MUST contain an "email"
   claim whose value is a string containing the email address of the
   subject.  The "email" claim MUST NOT be null or empty.  The Email
   Subject Identifier Type is identified by the name "email".






Scurtescu, et al.       Expires October 26, 2018                [Page 4]


                           openid-risc-profile                April 2018


2.1.2.  Phone Number Subject Identifier Type

   The Phone Number Subject Identifier Type describes a subject by
   telephone number.  Subject Identifiers of this type MUST contain a
   "phone" claim whose value is a string containing the full telephone
   number of the subject, including international dialing prefix,
   formatted according to E.164 [E164].  The "phone" claim MUST NOT be
   null or empty.  The Phone Number Subject Identifier Type is
   identified by the name "phone".

2.1.3.  Issuer and Subject Subject Identifier Type

   The Issuer and Subject Subject Identifier Type describes a subject by
   an issuer and a subject.  Subject Identifiers of this type MUST
   contain an "iss" claim whose value identifies the issuer, and a "sub"
   claim whose value identifies the subject with respect to the issuer.
   These claims MUST follow the formats of the "iss" claim and "sub"
   claim defined by [RFC7519], respectively.  Both the "iss" claim and
   the "sub" claim MUST NOT be null or empty.  The Issuer and Subject
   Subject Identifier Type is identified by the name "iss_sub".

2.1.4.  ID Token Claims Subject Identifier Type

   The ID Token Claims Subject Identifier Type describes a subject by a
   subset of the claims from an ID token.  Subject Identifiers of this
   type MUST contain at least one of the following claims:

   email
      An "email" claim, as defined in [IDTOKEN].

   phone_number
      An "phone_number" claim, as defined in [IDTOKEN].

   sub
      A "sub" claim, as defined in [RFC7519].

   If the Subject Identifier contains a "sub" claim, it MUST also
   contain an "iss" claim, as defined in [RFC7519].  The ID Token Claims
   Subject Identifier Type is identified by the name "id_token_claims".

3.  Transmitter Configuration Discovery

   This section defines a mechanism for Receivers to obtain Transmitter
   configuration information.







Scurtescu, et al.       Expires October 26, 2018                [Page 5]


                           openid-risc-profile                April 2018


3.1.  Transmitter Configuration Metadata

   Transmitters have metadata describing their configuration:

   issuer  REQUIRED.  URL using the https scheme with no query or
      fragment component that the Transmitter asserts as its Issuer
      Identifier.  This MUST be identical to the iss Claim value in
      Security Event Tokens issued from this Transmitter.

   jwks_uri  REQUIRED.  URL of the Transmitter's JSON Web Key Set
      [RFC7517] document.  This contains the signing key(s) the Receiver
      uses to validate signatures from the Transmitter.

   delivery_methods_supported  RECOMMENDED.  List of supported delivery
      method URIs.

   configuration_endpoint  OPTIONAL.  The URL of the Configuration
      Endpoint.

   status_endpoint  OPTIONAL.  The URL of the Status Endpoint.

   add_subject_endpoint  OPTIONAL.  The URL of the Add Subject Endpoint.

   remove_subject_endpoint  OPTIONAL.  The URL of the Remove Subject
      Endpoint.

   verification_endpoint  OPTIONAL.  The URL of the Verification
      Endpoint.

   TODO: consider adding a IANA Registry for metadata, similar to
   Section 7.1.1 of [OAUTH-DISCOVERY].  This would allow other specs to
   add to the metadata.

3.2.  Obtaining Transmitter Configuration Information

   Using the Issuer as documented by the Transmitter, the Transmitter
   Configuration Information can be retrieved.

   Transmitters supporting Discovery MUST make a JSON document available
   at the path formed by inserting the string "/.well-known/risc-
   configuration" into the Issuer between the host component and the
   path component, if any.  The syntax and semantics of ".well-known"
   are defined in [RFC5785].  "risc-configuration" MUST point to a JSON
   document compliant with this specification and MUST be returned using
   the "application/json" content type.






Scurtescu, et al.       Expires October 26, 2018                [Page 6]


                           openid-risc-profile                April 2018


3.2.1.  Transmitter Configuration Request

   A Transmitter Configuration Document MUST be queried using an HTTP
   "GET" request at the previously specified path.

   The Receiver would make the following request to the Issuer
   "https://tr.example.com" to obtain its Configuration information,
   since the Issuer contains no path component:

   GET /.well-known/risc-configuration HTTP/1.1
   Host: tr.example.com

    Figure 3: Example: Transmitter Configuration Request (without path)

   If the Issuer value contains a path component, any terminating "/"
   MUST be removed before inserting "/.well-known/risc-configuration"
   between the host component and the path component.  The Receiver
   would make the following request to the Issuer
   "https://tr.example.com/issuer1" to obtain its Configuration
   information, since the Issuer contains a path component:

   GET /.well-known/risc-configuration/issuer1 HTTP/1.1
   Host: tr.example.com

     Figure 4: Example: Transmitter Configuration Request (with path)

   Using path components enables supporting multiple issuers per host.
   This is required in some multi-tenant hosting configurations.  This
   use of ".well-known" is for supporting multiple issuers per host;
   unlike its use in [RFC5785], it does not provide general information
   about the host.

3.2.2.  Transmitter Configuration Response

   The response is a set of Claims about the Transmitter's
   configuration, including all necessary endpoints and public key
   location information.  A successful response MUST use the 200 OK HTTP
   status code and return a JSON object using the "application/json"
   content type that contains a set of Claims as its members that are a
   subset of the Metadata values defined in Section 3.1.  Other Claims
   MAY also be returned.

   Claims that return multiple values are represented as JSON arrays.
   Claims with zero elements MUST be omitted from the response.

   An error response uses the applicable HTTP status code value.





Scurtescu, et al.       Expires October 26, 2018                [Page 7]


                           openid-risc-profile                April 2018


   HTTP/1.1 200 OK
   Content-Type: application/json

   {
     "issuer":
       "https://tr.example.com",
     "jwks_uri":
       "https://tr.example.com/jwks.json",
     "delivery_methods_supported": [
       "https://schemas.openid.net/secevent/risc/delivery-method/push",
       "https://schemas.openid.net/secevent/risc/delivery-method/poll"],
     "configuration_endpoint":
       "https://tr.example.com/risc/mgmt/stream",
     "status_endpoint":
       "https://tr.example.com/risc/mgmt/status",
     "add_subject_endpoint":
       "https://tr.example.com/risc/mgmt/subject:add",
     "remove_subject_endpoint":
       "https://tr.example.com/risc/mgmt/subject:remove",
     "verification_endpoint":
       "https://tr.example.com/risc/mgmt/verification"
   }

           Figure 5: Example: Transmitter Configuration Response

3.2.3.  Transmitter Configuration Validation

   If any of the validation procedures defined in this specification
   fail, any operations requiring the information that failed to
   correctly validate MUST be aborted and the information that failed to
   validate MUST NOT be used.

   The "issuer" value returned MUST be identical to the Issuer URL that
   was directly used to retrieve the configuration information.  This
   MUST also be identical to the "iss" Claim value in Security Event
   Tokens issued from this Transmitter.

4.  Management API for SET Event Streams

   This section defines an HTTP API to be implemented by Event
   Transmitters and that can be used by Event Receivers to query and
   update the Event Stream configuration and status, to add and remove
   subjects and to trigger verification.

   This section is based on Management API for SET Event Streams
   [MGMTAPI].





Scurtescu, et al.       Expires October 26, 2018                [Page 8]


                           openid-risc-profile                April 2018


   +------------+                +------------+
   |            | Stream Config  |            |
   | Event      <----------------+ Event      |
   | Stream     |                | Receiver   |
   | Management | Stream Status  |            |
   | API        <----------------+            |
   |            |                |            |
   |            | Add Subject    |            |
   |            <----------------+            |
   |            |                |            |
   |            | Remove Subject |            |
   |            <----------------+            |
   |            |                |            |
   |            | Verification   |            |
   |            <----------------+            |
   |            |                |            |
   +------------+                +------------+

                   Figure 6: Event Stream Management API

   It is OPTIONAL for Transmitters to implement a Management API, but it
   is RECOMMENDED that they implement it, especially the endpoints for
   querying the Stream Status and for triggering Verification.

4.1.  Event Stream Management

   Event Receivers manage how they receive events, and the subjects
   about which they want to receive events over an Event Stream by
   making HTTP requests to endpoints in the Event Stream Management API.

   The Event Stream Management API is implemented by the Event
   Transmitter and consists of the following endpoints:

   Configuration Endpoint
      An endpoint used to read the Event Stream's current configuration.

   Status Endpoint
      An endpoint used to read the Event Stream's current status.

   Add Subject Endpoint
      An endpoint used to add subjects to an Event Stream.

   Remove Subject Endpoint
      An endpoint used to remove subjects from an Event Stream.

   Verification Endpoint
      An endpoint used to request the Event Transmitter transmit a
      Verification Event over the Event Stream.



Scurtescu, et al.       Expires October 26, 2018                [Page 9]


                           openid-risc-profile                April 2018


   An Event Transmitter MAY use the same URLs as endpoints for multiple
   streams, provided that the Event Transmitter has some mechanism
   through which they can identify the applicable Event Stream for any
   given request, e.g. from authentication credentials.  The definition
   of such mechanisms is outside the scope of this specification.

4.1.1.  Stream Status

4.1.1.1.  Reading a Stream's Status

   An Event Receiver checks the current status of an event stream by
   making an HTTP GET request to the stream's Status Endpoint.  On
   receiving a valid request the Event Transmitter responds with a 200
   OK response containing a JSON [RFC7159] object with a single
   attribute "status", whose string value MUST have one of the following
   values:

   enabled
      The transmitter will transmit events over the stream, according to
      the stream's configured delivery method.

   paused
      The transmitter will not transmit events over the stream.  The
      transmitter will hold any events it would have transmitted while
      paused, and will transmit them when the stream's status becomes
      "enabled".

   disabled
      The transmitter will not transmit events over the stream, and will
      not hold any events for later transmission.

   The following is a non-normative example request to check an event
   stream's status:

   GET /set/status HTTP/1.1
   Host: transmitter.example.com
   Authorization: Bearer eyJ0b2tlbiI6ImV4YW1wbGUifQo=

              Figure 7: Example: Check Stream Status Request

   The following is a non-normative example response:










Scurtescu, et al.       Expires October 26, 2018               [Page 10]


                           openid-risc-profile                April 2018


   HTTP/1.1 200 OK
   Content-Type: application/json; charset=UTF-8
   Cache-Control: no-store
   Pragma: no-cache

   {
     "status": "enabled"
   }

              Figure 8: Example: Check Stream Status Response

   Errors are signaled with HTTP status codes as follows:

   +------+------------------------------------------------------------+
   | Code | Description                                                |
   +------+------------------------------------------------------------+
   | 401  | if authorization failed or it is missing                   |
   |      |                                                            |
   | 403  | if the Event Receiver is not allowed to read the stream    |
   |      | status                                                     |
   |      |                                                            |
   | 404  | if there is no Event Stream configured for this Event      |
   |      | Receiver                                                   |
   +------+------------------------------------------------------------+

                    Table 1: Read Stream Status Errors

4.1.1.2.  Updating a Stream's Status

   An Event Receiver updates the current status of a stream by making an
   HTTP POST request to the Status Endpoint.  The POST body contains a
   JSON [RFC7159] representation of the updated status.  On receiving a
   valid request the Event Transmitter responds with a "200 OK" response
   containing a JSON [RFC7159] representation of the updated stream
   status in the body.

   The following is a non-normative example request to update an Event
   Stream's status:

   POST /set/status HTTP/1.1
   Host: transmitter.example.com
   Authorization: Bearer eyJ0b2tlbiI6ImV4YW1wbGUifQo=

   {
     "status": "paused",
   }

              Figure 9: Example: Update Stream Status Request



Scurtescu, et al.       Expires October 26, 2018               [Page 11]


                           openid-risc-profile                April 2018


   The following is a non-normative example response:

   HTTP/1.1 200 OK
   Content-Type: application/json; charset=UTF-8
   Cache-Control: no-store
   Pragma: no-cache

   {
     "status": "paused"
   }

             Figure 10: Example: Update Stream Status Response

   Errors are signaled with HTTP status codes as follows:

   +------+------------------------------------------------------------+
   | Code | Description                                                |
   +------+------------------------------------------------------------+
   | 400  | if the request body cannot be parsed or if the request is  |
   |      | otherwise invalid                                          |
   |      |                                                            |
   | 401  | if authorization failed or it is missing                   |
   |      |                                                            |
   | 403  | if the Event Receiver is not allowed to update the stream  |
   |      | status                                                     |
   |      |                                                            |
   | 404  | if there is no Event Stream configured for this Event      |
   |      | Receiver                                                   |
   +------+------------------------------------------------------------+

                   Table 2: Update Stream Status Errors

4.1.2.  Stream Configuration

   An Event Stream's configuration is represented as a JSON [RFC7159]
   object with the following properties:

   iss
      *Read-Only*, A URL using the https scheme with no query or
      fragment component that the Transmitter asserts as its Issuer
      Identifier.  This MUST be identical to the "iss" Claim value in
      Security Event Tokens issued from this Transmitter.

   aud
      *Read-Only*, A string or an array of strings containing an
      audience claim as defined in JSON Web Token (JWT) [RFC7519] that
      identifies the Event Receiver(s) for the Event Stream.  This
      property cannot be updated.  If multiple Receivers are specified



Scurtescu, et al.       Expires October 26, 2018               [Page 12]


                           openid-risc-profile                April 2018


      then the Transmitter SHOULD know that these Receivers are the same
      entity.

   events_supported
      *Read-Only*, An array of URIs identifying the set of events
      supported by the Transmitter for this Receiver.  If omitted, Event
      Transmitters SHOULD make this set available to the Event Receiver
      via some other means (e.g. publishing it in online documentation).

   events_requested
      *Read-Write*, An array of URIs identifying the set of events that
      the Receiver requested.  A Receiver should request only the events
      that it understands and it can act on.  This is configurabel by
      the Receuver.

   events_delivered
      *Read-Only*, An array of URIs which is the intersection of
      "events_supported" and "events_requested".  These events MAY be
      delivered over the Event Stream.

   delivery
      *Read-Write*, A JSON object containing a set of name/value pairs
      specifying configuration parameters for the SET delivery method.
      The actual delivery method is identified by the special key
      "method" with the value being a URI as defined in Section 5.2.1.

   min_verification_interval
      *Read-Only*, An integer indicating the minimum amount of time in
      seconds that must pass in between verification requests.  If an
      Event Receiver submits verification requests more frequently than
      this, the Event Transmitter MAY respond with a 429 status code.
      An Event Transmitter SHOULD NOT respond with a 429 status code if
      an Event Receiver is not exceeding this frequency.

   subject_type
      *Read-Write*, The Subject Identifier Type that the Receiver wants
      for the events.  If not set then the Transmitter might decide to
      use a type that discloses more information than necessary.

   TODO: consider adding a IANA Registry for stream configuration
   metadata, similar to Section 7.1.1 of [OAUTH-DISCOVERY].  This would
   allow other specs to add to the stream configuration.

4.1.2.1.  Reading a Stream's Configuration

   An Event Receiver gets the current configuration of a stream by
   making an HTTP GET request to the Configuration Endpoint.  On
   receiving a valid request the Event Transmitter responds with a "200



Scurtescu, et al.       Expires October 26, 2018               [Page 13]


                           openid-risc-profile                April 2018


   OK" response containing a JSON [RFC7159] representation of the
   stream's configuration in the body.

   The following is a non-normative example request to read an Event
   Stream's configuration:

   GET /set/stream HTTP/1.1
   Host: transmitter.example.com
   Authorization: Bearer eyJ0b2tlbiI6ImV4YW1wbGUifQo=

           Figure 11: Example: Read Stream Configuration Request

   The following is a non-normative example response:

  HTTP/1.1 200 OK
  Content-Type: application/json; charset=UTF-8
  Cache-Control: no-store
  Pragma: no-cache

  {
    "iss": "https://tr.example.com",
    "aud": [
        "http://receiver.example.com/web",
        "http://receiver.example.com/mobile"
      ],
    "delivery": {
      "delivery_method":
        "https://schemas.openid.net/secevent/risc/delivery-method/push",
      "url": "https://receiver.example.com/events"
    },
    "events_supported": [
      "urn:example:secevent:events:type_1",
      "urn:example:secevent:events:type_2",
      "urn:example:secevent:events:type_3"
    ],
    "events_requested": [
      "urn:example:secevent:events:type_2",
      "urn:example:secevent:events:type_3",
      "urn:example:secevent:events:type_4"
    ],
    "events_delivered": [
      "urn:example:secevent:events:type_2",
      "urn:example:secevent:events:type_3"
    ]
  }

          Figure 12: Example: Read Stream Configuration Response




Scurtescu, et al.       Expires October 26, 2018               [Page 14]


                           openid-risc-profile                April 2018


   Errors are signaled with HTTP status codes as follows:

   +------+------------------------------------------------------------+
   | Code | Description                                                |
   +------+------------------------------------------------------------+
   | 401  | if authorization failed or it is missing                   |
   |      |                                                            |
   | 403  | if the Event Receiver is not allowed to read the stream    |
   |      | configuration                                              |
   |      |                                                            |
   | 404  | if there is no Event Stream configured for this Event      |
   |      | Receiver                                                   |
   +------+------------------------------------------------------------+

                 Table 3: Read Stream Configuration Errors

4.1.2.2.  Updating a Stream's Configuration

   An Event Receiver updates the current configuration of a stream by
   making an HTTP POST request to the Configuration Endpoint.  The POST
   body contains a JSON [RFC7159] representation of the updated
   configuration.  On receiving a valid request the Event Transmitter
   responds with a "200 OK" response containing a JSON [RFC7159]
   representation of the updated stream configuration in the body.

   The full set of editable properties must be present in the POST body,
   not only the ones that are specifically intended to be changed.
   Missing properties SHOULD be interpreted as requested to be deleted.
   Event Receivers should read the configuration first, modify the JSON
   [RFC7159] representation, then make an update request.

   Properties that cannot be updated MAY be present, but they MUST match
   the expected value.

   The following is a non-normative example request to update an Event
   Stream's configuration:















Scurtescu, et al.       Expires October 26, 2018               [Page 15]


                           openid-risc-profile                April 2018


  POST /set/stream HTTP/1.1
  Host: transmitter.example.com
  Authorization: Bearer eyJ0b2tlbiI6ImV4YW1wbGUifQo=

  {
    "iss": "https://tr.example.com",
    "aud": [
      "http://receiver.example.com/web",
      "http://receiver.example.com/mobile"
    ],
    "delivery": {
      "delivery_method":
        "https://schemas.openid.net/secevent/risc/delivery-method/push",
      "url": "https://receiver.example.com/events"
    },
    "events_requested": [
      "urn:example:secevent:events:type_2",
      "urn:example:secevent:events:type_3",
      "urn:example:secevent:events:type_4"
    ]
  }

          Figure 13: Example: Update Stream Configuration Request

   The following is a non-normative example response:


























Scurtescu, et al.       Expires October 26, 2018               [Page 16]


                           openid-risc-profile                April 2018


  HTTP/1.1 200 OK
  Content-Type: application/json; charset=UTF-8
  Cache-Control: no-store
  Pragma: no-cache

  {
    "iss": "https://tr.example.com",
    "aud": [
      "http://receiver.example.com/web",
      "http://receiver.example.com/mobile"
    ],
    "delivery": {
      "delivery_method":
        "https://schemas.openid.net/secevent/risc/delivery-method/push",
      "url": "https://receiver.example.com/events"
    },
    "events_supported": [
      "urn:example:secevent:events:type_1",
      "urn:example:secevent:events:type_2",
      "urn:example:secevent:events:type_3"
    ],
    "events_requested": [
      "urn:example:secevent:events:type_2",
      "urn:example:secevent:events:type_3",
      "urn:example:secevent:events:type_4"
    ],
    "events_delivered": [
      "urn:example:secevent:events:type_2",
      "urn:example:secevent:events:type_3"
    ]
  }

         Figure 14: Example: Update Stream Configuration Response

   Errors are signaled with HTTP status codes as follows:
















Scurtescu, et al.       Expires October 26, 2018               [Page 17]


                           openid-risc-profile                April 2018


   +------+------------------------------------------------------------+
   | Code | Description                                                |
   +------+------------------------------------------------------------+
   | 400  | if the request body cannot be parsed or if the request is  |
   |      | otherwise invalid                                          |
   |      |                                                            |
   | 401  | if authorization failed or it is missing                   |
   |      |                                                            |
   | 403  | if the Event Receiver is not allowed to update the stream  |
   |      | configuration                                              |
   |      |                                                            |
   | 404  | if there is no Event Stream configured for this Event      |
   |      | Receiver                                                   |
   +------+------------------------------------------------------------+

                Table 4: Update Stream Configuration Errors

4.1.2.3.  Removing a Stream Configuration

   An Event Receiver removes the configuration of a stream by making an
   HTTP DELETE request to the Configuration Endpoint.  On receiving a
   request the Event Transmitter responds with a "200 OK" response if
   the configuration was successfully removed.

   The following is a non-normative example request to remove an Event
   Stream's configuration:

   DELETE /set/stream HTTP/1.1
   Host: transmitter.example.com
   Authorization: Bearer eyJ0b2tlbiI6ImV4YW1wbGUifQo=

          Figure 15: Example: Remove Stream Configuration Request

   Errors are signaled with HTTP status codes as follows:

   +------+------------------------------------------------------------+
   | Code | Description                                                |
   +------+------------------------------------------------------------+
   | 401  | if authorization failed or it is missing                   |
   |      |                                                            |
   | 403  | if the Event Receiver is not allowed to update the stream  |
   |      | configuration                                              |
   +------+------------------------------------------------------------+

                Table 5: Update Stream Configuration Errors






Scurtescu, et al.       Expires October 26, 2018               [Page 18]


                           openid-risc-profile                April 2018


4.1.3.  Subjects

   An Event Receiver can indicate to an Event Transmitter whether or not
   the receiver wants to receive events about a particular subject by
   "adding" or "removing" that subject to the Event Stream,
   respectively.

4.1.3.1.  Adding a Subject to a Stream

   To add a subject to an Event Stream, the Event Receiver makes an HTTP
   POST request to the Add Subject Endpoint, containing in the body a
   JSON object the following claims:

   subject
      REQUIRED.  A Subject Identifier identifying the subject to be
      added.

   verified
      OPTIONAL.  A boolean value; when true, it indicates that the Event
      Receiver has verified the Subject Identifier.  When false, it
      indicates that the Event Receiver has not verified the Subject
      Identifier.  If omitted, Event Transmitters SHOULD NOT assume that
      verification has not occurred.

   On a successful response, the Event Transmitter responds with an
   empty "200 OK" response.  The Event Transmitter MAY choose to
   silently ignore the request, for example if the subject has
   previously indicated to the transmitter that they do not want events
   to be transmitted to the Event Receiver.  In this case, the
   transmitter MAY return an empty "200 OK" response or an appropriate
   error code.  See Security Considerations (Section 4.3).

   Errors are signaled with HTTP status codes as follows:


















Scurtescu, et al.       Expires October 26, 2018               [Page 19]


                           openid-risc-profile                April 2018


   +------+------------------------------------------------------------+
   | Code | Description                                                |
   +------+------------------------------------------------------------+
   | 400  | if the request body cannot be parsed or if the request is  |
   |      | otherwise invalid                                          |
   |      |                                                            |
   | 401  | if authorization failed or it is missing                   |
   |      |                                                            |
   | 403  | if the Event Receiver is not allowed to add this           |
   |      | particular subject, or not allowed to add in general       |
   |      |                                                            |
   | 404  | if the subject is not recognized by the Event Transmitter, |
   |      | the Event Transmitter may chose to stay silent in this     |
   |      | case and respond with "200"                                |
   |      |                                                            |
   | 429  | if the Event Receiver is sending too many requests in a    |
   |      | gvien amount of time                                       |
   +------+------------------------------------------------------------+

                        Table 6: Add Subject Errors

   The following is a non-normative example request to add a subject to
   a stream, where the subject is identified by an Email Subject
   Identifier.

   POST /set/subjects:add HTTP/1.1
   Host: transmitter.example.com
   Authorization: Bearer eyJ0b2tlbiI6ImV4YW1wbGUifQo=

   {
     "subject": {
       "subject_type": "email",
       "email": "example.user at example.com"
     },
     "verified": true
   }

                  Figure 16: Example: Add Subject Request

   The following is a non-normative example response to a successful
   request:

   HTTP/1.1 200 OK
   Server: transmitter.example.com
   Cache-Control: no-store
   Pragma: no-cache

                 Figure 17: Example: Add Subject Response



Scurtescu, et al.       Expires October 26, 2018               [Page 20]


                           openid-risc-profile                April 2018


4.1.3.2.  Removing a Subject

   To remove a subject from an Event Stream, the Event Receiver makes an
   HTTP POST request to the Remove Subject Endpoint, containing in the
   body a JSON object with the following claims:

   subject
      A Subject Identifier identifying the subject to be removed.
      REQUIRED.

   On a successful response, the Event Transmitter responds with a "204
   No Content" response.

   Errors are signaled with HTTP status codes as follows:

   +------+------------------------------------------------------------+
   | Code | Description                                                |
   +------+------------------------------------------------------------+
   | 400  | if the request body cannot be parsed or if the request is  |
   |      | otherwise invalid                                          |
   |      |                                                            |
   | 401  | if authorization failed or it is missing                   |
   |      |                                                            |
   | 403  | if the Event Receiver is not allowed to remove this        |
   |      | particular subject, or not allowed to remove in general    |
   |      |                                                            |
   | 404  | if the subject is not recognized by the Event Transmitter, |
   |      | the Event Transmitter may chose to stay silent in this     |
   |      | case and respond with "204"                                |
   |      |                                                            |
   | 429  | if the Event Receiver is sending too many requests in a    |
   |      | gvien amount of time                                       |
   +------+------------------------------------------------------------+

                      Table 7: Remove Subject Errors

   The following is a non-normative example request where the subject is
   identified by a Phone Number Subject Identifier:













Scurtescu, et al.       Expires October 26, 2018               [Page 21]


                           openid-risc-profile                April 2018


   POST /set/subjects:remove HTTP/1.1
   Host: transmitter.example.com
   Authorization: Bearer eyJ0b2tlbiI6ImV4YW1wbGUifQo=

   {
     "subject": {
       "subject_type": "phone",
       "phone_number": "+1 206 555 0123"
     }
   }

                Figure 18: Example: Remove Subject Request

   The following is a non-normative example response to a successful
   request:

   HTTP/1.1 204 No Content
   Server: transmitter.example.com
   Cache-Control: no-store
   Pragma: no-cache

                Figure 19: Example: Remove Subject Response

4.1.4.  Verification

   In some cases, the frequency of event transmission on an Event Stream
   will be very low, making it difficult for an Event Receiver to tell
   the difference between expected behavior and event transmission
   failure due to a misconfigured stream.  Event Receivers can request
   that a verification event be transmitted over the Event Stream,
   allowing the receiver to confirm that the stream is configured
   correctly upon successful receipt of the event.  The acknowledgment
   of a Verification Event also confirms to the Event Transmitter that
   end-to-end delivery is working, including signature verification and
   encryption.

   An Event Transmitter MAY send a Verification Event at any time, even
   if one was not requested by the Event Receiver.

4.1.4.1.  Verification Event

   The Verification Event is a standard SET with the following
   attributes:

   event type
      The Event Type URI is: "https://schemas.openid.net/secevent/risc/
      event-type/verification".




Scurtescu, et al.       Expires October 26, 2018               [Page 22]


                           openid-risc-profile                April 2018


   state
      OPTIONAL An opaque value provided by the Event Receiver when the
      event is triggered.  This is a nested attribute in the event
      payload.

   Upon receiving a Verification Event, the Event Receiver SHALL parse
   the SET and validate its claims.  In particular, the Event Receiver
   SHALL confirm that the value for "state" is as expected.  If the
   value of "state" does not match, an error response of "setData"
   SHOULD be returned (see Section 2.3 of [DELIVERYPUSH] or
   [DELIVERYPOLL]).

   In many cases, Event Transmitters MAY disable or suspend an Event
   Stream that fails to successfully verify based on the acknowledgement
   or lack of acknowledgement by the Event Receiver.

4.1.4.2.  Triggering a Verification Event.

   To request that a verification event be sent over an Event Stream,
   the Event Receiver makes an HTTP POST request to the Verification
   Endpoint, with a JSON [RFC7159] object containing the parameters of
   the verification request, if any.  On a successful request, the event
   transmitter responds with an empty "204 No Content" response.

   Verification requests have the following properties:

   state
      OPTIONAL.  An arbitrary string that the Event Transmitter MUST
      echo back to the Event Receiver in the verification event's
      payload.  Event Receivers MAY use the value of this parameter to
      correlate a verification event with a verification request.  If
      the verification event is initiated by the transmitter then this
      parameter MUST not be set.

   A successful response from a POST to the Verification Endpoint does
   not indicate that the verification event was transmitted
   successfully, only that the Event Transmitter has transmitted the
   event or will do so at some point in the future.  Event Transmitters
   MAY transmit the event via an asynchronous process, and SHOULD
   publish an SLA for verification event transmission times.  Event
   Receivers MUST NOT depend on the verification event being transmitted
   synchronously or in any particular order relative to the current
   queue of events.

   Errors are signaled with HTTP status codes as follows:






Scurtescu, et al.       Expires October 26, 2018               [Page 23]


                           openid-risc-profile                April 2018


   +------+------------------------------------------------------------+
   | Code | Description                                                |
   +------+------------------------------------------------------------+
   | 400  | if the request body cannot be parsed or if the request is  |
   |      | otherwise invalid                                          |
   |      |                                                            |
   | 401  | if authorization failed or it is missing                   |
   |      |                                                            |
   | 429  | if the Event Receiver is sending too many requests in a    |
   |      | gvien amount of time; see related                          |
   |      | "min_verification_interval" in Section 4.1.2               |
   +------+------------------------------------------------------------+

                       Table 8: Verification Errors

   The following is a non-normative example request to trigger a
   verification event:

   POST /set/verify HTTP/1.1
   Host: transmitter.example.com
   Authorization: Bearer eyJ0b2tlbiI6ImV4YW1wbGUifQo=
   Content-Type: application/json; charset=UTF-8

   {
     "state": "VGhpcyBpcyBhbiBleGFtcGxlIHN0YXRlIHZhbHVlLgo="
   }

             Figure 20: Example: Trigger Verification Request

   The following is a non-normative example response to a successful
   request:

   HTTP/1.1 204 No Content
   Server: transmitter.example.com
   Cache-Control: no-store
   Pragma: no-cache

             Figure 21: Example: Trigger Verification Response

   And the following is a non-normative example of a verification event
   sent to the Event Receiver as a result of the above request:










Scurtescu, et al.       Expires October 26, 2018               [Page 24]


                           openid-risc-profile                April 2018


{
  "jti": "123456",
  "iss": "https://transmitter.example.com",
  "aud": "receiver.example.com",
  "iat": "1493856000",
  "events": [
    "https://schemas.openid.net/secevent/risc/event-type/verification":{
      "state": "VGhpcyBpcyBhbiBleGFtcGxlIHN0YXRlIHZhbHVlLgo="
    }
  ]
}

                   Figure 22: Example: Verification SET

4.2.  Authorization

   HTTP API calls from a Receiver to a Transmitter SHOULD be authorized
   by providing an OAuth 2 Access Token as defined by [RFC6750].

   The receiver may obtain an access token using the Client Credential
   Grant [CLIENTCRED], or any other method suitable for the Receiver and
   the Transmitter.

   Other authorization methods MAY be used if the Transmitter and the
   Receiver have agreement on the method.

4.3.  Security Considerations

4.3.1.  Subject Probing

   It may be possible for an Event Transmitter to leak information about
   subjects through their responses to add subject requests.  A "404"
   response may indicate to the Event Receiver that the subject does not
   exist, which may inadvertantly reveal information about the subject
   (e.g. that a particular individual does or does not use the Event
   Transmitter's service).

   Event Transmitters SHOULD carefully evaluate the conditions under
   which they will return error responses to add subject requests.
   Event Transmitters MAY return a "204" response even if they will not
   actually send any events related to the subject, and Event Receivers
   MUST NOT assume that a 204 response means that they will receive
   events related to the subject.








Scurtescu, et al.       Expires October 26, 2018               [Page 25]


                           openid-risc-profile                April 2018


4.3.2.  Information Harvesting

   SETs may contain personally identifiable information (PII) or other
   non-public information about the event transmitter, the subject (of
   an event in the SET), or the relationship between the two.  It is
   important for Event Transmitters to understand what information they
   are revealing to Event Receivers when transmitting events to them,
   lest the event stream become a vector for unauthorized access to
   private information.

   Event Transmitters SHOULD interpret add subject requests as
   statements of interest in a subject by an Event Receiver, and ARE NOT
   obligated to transmit events related to every subject an Event
   Receiver adds to the stream.  Event Transmitters MAY choose to
   transmit some, all, or no events related to any given subject and
   SHOULD validate that they are permitted to share the information
   contained within an event with the Event Receiver before transmitting
   the event.  The mechanisms by which such validation is performed are
   outside the scope of this specification.

4.3.3.  Malicious Subject Removal

   A malicious party may find it advantageous to remove a particular
   subject from a stream, in order to reduce the Event Receiver's
   ability to detect malicious activity related to the subject,
   inconvenience the subject, or for other reasons.  Consequently it may
   be in the best interests of the subject for the Event Transmitter to
   continue to send events related to the subject for some time after
   the subject has been removed from a stream.

   Event Transmitters MAY continue sending events related to a subject
   for some amount of time after that subject has been removed from the
   stream.  Event Receivers MUST tolerate receiving events for subjects
   that have been removed from the stream, and MUST NOT report these
   events as errors to the Event Transmitter.

5.  Profiles

   This section is a profile of the following IETF SecEvent
   specifications:

   o  "Security Event Token (SET)" [SET]

   o  Push-Based SET Token Delivery Using HTTP [DELIVERYPUSH]

   o  Poll-Based SET Token Delivery Using HTTP [DELIVERYPOLL]





Scurtescu, et al.       Expires October 26, 2018               [Page 26]


                           openid-risc-profile                April 2018


   The RISC use cases that set the requirements are described in
   Security Events RISC Use Cases [USECASES].

5.1.  Security Event Token Profle

   This section provides RISC profiling specifications for the "Security
   Event Token (SET)" [SET] spec.

5.1.1.  Signature Key Resolution

   The signature key can be obtained through "jwks_uri", see Section 3.

5.1.2.  RISC Event Subject

   The subject of a RISC event is identified by the "subject" claim
   within the event payload, whose value is a Subject Identifier.  The
   "subject" claim is REQUIRED for all RISC events.  The JWT "sub" claim
   MUST NOT be present in any SET containing a RISC event.

   {
     "iss": "https://idp.example.com/",
     "jti": "756E69717565206964656E746966696572",
     "iat": 1520364019,
     "aud": "636C69656E745F6964",
     "events": {
       "https://schemas.openid.net/secevent/risc/event-type/account-\
   disabled": {
         "subject": {
           "subject_type": "phone",
           "phone_number": "+1 206 555 0123"
         },
         "reason": "hijacking",
         "cause-time": 1508012752
       }
     }
   }

    Figure 23: Example: SET Containing a RISC Event with a Phone Number
                                  Subject

5.1.3.  Explicit Typing of SETs

   RISC events MUST use explicit typing as defined in Section 2.3 of
   [SET].







Scurtescu, et al.       Expires October 26, 2018               [Page 27]


                           openid-risc-profile                April 2018


   {
     "typ":"secevent+jwt",
     "alg":"HS256"
   }

                  Figure 24: Explicitly Typed JOSE Header

   The purpose is defense against confusion with other JWTs, as
   described in Sections 4.5, 4.6 and 4.7 of [SET].  While current Id
   Token [IDTOKEN] validators may not be using the "typ" header
   parameter, by requiring it for RISC SETs a distinct value is
   guaranteed for future validators.

5.1.4.  The "exp" Claim

   The "exp" claim MUST NOT be used in RISC SETs.

   The purpose is defense in depth against confusion with other JWTs, as
   described in Sections 4.5 and 4.6 of [SET].

5.1.5.  The "aud" Claim

   The "aud" claim can be a single value or an array.  Each value SHOULD
   be the OAuth 2 client id.  Other values that uniquely identifies the
   Receiver to the Transmitter MAY be used, if the two parties have
   agreement on the format.

   More than one values can be present if the corresponding Receivers
   are known to the Transmitter to be the same entity, for example a web
   client and I mobile client of the same application.  All the
   Receivers in this case MUST use the exact same delivery method.

   If multiple Receivers have the exact same delivery configuration but
   the Transmitter does not know if they belong to the same entity then
   the Transmitter SHOULD issue distinct SETs for each Receiver and
   deliver them separately.  In this case the multiple Receivers might
   use the same service to process SETs, and this service might reroute
   SETs to respective Receivers, an "aud" claim with multiple Receivers
   would lead to unintended data disclosure.












Scurtescu, et al.       Expires October 26, 2018               [Page 28]


                           openid-risc-profile                April 2018


{
  "jti": "123456",
  "iss": "https://transmitter.example.com",
  "aud": ["receiver.example.com/web", "receiver.example.com/mobile"],
  "iat": "1493856000",
  "events": [
    "https://schemas.openid.net/secevent/risc/event-type/verification":{
      "state": "VGhpcyBpcyBhbiBleGFtcGxlIHN0YXRlIHZhbHVlLgo="
    }
  ]
}

              Figure 25: Example: SET with array 'aud' claim

5.1.6.  The "events" claim

   The "events" claim SHOULD contain only one event.  Multiple event
   type URIs are permitted only if they are alternative URIs defining
   the exact same event type.

5.1.7.  Security Considerations

5.1.7.1.  Distingushing SETs from other Kinds of JWTs

   Of particular concern is the possibility that SETs are confused for
   other kinds of JWTs.  The Security Considerations sesction of [SET]
   has several sub-sections on this subject.  The RISC Profile is asking
   for further restrioctons:

   o  The "sub" claim MUST NOT be present, as described in
      Section 5.1.2.

   o  RISC SETs MUST use explicit typing, as described in Section 5.1.3.

   o  The "exp" claim MUST NOT be present, as described in
      Section 5.1.4.

5.2.  SET Token Delivery Using HTTP Profile

   This section provides RISC profiling specifications for the
   [DELIVERYPUSH] and [DELIVERYPOLL] specs.

5.2.1.  Stream Configuration Metadata

   Each delivery method is identified by a URI, specified below by the
   "method" metadata.





Scurtescu, et al.       Expires October 26, 2018               [Page 29]


                           openid-risc-profile                April 2018


5.2.1.1.  Push Delivery using HTTP

   This section provides RISC profiling specifications for the
   [DELIVERYPUSH] spec.

   method  "https://schemas.openid.net/secevent/risc/delivery-method/
      push"

   endpoint_url  The URL where events are pushed through HTTP POST.
      This is set by the Receiver.

   authorization_header  The HTTP Authorization header that the
      Transmitter MUST set with each event delivery, if the
      configuration is present.  The value is optional and it is set by
      the Receiver.

5.2.1.2.  Polling Delivery using HTTP

   This section provides RISC profiling specifications for the
   [DELIVERYPOLL] spec.

   method  "https://schemas.openid.net/secevent/risc/delivery-method/
      poll"

   endpoint_url  The URL where events can be retrieved from.  This is
      specified by the Transmitter.

6.  IANA Considerations

6.1.  Security Event Subject Identifier Types Registry

   This document defines Subject Identifier Types, for which IANA is
   asked to create and maintain a new registry titled "Security Event
   Subject Identifier Types".  Initial values for the Security Event
   Subject Identifier Types registry are given in Section 6.1.2.  Future
   assignments are to be made through the Expert Review registration
   policy [BCP26] and shall follow the template presented in
   Section 6.1.1.

6.1.1.  Registration Template

   Type Name:
      The name of the Subject Identifier Type, as described in
      Section 2.1.  The name MUST be an ASCII string consisting only of
      lower-case characters ("a" - "z"), digits ("0" - "9"), and hyphens
      ("-"), and SHOULD NOT exceed 20 characters in length.

   Type Description:



Scurtescu, et al.       Expires October 26, 2018               [Page 30]


                           openid-risc-profile                April 2018


      A brief description of the Subject Identifier Type.

   Change Controller:
      For types defined in documents published by the OpenID Foundation
      or its working groups, list "OIDF RISC Working Group".  For all
      other types, list the name of the party responsible for the
      registration.  Contact information such as mailing address, email
      address, or phone number may also be provided.

   Defining Document(s):
      A reference to the document or documents that define the Subject
      Identifier Type.  The definition MUST specify the name, format,
      and meaning of each claim that may occur within a Subject
      Identifier of the defined type, as well as whether each claim is
      optional or required, or the circumstances under which the claim
      is optional or required.  URIs that can be used to retrieve copies
      of each document SHOULD be included.

6.1.2.  Initial Registry Contents

   o  Type Name: "email"
   o  Type Description: Subject identifier based on email address.
   o  Change Controller: OIDF RISC Working Group
   o  Defining Document(s): Section 2.1.1 of this document.

   o  Type Name: "id_token_claims"
   o  Type Description: Subject identifier based on OpenID Connect ID
      Token claims.
   o  Change Controller: OIDF RISC Working Group
   o  Defining Document(s): Section 2.1.4 of this document.

   o  Type Name: "iss_sub"
   o  Type Description: Subject identifier based on issuer and subject.
   o  Change Controller: OIDF RISC Working Group
   o  Defining Document(s): Section 2.1.3 of this document.

   o  Type Name: "phone"
   o  Type Description: Subject identifier based on phone number.
   o  Change Controller: OIDF RISC Working Group
   o  Defining Document(s): Section 2.1.2 of this document.

6.1.3.  Guidance for Expert Reviewers

   The Expert Reviewer is expected to review the documentation
   referenced in a registration request to verify its completeness.  The
   Expert Reviewer must base their decision to accept or reject the
   request on a fair and impartial assessment of the request.  If the
   Expert Reviewer has a conflict of interest, such as being an author



Scurtescu, et al.       Expires October 26, 2018               [Page 31]


                           openid-risc-profile                April 2018


   of a defining document referenced by the request, they must recuse
   themselves from the approval process for that request.  In the case
   where a request is rejected, the Expert Reviewer should provide the
   requesting party with a written statement expressing the reason for
   rejection, and be prepared to cite any sources of information that
   went into that decision.

   Subject Identifier Types need not be generally applicable and may be
   highly specific to a particular domain; it is expected that types may
   be registered for niche or industry-specific use cases.  The Expert
   Reviewer should focus on whether the type is thoroughly documented,
   and whether its registration will promote or harm interoperability.
   In most cases, the Expert Reviewer should not approve a request if
   the registration would contribute to confusion, or amount to a
   synonym for an existing type.

6.2.  Well-Known URI Registry

   TODO: follow steps in Section 5.1 of [RFC5785] to send a registration
   request.

   This specification registers the well-known URI defined in Section 3
   in the IANA Well-Known URI registry defined in [RFC5785].

6.2.1.  Registry Contents

   o  URI suffix: "risc-configuration"

   o  Change controller: OpenID Foundation RISC Working Group - openid-
      specs-risc at lists.openid.net

   o  Specification document: Section 3 of this document

   o  Related information: (none)

7.  Privacy Considerations

7.1.  Subject Information Leakage

   Event issuers and recipients SHOULD take precautions to ensure that
   they do not leak information about subjects via Subject Identifiers,
   and choose appropriate Subject Identifier Types accordingly.  Parties
   SHOULD NOT identify a subject using a given Subject Identifier Type
   if doing so will allow the recipient to correlate different claims
   about the subject that they are not known to already have knowledge
   of.  Issuers and recipients SHOULD always use the same Subject
   Identifier Type and the same claim values to identify a given subject




Scurtescu, et al.       Expires October 26, 2018               [Page 32]


                           openid-risc-profile                April 2018


   when communicating with a given party in order to reduce the
   possibility of information leakage.

8.  References

8.1.  Normative References

   [BCP26]    Cotton, M., Leiba, B., and T. Narten, "Guidelines for
              Writing an IANA Considerations Section in RFCs", BCP 26,
              RFC 8126, DOI 10.17487/RFC8126, June 2017,
              <https://tools.ietf.org/html/rfc8126>.

   [CLIENTCRED]
              Hardt, D., Ed., "The OAuth 2.0 Authorization Framework -
              Client Credentials Grant", RFC 6749, DOI 10.17487/RFC6749,
              October 2012, <https://tools.ietf.org/html/
              rfc6749#section-4.4>.

   [DELIVERYPOLL]
              Backman, A., Ed., Jones, M., Ed., Hunt, P., Ed.,
              Scurtescu, M., Ansari, M., and A. Nadalin, "Poll-Based SET
              Token Delivery Using HTTP", April 2018,
              <https://tools.ietf.org/html/draft-ietf-secevent-http-
              poll-00>.

   [DELIVERYPUSH]
              Backman, A., Ed., Jones, M., Ed., Hunt, P., Ed.,
              Scurtescu, M., Ansari, M., and A. Nadalin, "Push-Based SET
              Token Delivery Using HTTP", April 2018,
              <https://tools.ietf.org/html/draft-ietf-secevent-http-
              push-00>.

   [E164]     International Telecommunication Union, "The international
              public telecommunication numbering plan", 2010,
              <http://www.itu.int/rec/T-REC-E.164-201011-I/en>.

   [IDTOKEN]  Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., and
              C. Mortimore, "OpenID Connect Core 1.0 - ID Token", April
              2017, <http://openid.net/specs/
              openid-connect-core-1_0.html#IDToken>.

   [MGMTAPI]  Scurtescu, M. and A. Backman, "Management API for SET
              Event Streams", June 2017, <https://tools.ietf.org/html/
              draft-scurtescu-secevent-simple-control-plane>.







Scurtescu, et al.       Expires October 26, 2018               [Page 33]


                           openid-risc-profile                April 2018


   [OAUTH-DISCOVERY]
              Jones, M., Sakimura, N., and J. Bradley, "OAuth 2.0
              Authorization Server Metadata - Version 10", March 2018,
              <https://tools.ietf.org/html/draft-ietf-oauth-discovery-
              10>.

   [OIDC-DISCOVERY]
              Sakimura, N., Bradley, J., Jones, M., and E. Jay, "OpenID
              Connect Discovery 1.0", November 2014,
              <https://openid.net/specs/openid-connect-discovery-
              1_0.html>.

   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
              Requirement Levels", BCP 14, RFC 2119,
              DOI 10.17487/RFC2119, March 1997, <https://www.rfc-
              editor.org/info/rfc2119>.

   [RFC5785]  Nottingham, M. and E. Hammer-Lahav, "Defining Well-Known
              Uniform Resource Identifiers (URIs)", RFC 5785,
              DOI 10.17487/RFC5785, April 2010, <https://www.rfc-
              editor.org/info/rfc5785>.

   [RFC6750]  Jones, M. and D. Hardt, "The OAuth 2.0 Authorization
              Framework: Bearer Token Usage", RFC 6750,
              DOI 10.17487/RFC6750, October 2012, <https://www.rfc-
              editor.org/info/rfc6750>.

   [RFC7159]  Bray, T., Ed., "The JavaScript Object Notation (JSON) Data
              Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March
              2014, <https://www.rfc-editor.org/info/rfc7159>.

   [RFC7517]  Jones, M., "JSON Web Key (JWK)", RFC 7517,
              DOI 10.17487/RFC7517, May 2015, <https://www.rfc-
              editor.org/info/rfc7517>.

   [RFC7519]  Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token
              (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015,
              <https://www.rfc-editor.org/info/rfc7519>.

   [RFC8174]  Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
              2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
              May 2017, <https://www.rfc-editor.org/info/rfc8174>.

   [SET]      Hunt, P., Ed., Jones, M., Denniss, W., and M. Ansari,
              "Security Event Token (SET)", April 2018,
              <https://tools.ietf.org/html/draft-ietf-secevent-token-
              09>.




Scurtescu, et al.       Expires October 26, 2018               [Page 34]


                           openid-risc-profile                April 2018


   [USECASES]
              Scurtescu, M., "Security Events RISC Use Cases", June
              2017, <https://tools.ietf.org/html/draft-scurtescu-
              secevent-risc-use-cases-00>.

8.2.  URIs

   [1] https://datatracker.ietf.org/wg/secevent/about/

Appendix A.  Acknowledgements

   Transmitter Configuration Discovery (Section 3) is based on both
   OpenID Connect Discovery 1.0 [OIDC-DISCOVERY] and OAuth 2.0
   Authorization Server Metadata [OAUTH-DISCOVERY].

Authors' Addresses

   Marius Scurtescu
   Google

   Email: mscurtescu at google.com


   Annabelle Backman
   Amazon

   Email: richanna at amazon.com


   John Bradley
   Yubico

   Email: secevemt at ve7jtb.com


















Scurtescu, et al.       Expires October 26, 2018               [Page 35]
-------------- next part --------------
A non-text attachment was scrubbed...
Name: openid-risc-profile-1_0.xml
Type: text/xml
Size: 86285 bytes
Desc: not available
URL: <http://lists.openid.net/pipermail/openid-specs-risc/attachments/20180424/35f7c3fa/attachment-0005.xml>


More information about the Openid-specs-risc mailing list