[Openid-specs-risc] OAuth Event Types updates

Marius Scurtescu mscurtescu at google.com
Mon Apr 23 02:06:57 UTC 2018


The OAuth Event Types spec updates:
- added OAuth client subject type
- added OAuth token subject type
- added token-issued event type
- added reason attribute to token-revoked
- collision and user identifier advice for token_revoked

Latest version attached.

Marius
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openid.net/pipermail/openid-specs-risc/attachments/20180422/2a102e68/attachment.html>
-------------- next part --------------




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


                           OAuth Event Types
                          oauth-event-types-00

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  . . . . . . . . . . . . . . . . . . . . .   5
     3.4.  Client Disabled . . . . . . . . . . . . . . . . . . . . .   6
     3.5.  Client Enabled  . . . . . . . . . . . . . . . . . . . . .   7
     3.6.  Client Credential Changed . . . . . . . . . . . . . . . .   7
   4.  IANA Considerations . . . . . . . . . . . . . . . . . . . . .   7
     4.1.  Subject Identifier Type Registry  . . . . . . . . . . . .   7
   5.  Normative References  . . . . . . . . . . . . . . . . . . . .   8
   Authors' Addresses  . . . . . . . . . . . . . . . . . . . . . . .   8

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 24, 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_type - required, describes how is the token
      identified.  Possible values:

      *  token_string

      *  token_string_hash

      *  token_string_prefix

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

   o  token_string_hash_alg - optional, the token string hash algorithm,
      required if "token_identifier_type" is "token_string_hash".  TODO:
      possible values.







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


                            oauth-event-types                 April 2018


   "subject": {
     "subject_type": "oauth_token",
     "token_type": "refresh_token",
     "token_identifier_type": "token_string",
     "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 24, 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_type": "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 24, 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, TODO: possible values ("inactive", "too_many",
      "api")?

   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-revoked": {
         "subject": {
           "subject_type": "oauth_token",
           "token_type": "refresh_token",
           "token_identifier_type": "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 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.



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


                            oauth-event-types                 April 2018


   Attributes: none

   {
     "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 24, 2018                [Page 6]


                            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 24, 2018                [Page 7]


                            oauth-event-types                 April 2018


5.  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>.

   [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>.

   [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]
              OpenID Foundation, "RISC Profile".

   [SET]      IETF, "Security Event Token (SET)",
              <https://tools.ietf.org/html/draft-ietf-secevent-token>.

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 24, 2018                [Page 8]


                            oauth-event-types                 April 2018


   John Bradley
   Yubico

   Email: secevemt at ve7jtb.com















































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


More information about the Openid-specs-risc mailing list