<?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="openid-risc-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="openid-risc-event-types">OpenID RISC Event Types 1.0</title>

    <author initials="M." surname="Scurtescu" fullname="Marius Scurtescu">
      <organization abbrev="Google">Google</organization>
      <address>
        <email>mscurtescu@google.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 RISC 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>
      
      <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="event-types" title="Event Types">
      <t>The base URI for RISC event types is:<vspace />
        https://schemas.openid.net/secevent/risc/event-type/</t>
      
      <section anchor="account-credential-change-required" title="Account Credential Change Required">
        <t>Event Type URI:<vspace />
        https://schemas.openid.net/secevent/risc/event-type/account-credential-change-required</t>
        
        <t>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.</t>
        
        <t>Attributes: none</t>

        <figure anchor="account-credential-change-required-example" title="Example: Account Credential Change Required">
          <artwork><![CDATA[
{
  "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",
      }
    }
  }
}
            ]]></artwork>
          <postamble><spanx style="emph">(the event type URI is wrapped, the backslash is the continuation character)</spanx></postamble>
        </figure>
      </section>

      <section anchor="account-purged" title="Account Purged">
        <t>Event Type URI:<vspace />
        https://schemas.openid.net/secevent/risc/event-type/account-purged</t>
        
        <t>Account Purged signals that the account identified by the subject has been permanently deleted.</t>
        
        <t>Attributes: none</t>
      </section>

      <section anchor="account-disabled" title="Account Disabled">
        <t>Event Type URI:<vspace />
        https://schemas.openid.net/secevent/risc/event-type/account-disabled</t>
        
        <t>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 <spanx style="verb">reason</spanx> attribute described below. The account may be
        <xref target="account-enabled">enabled</xref> in the future.</t>
        
        <t>Attributes:<list style="symbols">
          <t>reason - optional, describes why was the account disabled. Possible values:<list style="symbols">
            <t>hijacking</t>
            <t>bulk-account</t>
          </list></t>
        </list></t>

        <figure anchor="account-disabled-example" title="Example: Account Disabled">
          <artwork><![CDATA[
{
  "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",
    }
  }
}
            ]]></artwork>
          <postamble><spanx style="emph">(the event type URI is wrapped, the backslash is the continuation character)</spanx></postamble>
        </figure>
      </section>

      <section anchor="account-enabled" title="Account Enabled">
        <t>Event Type URI:<vspace />
        https://schemas.openid.net/secevent/risc/event-type/account-enabled</t>
        
        <t>Account Enabled signals that the account identified by the subject has been enabled.</t>
        
        <t>Attributes: none</t>
      </section>

      <section anchor="identifier-changed" title="Identifier Changed">
        <t>Event Type URI:<vspace />
          https://schemas.openid.net/secevent/risc/event-type/identifier-changed</t>
        
        <t>Identifier Changed signals that the identifier specified in the subject has changed. The subject
          type MUST be either <spanx style="verb">email</spanx> or <spanx style="verb">phone</spanx> 
          and it MUST specify the old value.</t>
        
        <t>This event SHOULD be issued only by the provider that is authoritative over the identifier.
          For example, if the person that owns <spanx style="verb">john.doe@example.com</spanx> goes 
          through a name change and wants the new <spanx style="verb">john.row@example.com</spanx> email
          then <spanx style="strong">only</spanx> the email provider <spanx style="verb">example.com</spanx>
          SHOULD issue an Identifier Changed event as shown in the example below.</t>
        
        <t>If an identifier used as a username or recovery option is changed, at a provider that is not
          authoritative over that identifier, then <xref target="recovery-information-changed">Recovery Information Changed</xref> 
          SHOULD be used instead.</t>
        
        <t>Attributes:<list style="symbols">
          <t>new-value - optional, the new value of the identifier.</t>
        </list></t>
        
        <figure anchor="identifier-changed-example" title="Example: Identifier Changed">
          <artwork><![CDATA[
{
  "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@example.com",
      },
      "new-value": "john.roe@example.com",
    }
  }
}
            ]]></artwork>
          <postamble>The <spanx style="verb">foo@example.com</spanx> email changed to <spanx style="verb">bar@example.com</spanx>.
            <spanx style="emph">(the event type URI is wrapped, the backslash is the continuation character)</spanx></postamble>
        </figure>
      </section>

      <section anchor="identifier-recycled" title="Identifier Recycled">
        <t>Event Type URI:<vspace />
        https://schemas.openid.net/secevent/risc/event-type/identifier-recycled</t>
        
        <t>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 <spanx style="verb">email</spanx> or 
        <spanx style="verb">phone</spanx>.</t>
        
        <t>Attributes: none</t>
        
        <figure anchor="identifier-recycled-example" title="Example: Identifier Recycled">
          <artwork><![CDATA[
{
  "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@example.com",
      }
    }
  }
}
            ]]></artwork>
          <postamble>The 'foo@example.com' email address was recycled.
            <spanx style="emph">(the event type URI is wrapped, the backslash is the continuation character)</spanx></postamble>
        </figure>
      </section>

      <section anchor="opt-out" title="Opt Out">
        <t>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:<list style="numbers">
          <t>opt-in - the account is participating in RISC event exchange.</t>
          <t>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.</t>
          <t>opt-out - the account is NOT participating in RISC event exchange.</t>
        </list></t>
        
        <figure anchor="opt-out-states" title="Opt-Out States and Opt-Out Events">
          <preamble>State changes trigger Opt-Out Events as represented bellow:</preamble>
          <artwork><![CDATA[
+--------+  opt-out-initiated  +-------------------+
|        +--------------------->                   |
| opt-in |                     | opt-out-initiated |
|        |  pt-out-cancelled   |                   |
|        <---------------------+                   |
+---^----+                     +----------+--------+
    |                                     |
    | opt-in                              | opt-out-effective
    |                                     |
    |                          +----------V--------+
    |                          |                   |
    +--------------------------| opt-out           |
                               |                   |
                               +-------------------+
          ]]></artwork>
        </figure>
        
        <t>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.</t>
        
        <section anchor="opt-in" title="Opt In">
          <t>Event Type URI:<vspace />
          https://schemas.openid.net/secevent/risc/event-type/opt-in</t>
        
          <t>Opt In signals that the account identified by the subject opted into RISC event exchanges.
          The account is in the <spanx style="verb">opt-in</spanx> state.</t>
        
          <t>Attributes: none</t>
        </section>
        
        <section anchor="opt-out-initiated" title="Opt Out Initiated">
          <t>Event Type URI:<vspace />
          https://schemas.openid.net/secevent/risc/event-type/opt-out-initiated</t>
        
          <t>Opt Out Initiated signals that the account identified by the subject initiated to opt out
          from RISC event exchanges. The account is in the <spanx style="verb">opt-out-initiated</spanx> state.</t>
        
          <t>Attributes: none</t>
        </section>
        
        <section anchor="opt-out-cancelled" title="Opt Out Cancelled">
          <t>Event Type URI:<vspace />
          https://schemas.openid.net/secevent/risc/event-type/opt-out-cancelled</t>
        
          <t>Opt Out Cancelled signals that the account identified by the subject cancelled the opt out from RISC
          event exchanges. The account is in the <spanx style="verb">opt-in</spanx> state.</t>
        
          <t>Attributes: none</t>
        </section>
        
        <section anchor="opt-out-effective" title="Opt Out Effective">
          <t>Event Type URI:<vspace />
          https://schemas.openid.net/secevent/risc/event-type/opt-out-effective</t>
        
          <t>Opt Out Effective signals that the account identified by the subject was effectively opted out from
          RISC event exchanges. The account is in the <spanx style="verb">opt-out</spanx> state.</t>
        
          <t>Attributes: none</t>
        </section>
      </section>
      
      <section anchor="recovery-activated" title="Recovery Activated">
        <t>Event Type URI:<vspace />
        https://schemas.openid.net/secevent/risc/event-type/recovery-activated</t>
        
        <t>Recovery Activated signals that the account identified by the subject activated a recovery flow.</t>
        
        <t>Attributes: none</t>
      </section>

      <section anchor="recovery-information-changed" title="Recovery Information Changed">
        <t>Event Type URI:<vspace />
        https://schemas.openid.net/secevent/risc/event-type/recovery-information-changed</t>
        
        <t>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.</t>
        
        <t>Attributes: none</t>
      </section>

      <section anchor="sessions-revoked" title="Sessions Revoked">
        <t>Event Type URI:<vspace />
        https://schemas.openid.net/secevent/risc/event-type/sessions-revoked</t>
        
        <t>Sessions Revoked signals that all the sessions for the account identified by the subject have been
        revoked.</t>
        
        <t>Attributes: none</t>
      </section>
    </section>
  </middle>

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

      <reference anchor="JSON" target='https://www.rfc-editor.org/info/rfc7159'>
        <front>
          <title>The JavaScript Object Notation (JSON) Data Interchange Format</title>
            <author initials='T.' surname='Bray' fullname='T. Bray' role='editor'><organization /></author>
            <date year='2014' month='March' />
            <abstract><t>JavaScript Object Notation (JSON) is a lightweight, text-based, language-independent data interchange format.  It was derived from the ECMAScript Programming Language Standard.  JSON defines a small set of formatting rules for the portable representation of structured data.</t><t>This document removes inconsistencies with other specifications of JSON, repairs specification errors, and offers experience-based interoperability guidance.</t></abstract>
        </front>
        <seriesInfo name='RFC' value='7159'/>
        <seriesInfo name='DOI' value='10.17487/RFC7159'/>
      </reference>

      <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="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>
    </references>
  </back>
</rfc>
