oauth-event-types-1_0.xml

<?xml version="1.0" encoding="utf-8"?>
<?xml-stylesheet type='text/xsl' href='http://xml2rfc.tools.ietf.org/authoring/rfc2629.xslt' ?>
<!DOCTYPE rfc PUBLIC "-//IETF//DTD RFC 2629//EN" "http://xml2rfc.tools.ietf.org/authoring/rfc2629.dtd">
<!--
  NOTE:  This XML file is input used to produce the authoritative copy of an
  OpenID Foundation specification.  The authoritative copy is the HTML output.
  This XML source file is not authoritative.  The statement ipr="none" is
  present only to satisfy the document compilation tool and is not indicative
  of the IPR status of this specification.  The IPR for this specification is
  described in the "Notices" section.  This is a public OpenID Foundation
  document and not a private document, as the private="..." declaration could
  be taken to indicate.
-->

<rfc docName="oauth-event-types-1_0" category="std" ipr="none">

  <?rfc toc="yes" ?>
  <?rfc tocdepth="5" ?>
  <?rfc symrefs="yes" ?>
  <?rfc sortrefs="yes"?>
  <?rfc strict="yes" ?>
  <?rfc iprnotified="no" ?>
  <?rfc private="Draft" ?>
  <?rfc comments="yes"?>

  <front>
    <title abbrev="oauth-event-types">OAuth Event Types 1.0</title>

    <author initials="M." surname="Scurtescu" fullname="Marius Scurtescu">
      <organization abbrev="Coinbase">Coinbase</organization>
      <address>
        <email>marius.scurtescu@coinbase.com</email>
      </address>
    </author>
    <author initials="A." surname="Backman" fullname="Annabelle Backman">
      <organization abbrev="Amazon">Amazon</organization>
      <address>
        <email>richanna@amazon.com</email>
      </address>
    </author>
    <author initials="P." surname="Hunt" fullname="Phil Hunt">
      <organization abbrev="Oracle">Oracle Corporation</organization>
      <address>
        <email>phil.hunt@yahoo.com</email>
      </address>
    </author>
    <author initials="J." surname="Bradley" fullname="John Bradley">
      <organization abbrev="Yubico">Yubico</organization>
      <address>
        <email>secevemt@ve7jtb.com</email>
      </address>
    </author>

    <date year="2018" month="April" day="24"/>

    <workgroup>RISC Working Group</workgroup>

    <abstract>
      <t>This document defines the OAuth Event Types. Event Types are introduced and defined in <xref target="SET">Security Event Token (SET)</xref>.</t>
    </abstract>
  </front>

  <middle>
    <section anchor="intro" title="Introduction">
      <t>This specification is based on <xref target="RISC-PROFILE">RISC Profile</xref> and uses
      the subject identifiers defined there.</t>

      <t>The <spanx style="verb">aud</spanx> claim identifies the OAuth 2 client and its value SHOULD 
      be the <xref target="RFC6749">OAuth 2</xref> client id.</t>
      
      <section anchor="conv" title="Notational Conventions">
        <t>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 <xref target="RFC2119"/> <xref target="RFC8174"/> 
          when, and only when, they appear in all capitals, as shown here.</t>
      </section>
    </section>
    
    <section anchor="subject-identifier-types" title="OAuth Specific Subject Identifier Types">
      
      <t>This section defines OAuth specific Subject Identifier Types. Subject identifiers are defined in 
      Section 2 of <xref target="RISC-PROFILE"/>.</t>
      
      <section anchor="subject-identifier-token" title="Token Subject Identifier Type">
        <t>A Token Subject Identifier Type describes an OAuth 2 token subject and it is identified by
          the name <spanx style="verb">oauth_token</spanx>.</t>
        
        <t>Subject Identifiers of this type MUST contain the following claims:<list style="symbols">
          <t>token_type - required, describes the OAuth 2 token type. Possible values:<list style="symbols">
            <t>access_token</t>
            <t>authorization_code</t>
            <t>refresh_token</t>
          </list></t>
          <t>token_identifier_alg - required, describes how is the token string in the 
            <spanx style="verb">token</spanx> attribute to be interpreted.
            Possible values:<list style="symbols">
              <t>plain - plain token string</t>
              <t>prefix - token string prefix</t>
              <t>hash_* - token string hash, actual hash algorithms added as a suffix.
              TODO: create individual values for each hash algorithm.</t>
            </list></t>
          <t>token - required, the token identifier, as described by 
            <spanx style="verb">token_identifier_alg</spanx>.</t>
        </list></t>
        
        <figure anchor="subject-identifier-token-example" title="Example: Token Subject Identifier Type">
          <artwork><![CDATA[
"subject": {
  "subject_type": "oauth_token",
  "token_type": "refresh_token",
  "token_identifier_alg": "plain",
  "token": "7265667265736820746F6B656E20737472696E67"
}
            ]]></artwork>
        </figure>
      </section>
      
      <section anchor="subject-identifier-client" title="Client Subject Identifier Type">
        <t>A Client Subject Identifier Type describes an OAuth 2 client subject and it is identified by
          the name <spanx style="verb">oauth_client</spanx>.</t>
        
        <t>Subjects identifiers of this type MUST contain the following claim:<list style="symbols">
          <t>client_id - required, the OAuth 2 client id.</t>
        </list></t>
        
        <figure anchor="subject-identifier-client-example" title="Example: Client Subject Identifier Type">
          <artwork><![CDATA[
"subject": {
  "subject_type": "oauth_client",
  "client_id": "636C69656E74206964"
}
            ]]></artwork>
        </figure>
      </section>
    </section>
    
    <section anchor="event-types" title="Event Types">
      <t>The base URI for OAuth Event Types is:<vspace />
        https://schemas.openid.net/secevent/oauth/event-type/</t>
      
      <section anchor="token-issued" title="Token Issued">
        <t>Event Type URI:<vspace />
          https://schemas.openid.net/secevent/oauth/event-type/token-issued</t>
        
        <t>Token Issued signals that a new token was issued.</t>
        
        <t>Attributes:<list style="symbols">
          <t>subject - required, a Subject Identifier as defined by <xref target="subject-identifier-token"/> 
            that identifies the token.</t>
          <t>token_subject - optional, a Subject Identifier as defined by Section 2.1 of <xref target="RISC-PROFILE"/> 
            that identifies the account associated with the token.</t>
          <t>TODO: OAuth flow and endpoints involved in the process? For example: redirect_uri, response_type, origin?</t>
        </list></t>
        
        <t>The token SHOULD be uniquely identified by the provided attributes, either by 
          <spanx style="verb">subject</spanx> alone or by <spanx style="verb">subject</spanx>
          in combination with <spanx style="verb">token_subject</spanx>. The token is unique
          in the context of a given Transmitter and not globally unique. TODO: do we need a
          <spanx style="verb">iss</spanx> attribute for the <spanx style="verb">oauth_token</spanx>
          Subject Type?</t>
        
        <figure anchor="token-issued-example" title="Example: Token Issued">
          <artwork><![CDATA[
{
  "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": "plain",
        "token": "7265667265736820746F6B656E20737472696E67"
      },
      "token_subject" {
        "subject_type": "iss-sub",
        "iss": "https://idp.example.com/",
        "sub": "75736572206964"
      }
    }
  }
}
            ]]></artwork>
          <postamble><spanx style="emph">(the event type URI is wrapped, the backslash is the continuation character)</spanx></postamble>
        </figure>
      </section>
      
      <section anchor="token-revoked" title="Token Revoked">
        <t>Event Type URI:<vspace />
        https://schemas.openid.net/secevent/oauth/event-type/token-revoked</t>
        
        <t>Token Revoked signals that the token identified by this event was revoked.</t>
        
        <t>Attributes:<list style="symbols">
          <t>subject - required, a Subjectect Identifier as defined by <xref target="subject-identifier-token"/> 
            that identifies the token.</t>
          <t>token_subject - optional, a Subject Identifier as defined by Section 2.1 of <xref target="RISC-PROFILE"/> 
            that identifies the account associated with the token.</t>
          <t>reason - optional, the reason why the token was revoked.
            Possible values: <list style="symbols">
              <t>inactive - token was revoked by the issuer because of inactivity</t>
              <t>too_many - token was revoked by the issuer because an internal limit was reached</t>
              <t>api - token was revoked through an API call like <xref target="RFC7009"/></t>
              <t>user - token was revoked explicitly by the user</t>
              <t>issuer - token was revoked by the issuer for some other reason</t>
              <t>TODO: add extension mechanism (either through URIs or IANA registry)</t>
            </list></t>
        </list></t>
        
        <t>The token SHOULD be uniquely identified by the provided attributes, either by 
        <spanx style="verb">subject</spanx> alone or by <spanx style="verb">subject</spanx>
        in combination with <spanx style="verb">token_subject</spanx>. The token is unique
        in the context of a given Transmitter and not globally unique. TODO: do we need a
        <spanx style="verb">iss</spanx> attribute for the <spanx style="verb">oauth_token</spanx>
        Subject Type?</t>
        
        <figure anchor="token-revoked-example" title="Example: Token Revoked">
          <artwork><![CDATA[
{
  "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": "plain",
        "token": "7265667265736820746F6B656E20737472696E67"
      },
      "token_subject" {
        "subject_type": "iss-sub",
        "iss": "https://idp.example.com/",
        "sub": "75736572206964"
      },
      "reason": "inactive"
    }
  }
}
            ]]></artwork>
          <postamble><spanx style="emph">(the event type URI is wrapped, the backslash is the continuation character)</spanx></postamble>
        </figure>
      </section>

      <section anchor="tokens-revoked" title="Tokens Revoked">
        <t>Event Type URI:<vspace />
        https://schemas.openid.net/secevent/oauth/event-type/tokens-revoked</t>
        
        <t>Tokens Revoked signals that all tokens issued for the account identified by the subject have been
          revoked.</t>
        
        <t>Attributes:<list style="symbols">
          <t>subject - optional, a Subject Identifier as defined by Section 2.1 of <xref target="RISC-PROFILE"/> 
            that identifies the account associated with the token.</t>
          <t>reason - optional, the reason why all the tokens were revoked.
            Possible values: <list style="symbols">
              <t>user - all tokens were revoked explicitly by the user</t>
              <t>issuer - all tokens were revoked by the issuer</t>
              <t>TODO: add extension mechanism (either through URIs or IANA registry)</t>
            </list></t>
        </list></t>
        
        <figure anchor="tokens-revoked-example" title="Example: Tokens Revoked">
          <artwork><![CDATA[
{
  "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",
      },
    }
  }
}
            ]]></artwork>
          <postamble><spanx style="emph">(the event type URI is wrapped, the backslash is the continuation character)</spanx></postamble>
        </figure>
      </section>

      <section anchor="client_disabled" title="Client Disabled">
        <t>Event Type URI:<vspace />
        https://schemas.openid.net/secevent/oauth/event-type/client-disabled</t>
        
        <t>Client Disabled signals that the client identified by the <spanx style="verb">aud</spanx> 
        claim has been disabled. The client may be
        <xref target="client-enabled">enabled</xref> in the future.</t>
        
        <t>Attributes: TODO use client subject identifier</t>
        
        <figure anchor="client-disabled" title="Example: Client Disabled">
          <artwork><![CDATA[
{
  "iss": "https://idp.example.com/",
  "jti": "756E69717565206964656E746966696572",
  "iat": 1508184845,
  "aud": "636C69656E745F6964",
  "events": {
    "https://schemas.openid.net/secevent/oauth/event-type/\
    client-disabled": {}
  }
}
            ]]></artwork>
          <postamble><spanx style="emph">(the event type URI is wrapped, the backslash is the continuation character)</spanx></postamble>
        </figure>
      </section>

      <section anchor="client-enabled" title="Client Enabled">
        <t>Event Type URI:<vspace />
        https://schemas.openid.net/secevent/oauth/event-type/client-enabled</t>
        
        <t>Client Enabled signals that the client identified by the <spanx style="verb">aud</spanx> 
        claim has been enabled.</t>
        
        <t>Attributes: TODO use client subject identifier</t>
      </section>

      <section anchor="client-credential-changed" title="Client Credential Changed">
        <t>Event Type URI:<vspace />
        https://schemas.openid.net/secevent/oauth/event-type/client-credential-changed</t>
        
        <t>Client Credential Changed signals that one of the credentials of the client identified by 
        the <spanx style="verb">aud</spanx> claim has changed. For example the client secret has 
        changed.</t>
        
        <t>Attributes: TODO use client subject identifier</t>
      </section>

    </section>
    
    <section anchor="iana" title="IANA Considerations">
      <section anchor="iana-subject-identifier-type-registry" title="Subject Identifier Type Registry">
        <t>TODO: register <spanx style="verb">oauth_token</spanx> and <spanx style="verb">oauth_client</spanx> 
          subject identifier types.</t>
      </section>
    </section>
  </middle>

  <back>
    <references title='Normative References'>

      <reference anchor="SET" target="https://tools.ietf.org/html/draft-ietf-secevent-token-09">
        <front>
          <title>Security Event Token (SET)</title>
          <author fullname="Phil Hunt" initials="P." role="editor" surname="Hunt">
            <organization />
          </author>
          
          <author fullname="Michael B. Jones" initials="M.B." surname="Jones">
            <organization />
          </author>
          
          <author fullname="William Denniss" initials="W." surname="Denniss">
            <organization />
          </author>
          
          <author fullname="Morteza Ansari" initials="M.A." surname="Ansari">
            <organization />
          </author>
          
          <date year="2018" month="April" />
        </front>
      </reference>
      
      <reference anchor="RFC6749" target="https://www.rfc-editor.org/info/rfc6749">
        <front>
          <title>The OAuth 2.0 Authorization Framework</title>
          <author initials="D." surname="Hardt" fullname="D. Hardt" role="editor">
            <organization/>
          </author>
          <date year="2012" month="October"/>
          <abstract>
            <t>
              The OAuth 2.0 authorization framework enables a third-party application to obtain limited access to an HTTP service, either on behalf of a resource owner by orchestrating an approval interaction between the resource owner and the HTTP service, or by allowing the third-party application to obtain access on its own behalf. This specification replaces and obsoletes the OAuth 1.0 protocol described in RFC 5849. [STANDARDS-TRACK]
            </t>
          </abstract>
        </front>
        <seriesInfo name="RFC" value="6749"/>
        <seriesInfo name="DOI" value="10.17487/RFC6749"/>
      </reference>

      <reference anchor="RFC2119" target='https://www.rfc-editor.org/info/rfc2119'>
        <front>
          <title>Key words for use in RFCs to Indicate Requirement Levels</title>
          <author initials='S.' surname='Bradner' fullname='S. Bradner'><organization /></author>
          <date year='1997' month='March' />
          <abstract><t>In many standards track documents several words are used to signify the requirements in the specification.  These words are often capitalized. This document defines these words as they should be interpreted in IETF documents.  This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements.</t></abstract>
        </front>
        <seriesInfo name='BCP' value='14'/>
        <seriesInfo name='RFC' value='2119'/>
        <seriesInfo name='DOI' value='10.17487/RFC2119'/>
      </reference>
      
      <reference anchor="RFC8174" target="https://www.rfc-editor.org/info/rfc8174">
        <front>
          <title>Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words</title>
          <author initials="B." surname="Leiba" fullname="B. Leiba">
            <organization/>
          </author>
          <date year="2017" month="May"/>
          <abstract>
            <t>RFC 2119 specifies common key words that may be used in protocol specifications. This 
              document aims to reduce the ambiguity by clarifying that only UPPERCASE usage of the 
              key words have the defined special meanings.</t>
          </abstract>
        </front>
        <seriesInfo name="BCP" value="14"/>
        <seriesInfo name="RFC" value="8174"/>
        <seriesInfo name="DOI" value="10.17487/RFC8174"/>
      </reference>
      
      <reference anchor="RISC-PROFILE" target="http://openid.net/specs/openid-risc-profile-1_0.html">
        <front>
          <title>OpenID RISC Profile of IETF Security Events 1.0</title>
          <author initials="M." surname="Scurtescu" fullname="Marius Scurtescu">
            <organization />
          </author>
          <author initials="A." surname="Backman" fullname="Annabelle Backman">
            <organization />
          </author>
          <author initials="J." surname="Bradley" fullname="John Bradley">
            <organization />
          </author>
          <date year="2018" month="April" />
        </front>
      </reference>
      
      <reference anchor="RFC7009" target="https://www.rfc-editor.org/info/rfc7009">
        <front>
          <title>OAuth 2.0 Token Revocation</title>
          <author initials="T." surname="Lodderstedt" fullname="T. Lodderstedt" role="editor">
            <organization/>
          </author>
          <author initials="S." surname="Dronia" fullname="S. Dronia">
            <organization/>
          </author>
          <author initials="M." surname="Scurtescu" fullname="M. Scurtescu">
            <organization/>
          </author>
          <date year="2013" month="August"/>
          <abstract>
            <t>
              This document proposes an additional endpoint for OAuth authorization servers, which allows clients to notify the authorization server that a previously obtained refresh or access token is no longer needed. This allows the authorization server to clean up security credentials. A revocation request will invalidate the actual token and, if applicable, other tokens based on the same authorization grant.
            </t>
          </abstract>
        </front>
        <seriesInfo name="RFC" value="7009"/>
        <seriesInfo name="DOI" value="10.17487/RFC7009"/>
      </reference>
    </references>
  </back>
</rfc>