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

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.

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:

"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:

"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:

  • subject - required, a Subjectect Identifier as defined by Section 2.1 that identifies the token.
  • token_subject - optional, a Subject Identifier as defined by Section 2.1 of [RISC-PROFILE] that identifies the account associated with the token.
  • TODO: OAuth flow and endpoints involved in the process? For example: redirect_uri, response_type, origin?

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:

  • subject - required, a Subjectect Identifier as defined by Section 2.1 that identifies the token.
  • token_subject - optional, a Subject Identifier as defined by Section 2.1 of [RISC-PROFILE] that identifies the account associated with the token.
  • 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?

{
  "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:

  • subject - optional, a Subject Identifier as defined by Section 2.1 of [RISC-PROFILE] that identifies the account associated with the token.
  • reason - optional, the reason why all the tokens were revoked. Possible values:
    • user - all tokens were revoked explicitly by the user
    • 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 [client-enabled] in the future.

Attributes: TODO use client subject identifier

{
  "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.

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.
[RFC6749] Hardt, D., "The OAuth 2.0 Authorization Framework", RFC 6749, DOI 10.17487/RFC6749, October 2012.
[RFC7009] Lodderstedt, T., Dronia, S. and M. Scurtescu, "OAuth 2.0 Token Revocation", RFC 7009, DOI 10.17487/RFC7009, August 2013.
[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017.
[RISC-PROFILE] Scurtescu, M., Backman, A. and J. Bradley, "OpenID RISC Profile of IETF Security Events 1.0", April 2018.
[SET] Hunt, P., Jones, M., Denniss, W. and M. Ansari, "Security Event Token (SET)", April 2018.

Authors' Addresses

Marius Scurtescu Google EMail: mscurtescu@google.com
Annabelle Backman Amazon EMail: richanna@amazon.com
Phil Hunt Oracle Corporation EMail: phil.hunt@yahoo.com
John Bradley Yubico EMail: secevemt@ve7jtb.com