<?xml version="1.0" encoding="utf-8"?>
<?xml-stylesheet type='text/xsl' href='http://xml2rfc.tools.ietf.org/authoring/rfc2629.xslt' ?>
<!DOCTYPE rfc SYSTEM "rfc2629.dtd">

<?rfc toc="yes"?>
<?rfc tocompact="yes"?>
<?rfc tocdepth="3"?>
<?rfc tocindent="yes"?>
<?rfc symrefs="yes"?>
<?rfc sortrefs="yes"?>
<?rfc comments="yes"?>
<?rfc inline="yes"?>
<?rfc compact="yes"?>
<?rfc subcompact="no"?>

<rfc category="std" docName="draft-ietf-secevent-token-02" ipr="trust200902">
  <front>
    <title abbrev="draft-ietf-secevent-token">Security Event Token (SET)</title>

    <author fullname="Phil Hunt" initials="P." role="editor" surname="Hunt">
      <organization abbrev="Oracle">Oracle Corporation</organization>

      <address>
        <email>phil.hunt@yahoo.com</email>
      </address>
    </author>
    
    <author fullname="William Denniss" initials="W." surname="Denniss">
      <organization abbrev="Google">Google</organization>

      <address>
        <email>wdenniss@google.com</email>
      </address>
    </author>

    <author fullname="Morteza Ansari" initials="M.A." surname="Ansari">
      <organization abbrev="Cisco">Cisco</organization>

      <address>
        <email>morteza.ansari@cisco.com</email>
      </address>
    </author>

    <author fullname="Michael B. Jones" initials="M.B." surname="Jones">
      <organization abbrev="Microsoft">Microsoft</organization>
      <address>
        <email>mbj@microsoft.com</email>
	      <uri>http://self-issued.info/</uri>
      </address>
    </author>

    <date year="2017"/>

    <area>Security</area>
    <workgroup>Security Events Working Group</workgroup>

    <keyword>Identity</keyword>
    <keyword>Security</keyword>
    <keyword>Event</keyword>
    <keyword>Token</keyword>
    <keyword>Internet-Draft</keyword>

    <abstract>
      <t>This specification defines the Security Event Token, which may
      be distributed via a protocol such as HTTP. The Security Event Token 
      (SET) specification profiles the JSON Web Token (JWT), which can be 
      optionally signed and/or encrypted. A SET describes a statement 
      of fact from the perspective of an issuer that it intends to share
      with one or more receivers.</t>
    </abstract>
  </front>

  <middle>
    <section anchor="intro" title="Introduction and Overview" toc="default">
      <t>This specification defines an extensible Security Event Token 
      (SET) format which may be exchanged using protocols such as HTTP. 
      The specification builds on the JSON Web Token (JWT) format <xref target="RFC7519"/> 
      in order to provide a self-contained token that can be optionally 
      signed using JSON Web Signature (JWS) <xref target="RFC7515"/>
      and/or encrypted using JSON Web Encryption (JWE) <xref target="RFC7516"/>.</t>
      
      <t>This specification profiles the use of JWT for the purpose of 
      issuing security event tokens (SETs). This specification defines a 
      base format upon which profiling specifications define actual 
      events and their meanings. Unless otherwise 
      specified, this specification uses non-normative example events intended to 
      demonstrate how events may be constructed. </t>
      
      <t>This specification is scoped to security and identity related events.
      While security event tokens may be used for other purposes, the specification
      only considers security and privacy concerns relevant to identity 
      and personal information.</t>
      
      <t>Security Events are not commands issued between parties. 
      A security event is a statement of fact from the perspective of an 
      issuer about the state of a security subject (e.g., a web 
      resource, token, IP address, the issuer itself) that the issuer controls or is aware 
      of, that has changed in some way (explicitly or implicitly). A 
      security subject MAY be permanent (e.g., a user account) or 
      temporary (e.g., an HTTP session) in nature. A state change could 
      describe a direct change of entity state, an implicit change of state 
      or other higher-level security statements such as:
      <list style="symbols">
        <t>The creation, modification, removal of a resource.</t>
        <t>The resetting or suspension of an account.</t>
        <t>The revocation of a security token prior to its expiry.</t>
        <t>The logout of a user session. Or, </t>
        <t>A cumulative conclusion such as to indicate that a user has 
        taken over an email identifier that may have been used in the 
        past by another user.</t>
      </list>
      </t>
            
      <t>While subject state changes are often triggered by 
      a user-agent or security-subsystem, the issuance and transmission 
      of an event often occurs asynchronously and in a back-channel to
      the action which caused the change that generated the security 
      event. Subsequently, an Event Receiver, having received a SET, 
      validates and interprets the received SET and takes its own 
      independent actions, if any. For example, having been informed of
      a personal identifier being associated with a different security 
      subject (e.g., an email address is being used by someone else), 
      the Event Receiver may choose to ensure that the new user is not granted 
      access to resources associated with the previous user. Or, the 
      Event Receiver may not have any relationship with the subject, 
      and no action is taken.</t>
      
      <t>While Event Receivers will often take actions upon receiving 
      SETs, security events MUST NOT be assumed to be commands or requests. 
      The intent of this specification is to define a way of exchanging 
      statements of fact that subscribers may interpret for their own
      purposes. As such, SETs have no capability for error signaling 
      other to ensure the validation of a received SET. </t>

      <section anchor="notat" title="Notational Conventions" toc="default">
        <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 <xref
        target="RFC2119"/>. These keywords are capitalized when used to
        unambiguously specify requirements of the protocol or application
        features and behavior that affect the inter-operability and security of
        implementations. When these words are not capitalized, they are meant
        in their natural-language sense.</t>

        <t>For purposes of readability, examples are not URL encoded.
        Implementers MUST percent encode URLs as described in <xref
        target="RFC3986">Section 2.1 of</xref>.</t>

        <t>Throughout this document, all figures MAY contain spaces and extra
        line-wrapping for readability and space limitations. Similarly, some
        URIs contained within examples have been shortened for space and
        readability reasons.</t>
      </section>

      <section anchor="defs" title="Definitions" toc="default">
        
        <t>
          The following definitions are used with SETs:
          <list style="hanging">
 
          <t hangText="Security Event Token (SET)"><vspace blankLines="0"/>
            A SET is a JWT <xref target="RFC7519"/> that is 
            distributed to one or more registered Event Receivers. 
          </t>
          
          <t hangText="Event Transmitter"><vspace/>
            A service provider that delivers SETs to other providers known
            as Event Receivers. 
          </t>
          
          <t hangText="Event Receiver"><vspace/>
            An Event Receiver is an entity that receives SETs through 
            some distribution method.  
          </t>
            
          <t hangText="Subject"><vspace blankLines="0"/>
            A SET describes an event or state change that has occurred 
            about a Subject. A Subject may be a principal (e.g., 
            <xref target="RFC7519">Section 4.1.2</xref>), a web resource,
            an entity such as an IP address, or the issuer itself that 
            a SET might reference.
          </t>
            
          <t hangText="Profiling Specification">A specification that 
            uses the SET Token specification to define one or more event
            types and the associated claims included.
          </t>
          </list>
        </t>
      </section>
    </section>

    <section anchor="events" title="The Security Event Token (SET)">
      <t>A SET is a data structure (in the form of a JWT
      <xref target="RFC7519"/>) representing one or more related security events 
      about a Subject.</t>
      
      <t>The schema and structure of a SET follows the JWT <xref target="RFC7519"/>
      specification. A SET has the following structure:
      <list style="symbols">
        <t>An outer JSON object that acts as the SET "envelope". The envelope 
        contains a set of name/value pairs called the JWT Claims Set, 
        typically common to every SET or common to a number of different 
        Events within a single Profiling Specification or a 
        related series of specifications. Claims in the envelope (the outer
        JSON structure) SHOULD be registered in the JWT Token Claims 
        Registry <xref target="RFC7519">Section 10.1</xref> or be
        Public Claims or Private Claims as also defined in <xref target="RFC7519"/>.</t>
        
        <t>Envelope claims that are profiled and defined 
        in this specification are used to validate a SET and declare the
        contents of the event data included in the SET. The claim 
        <spanx style="verb">events</spanx> identifies the event types 
        expressed that are related to the Security Subject and MAY also 
        include event-specific data.</t> 
        
        <t>Each JSON member of the <spanx style="verb">events</spanx> 
        object is a name and value pair. The JSON attribute name is a 
        URI String value that expresses an event type, and the 
        corresponding value is a JSON object known as the event "payload". 
        The payload JSON object contains claims typically unique to the 
        event's URI type value and are not registered as JWT claims. 
        These claims are defined by their associated Profiling 
        Specification. An event with no payload claims SHALL be represented as the empty JSON object 
        (<spanx style="verb">{}</spanx>). In many cases, one event URI expresses
        the primary event URI, while other events might be considered extensions
        that MAY be used to do things such as:<list style="symbols">
          <t>A categorization event type to provide classification 
          information (e.g., threat type or level).</t>
          <t>An enhancement of an existing specifications the arise over time.</t>
          <t>An extension needed to link a potential series of events.</t>
          <t>Localized specific purpose event URI used between a
          particular Event Transmitter and Receiver.</t>
        </list></t>
        
      </list>
      </t>

      <figure anchor="examplePassword" title="Example SCIM Password Reset Event">
        <preamble>The following is a non-normative example showing the JWT Claims Set for a hypothetical 
        SCIM password reset SET. This example shows an additional events 
        value (<spanx style="verb">https://example.com/scim/event/passwordResetExt</spanx>)
        used to convey additional information -- in this 
        case, the current count of reset attempts:</preamble>
        <artwork>
{ 
  "jti": "3d0c3cf797584bd193bd0fb1bd4e7d30",
  "iat": 1458496025,
  "iss": "https://scim.example.com",  
  "aud": [
    "https://jhub.example.com/Feeds/98d52461fa5bbc879593b7754",
    "https://jhub.example.com/Feeds/5d7604516b1d08641d7676ee7"
  ],  
  "sub": "https://scim.example.com/Users/44f6142df96bd6ab61e7521d9",
  "events": {
    "urn:ietf:params:scim:event:passwordReset": 
      { "id":"44f6142df96bd6ab61e7521d9"},
    "https://example.com/scim/event/passwordResetExt": 
      { "resetAttempts":5}
  }
}
</artwork>
      </figure>      
      <t>The event in the figure above expresses hypothetical password
      reset event for SCIM <xref target="RFC7644"/>. The JWT consists of:<list style="symbols">
        <t>An <spanx style="verb">events</spanx> claim specifying the hypothetical 
        SCIM URN (<spanx style="verb">urn:ietf:params:scim:event:passwordReset</spanx>) 
        for a password reset, and a local schema, 
        <spanx style="verb">https://example.com/scim/event/passwordResetExt</spanx>, 
        that is used to provide additional event information such as the 
        current count of resets.</t>
        <t>An <spanx style="verb">iss</spanx>
        claim, denoting the Event Transmitter.</t>
        <t>The <spanx style="verb">sub</spanx> claim specifies the SCIM 
        resource URI that was affected.</t>
        <t>The <spanx style="verb">aud</spanx> claim specifies the 
        intended audiences for the event. The syntax of the "aud" claim
        is defined in <xref target="RFC7519">Section 4.1.3</xref>.
        </t>
      </list></t>
      
      <t>In this example, the SCIM event 
      indicates that a password has been updated and the current 
      password reset count is 5. Notice that the value for 
      "resetAttempts" is actually part of its own JSON object associated
      with its own event URI attribute.  
      </t>

      <t><figure anchor="exampleBackLogoutEvent" title="Example OpenID Back-Channel Logout Event">
            <preamble>Here is another example JWT Claims Set for a security event token, this one
              for a Logout Token:</preamble>

            <artwork>
{
   "iss": "https://server.example.com",
   "sub": "248289761001",
   "aud": "s6BhdRkqt3",
   "iat": 1471566154,
   "jti": "bWJq",
   "sid": "08a5019c-17e1-4977-8f42-65a12843ea02",
   "events": {
     "http://schemas.openid.net/event/backchannel-logout": {}
   }
}
</artwork>
          </figure>Note that the above SET has an empty JSON object and
          uses the JWT registered claims <spanx style="verb">sub</spanx> 
          and <spanx style="verb">sid</spanx> to identify the subject
          that was logged-out.</t>
          <t>
          
          <figure anchor="exampleConsent" title="Example Consent Event">
        <preamble>In the following example JWT Claims Set, a fictional medical service collects 
          consent for medical actions and notifies other parties. The individual
          for whom consent is identified was originally authenticated via
          OpenID Connect.  In this case, the issuer of the security event is an
          application rather than the OpenID provider:</preamble>
        <artwork>
{ 
  "jti": "fb4e75b5411e4e19b6c0fe87950f7749",
  
  "sub": "248289761001",
  "iat": 1458496025,
  "iss": "https://my.examplemed.com",  
  "aud": [
    "https://rp.example.com"
  ],  
  "events": {
    "https://openid.net/heart/specs/consent.html":{
      "iss":"https://connect.example.com",
      "consentUri":[
        "https://terms.examplemed.com/labdisclosure.html#Agree"
      ]
    }
  }
}
</artwork>
      </figure>  
      In the above example, the attribute <spanx style="verb">iss</spanx> contained within the
      payload for the event <spanx style="verb">https://openid.net/heart/specs/consent.html</spanx> refers
      to the issuer of the Security Subject (<spanx style="verb">sub</spanx>) rather than the event
      issuer <spanx style="verb">https://my.examplemed.com</spanx>. They are
      distinct from the top level value of <spanx style="verb">iss</spanx>,
      which always refers to the issuer of the event - a medical consent
      service that is a relying party to the OpenID Provider.
          </t>
      
      <section anchor="EventContents" title="Core SET Claims">
        <t>The following are claims that are based on <xref target="RFC7519"/>
        claim definitions and are profiled for use in an event
        token:<list style="hanging">
            <t hangText="jti"><vspace blankLines="0"/>As defined by 
            <xref target="RFC7519">Section 4.1.7</xref> contains a unique
            identifier for an event. The identifier SHOULD be unique within
            a particular event feed and MAY be used by clients to track
            whether a particular event has already been received. This 
            claim is REQUIRED.</t>

            <t hangText="iss"><vspace blankLines="0"/>A single valued
            String containing the URI of the service provider publishing
            the SET (the issuer). This claim is REQUIRED. Note that when
            a SET is expressing an event about a Security Subject for
            which the SET issuer is not the issuer of the Security Subject,
            the conflict SHALL be resolved by including the Security Subject
            <spanx style="verb">iss</spanx> value within the event "payload" 
            (see <spanx style="verb">events</spanx> claim). </t>
 
            <t hangText="aud"><vspace blankLines="0"/>The syntax of the 
            claim is as defined in <xref target="RFC7519">Section 4.1.3</xref>.
            This claim contains one or more audience identifiers 
            for the SET. This claim is RECOMMENDED.</t>
            
            <t hangText="iat"><vspace blankLines="0"/>As defined by <xref target="RFC7519">Section 4.1.6</xref>,
            a value containing a NumericDate, which represents when the 
            event was issued. Unless otherwise specified,
            the value SHOULD be interpreted as equivalent 
            to the actual time of the event. This claim is REQUIRED. 
            </t> 
            
            <t hangText="nbf"><vspace blankLines="0"/>Defined by 
            <xref target="RFC7519">Section 4.1.5</xref>, a number 
            whose value is a NumericDate. In the context of the SET token
            it SHALL be interpreted to mean a date in which
            the event is believed to have occurred (in the past) or will occur in the 
            future. Note: there MAY be some cases where "nbf"
            is still smaller than "iat" such as when it took an extended 
            time for a SET to be issued (for example after some analysis). 
            This claim is OPTIONAL.</t> 
            
            <t hangText="sub">As defined by <xref target="RFC7519">Section 4.1.2</xref>,
            a String or URI value representing the principal or the subject of the SET. 
            This is usually the entity whose "state" was changed. For example,
            an IP Address was added to a black list. A URI representing a
            user resource that was modified. A token identifier for a revoked 
            token. If used, the Profile Specification SHOULD
            define the content and format semantics for the value. This claim
            is OPTIONAL, as the principal for any given profile may already be
            identified without the inclusion of a subject claim.
	    Note that some SET profiles MAY choose to convey event subject information
	    in the event payload, particularly if the subject information is
	    relative to issuer information that is also conveyed in the event payload,
	    which may be the case for some identity SET profiles.
	    </t>   
            
            <t hangText="exp">As defined by <xref target="RFC7519"/>, this claim
            is time on which the JWT MUST NOT be accepted for processing. In 
            the context of a SET however, this notion does not apply since
            a SET reflects something that has already been processed and is
            historical in nature. While some specifications MAY have a need
            for this claim, its use in general cases is NOT RECOMMENDED.</t>       
          </list>
        </t>
        <t>The following are new claims defined by this specification:<list style="hanging">
            <t hangText="events" anchor="eventDef"><vspace blankLines="0"/>
            The semantics of this claim is to define a set of event statements
            that each MAY add additional claims to fully describe a single
            logical event that has occurred (e.g. a state change to a subject).
            Multiple event statements of the same type SHALL NOT be accepted. 
            The <spanx style="verb">events</spanx>
            claim SHOULD NOT be used to express multiple logical events.</t>
            <t>The value of <spanx style="verb">events</spanx> is a
            JSON object whose members are a set of JSON name/value pairs
            whose names are URIs representing the event statements being 
            expressed. Event URI values SHOULD be stable values (e.g. a
            permanent URL for an event specification). For each name present, 
            the corresponding value 
            SHALL be a JSON object. The JSON object MAY be an empty 
            object (<spanx style="verb">{}</spanx>), or it MAY be a JSON 
            object containing data as described by the Profiling 
            Specification.</t>
            <t hangText="txn" anchor="txnDef"><vspace blankLines="0"/>
	          An OPTIONAL String value that represents a unique transaction 
            identifier. In cases where multiple SETs are issued based on 
            different event URIs, the transaction
            identifier MAY be used to correlate SETs to the same 
            originating event or stateful change.</t>
        </list></t>
      </section>

      <section anchor="ExplicitTyping" title="Explicit Typing of SETs">
	<t>
	  This specification registers the <spanx style="verb">application/secevent+jwt</spanx>
	  media type, which can be used to indicate that the content is a SET.
	  SETs MAY include this media type in the <spanx style="verb">typ</spanx> header parameter
	  of the JWT representing the SET to explicitly declare that the JWT is a SET.
	  This MUST be included if the SET could be used in an application context in which
	  it could be confused with other kinds of JWTs.
	</t>
	<t>
	  Per the definition of <spanx style="verb">typ</spanx> in Section 4.1.9 of <xref target="RFC7515"/>,
	  it is RECOMMENDED that the "application/" prefix be omitted.
	  Therefore, the <spanx style="verb">typ</spanx> value used SHOULD be
	  <spanx style="verb">secevent+jwt</spanx>.
	</t>
      </section>

      <section anchor="eventMessage" title="Security Event Token Construction">
        <t>A SET is a JWT <xref target="RFC7519"/> that is 
        constructed by building a JSON structure that constitutes an event 
        object which is then used as the body of a JWT.</t>
        <t>While this specification uses JWT to convey a SET, implementers
        SHALL NOT use SETs to convey authentication or authorization assertions.</t>

        <t><figure anchor="exampleJsonEvent" title="Example Event Claims">
            <preamble>The
            following is an example JWT Claims Set for a security event token (which has been formatted
            for readability):</preamble>

            <artwork>
{  
  "jti": "4d3559ec67504aaba65d40b0363faad8",
  "iat": 1458496404,
  "iss": "https://scim.example.com",  
  "aud": [
   "https://scim.example.com/Feeds/98d52461fa5bbc879593b7754",
   "https://scim.example.com/Feeds/5d7604516b1d08641d7676ee7"
  ],  
  
  "events": {
    "urn:ietf:params:scim:event:create": {
      "ref":
        "https://scim.example.com/Users/44f6142df96bd6ab61e7521d9",
      "attributes":["id", "name", "userName", "password", "emails"]
    }
  }
}
</artwork>
          </figure></t>

        <t>When transmitted, the above JSON body must be converted into a JWT
        as per <xref target="RFC7519"/>.</t>
     
        <t><figure>
            <preamble>The following is an example of a SCIM Event expressed as
            an unsecured JWT. The JOSE Header is:</preamble>

            <artwork>{"typ":"secevent+jwt","alg":"none"}</artwork>
          </figure><figure>
            <preamble>Base64url encoding of the octets of the UTF-8
            representation of the JOSE Header yields:</preamble>

            <artwork>eyJ0eXAiOiJzZWNldmVudCtqd3QiLCJhbGciOiJub25lIn0</artwork>
          </figure>
	  <figure>
            <preamble>The example JWT Claims Set is encoded as
            follows:</preamble>

            <artwork>
eyJqdGkiOiI0ZDM1NTllYzY3NTA0YWFiYTY1ZDQwYjAzNjNmYWFkOCIsImlhdCI6MTQ1
ODQ5NjQwNCwiaXNzIjoiaHR0cHM6Ly9zY2ltLmV4YW1wbGUuY29tIiwiYXVkIjpbImh0
dHBzOi8vc2NpbS5leGFtcGxlLmNvbS9GZWVkcy85OGQ1MjQ2MWZhNWJiYzg3OTU5M2I3
NzU0IiwiaHR0cHM6Ly9zY2ltLmV4YW1wbGUuY29tL0ZlZWRzLzVkNzYwNDUxNmIxZDA4
NjQxZDc2NzZlZTciXSwiZXZlbnRzIjp7InVybjppZXRmOnBhcmFtczpzY2ltOmV2ZW50
OmNyZWF0ZSI6eyJyZWYiOiJodHRwczovL3NjaW0uZXhhbXBsZS5jb20vVXNlcnMvNDRm
NjE0MmRmOTZiZDZhYjYxZTc1MjFkOSIsImF0dHJpYnV0ZXMiOlsiaWQiLCJuYW1lIiwi
dXNlck5hbWUiLCJwYXNzd29yZCIsImVtYWlscyJdfX19</artwork>
          </figure>
          <figure anchor="eventToken"
            title="Example Unsecured Security Event Token">
            <preamble>The encoded JWS signature is the empty string.
            Concatenating the parts yields:</preamble>

            <artwork>
eyJ0eXAiOiJzZWNldmVudCtqd3QiLCJhbGciOiJub25lIn0.
eyJqdGkiOiI0ZDM1NTllYzY3NTA0YWFiYTY1ZDQwYjAzNjNmYWFkOCIsImlhdCI6MTQ1
ODQ5NjQwNCwiaXNzIjoiaHR0cHM6Ly9zY2ltLmV4YW1wbGUuY29tIiwiYXVkIjpbImh0
dHBzOi8vc2NpbS5leGFtcGxlLmNvbS9GZWVkcy85OGQ1MjQ2MWZhNWJiYzg3OTU5M2I3
NzU0IiwiaHR0cHM6Ly9zY2ltLmV4YW1wbGUuY29tL0ZlZWRzLzVkNzYwNDUxNmIxZDA4
NjQxZDc2NzZlZTciXSwiZXZlbnRzIjp7InVybjppZXRmOnBhcmFtczpzY2ltOmV2ZW50
OmNyZWF0ZSI6eyJyZWYiOiJodHRwczovL3NjaW0uZXhhbXBsZS5jb20vVXNlcnMvNDRm
NjE0MmRmOTZiZDZhYjYxZTc1MjFkOSIsImF0dHJpYnV0ZXMiOlsiaWQiLCJuYW1lIiwi
dXNlck5hbWUiLCJwYXNzd29yZCIsImVtYWlscyJdfX19. 
</artwork>
          </figure></t>

        <t>For the purpose of a simpler example in <xref target="eventToken"/>, 
        an unsecured token was shown. When SETs are not signed or
        encrypted, the Event Receiver MUST employ other mechanisms
	such as TLS and HTTP to provide integrity, confidentiality,
	and issuer validation, as needed by the application.
        </t>
        <t>When validation (i.e. auditing), or additional transmission
        security is required, JWS signing and/or JWE encryption MAY be used. 
        To create and or validate a signed and/or encrypted SET, follow
        the instructions in Section 7 of <xref target="RFC7519"/>.</t>
      </section>
    </section>

    <section anchor="Profiles" title="Requirements for SET Profiles">
      <t>
	Profile Specifications for SETs define the syntax and semantics
	of SETs conforming to that SET profile and rules for validating those SETs.
	The syntax defined by profiling specifications includes what claims
	and event payload values are used by SETs utilizing the profile.
      </t>
      <t>
	Defining the semantics of the SET contents for SETs utilizing the profile
	is equally important.
	Possibly most important is defining the procedures used to validate the SET issuer
	and to obtain the keys controlled by the issuer that were used for
	cryptographic operations used in the JWT representing the SET.
	For instance, some profiles may define an algorithm for retrieving
	the SET issuer's keys that uses the <spanx style="verb">iss</spanx> claim value as its input.
      </t>
      <t>
	Profile Specifications MUST clearly specify the steps that a recipient of a SET
	utilizing that profile MUST perform to validate that the SET is
	both syntactically and semantically valid.
      </t>
    </section>

    <section anchor="Security" title="Security Considerations" toc="default">
      
      <section anchor="ConfidentialityIntegrity" title="Confidentiality and Integrity">

      <t>SETs may often contain sensitive information. Therefore,
      methods for distribution of events SHOULD require the use of a 
      transport-layer security mechanism when distributing events. 
      Parties MUST support TLS 1.2 <xref target="RFC5246"/> and MAY support
      additional transport-layer mechanisms meeting its security
      requirements. When using TLS, the client MUST perform a TLS/SSL server
      certificate check, per <xref target="RFC6125"/>. Implementation
      security considerations for TLS can be found in "Recommendations for
      Secure Use of TLS and DTLS" <xref target="RFC7525"/>.</t>
      
      <t>Security Events distributed through third-parties or that carry personally
      identifiable information, SHOULD be encrypted using JWE <xref target="RFC7516"/>
      or secured for confidentiality by other means.
      </t>
      <t>Security Events distributed without authentication over the channel, such
      as via TLS (<xref target="RFC5246"/> and <xref target="RFC6125"/>), 
      and/or OAuth 2.0 <xref target="RFC6749"/>, or Basic Authentication <xref target="RFC7617"/>,
      MUST be signed using JWS <xref target="RFC7515"></xref> so
      that individual events can be authenticated and validated by the 
      Event Receiver.</t>

      </section>

      <section anchor="Delivery" title="Delivery">

      <t>This specification does not define a delivery mechanism by itself.
      In addition to confidentiality and integrity (discussed above), implementers
      and Profile Specifications MUST consider the consequences of delivery 
      mechanisms that are not secure and/or not assured. For example, while
      a SET may be end-to-end secured using JWE encrypted SETs, without TLS 
      there is no assurance that the correct endpoint received the SET and 
      that it could be successfully processed.</t>
      </section>
      
      <section anchor="Sequencing" title="Sequencing">

        <t>As defined in this specification, there is no defined way to order
        multiple SETs in a sequence. Depending on the type and nature of SET
        event, order may or may not matter. For example, in provisioning, 
        event order is critical -- an object could not be modified before it
        was created. In other SET types, such as a token revocation, the order
        of SETs for revoked tokens does not matter. If however, the event was
        described as a log-in or logged-out status for a user subject, then 
        order becomes important.</t>
        
        <t>Profiling Specifications and implementers SHOULD take caution when
        using timestamps such as <spanx style="verb">iat</spanx> to define order. Distributed systems will have 
        some amount of clock-skew and thus time by itself will not guarantee order.</t>
        
        <t>Specifications profiling SET SHOULD define a mechanism for detecting
        order or sequence of events. For example, the <spanx style="verb">txn</spanx>
        claim could contain an ordered value (e.g., a counter) that the issuer defines.</t>
      </section>
      
      <section anchor="Timing" title="Timing Issues">

        <t>When SETs are delivered asynchronously and/or out-of-band with respect to
        the original action that incurred the security event, it is important
        to consider that a SET might be delivered to a Subscriber in advance
        or well behind the process that caused the event. For example, a 
        user having been required to logout and then log back in again, may
        cause a logout SET to be issued that may arrive at the same time 
        as the user-agent accesses a web site having just logged-in. If
        timing is not handled properly, the effect would be to erroneously
        treat the new user session as logged out. Profiling Specifications 
        SHOULD be careful to anticipate timing and subject selection information. 
        For example, it might be more appropriate to cancel a "session" 
        rather than a "user". Alternatively, the specification could use timestamps
        that allows new sessions to be started immediately after a stated 
        logout event time.</t>
      </section>

      <section anchor="SETsAndIDTokens" title="Distinguishing SETs from ID Tokens">
        <t>
	  Because <xref target="RFC7519"/> states that "all claims that are not understood
	  by implementations MUST be ignored", there is a consideration that 
	  a SET token might be confused with ID Token <xref target="OpenID.Core"/>
	  if a SET is mistakenly or intentionally used in a context requiring an ID Token.
	  If a SET could otherwise be interpreted as a valid ID Token
	  (because it includes the required claims for an ID Token
	  and valid issuer and audience claim values for an ID Token)
	  then that SET profile MUST require that the <spanx style="verb">exp</spanx> claim
	  not be present in the SET.
	  Because <spanx style="verb">exp</spanx> is a required claim in ID Tokens,
	  valid ID Token implementations will reject such a SET if presented as if it were an ID Token.
	</t>
	<t>
	  Excluding <spanx style="verb">exp</spanx> from SETs that
	  could otherwise be confused with ID Tokens is actually defense in depth.
	  In any OpenID Connect contexts in which an attacker could attempt to substitute a SET for an ID Token,
	  the SET would actually already be rejected as an ID Token
	  because it would not contain the correct <spanx style="verb">nonce</spanx> claim value
	  for the ID Token to be accepted in that context.
	</t>
	<t>
	  Note that the use of explicit typing, as described in <xref target="ExplicitTyping"/>,
	  will not achieve disambiguation between ID Tokens and SETs, as the ID Token validation rules
	  do not use the <spanx style="verb">typ</spanx> header parameter value.
	</t>
      </section>

      <section anchor="SETsAndATs" title="Distinguishing SETs from Access Tokens">
	<t>
	  OAuth 2.0 <xref target="RFC6749"/> defines access tokens as being opaque.
	  Nonetheless, some implementations implement access tokens as JWTs.
	  Because the structure of these JWTs is implementation-specific,
	  ensuring that a SET cannot be confused with such an access token is therefore
	  likewise, in general, implementation specific.
	  Nonetheless, it is recommended that SET profiles employ the following strategies
	  to prevent possible substitutions of SETs for access tokens
	  in contexts in which that might be possible:
	  <list style="symbols">
	    <t>
	      Prohibit use of the <spanx style="verb">exp</spanx> claim,
	      as is done to prevent ID Token confusion.
	    </t>
	    <t>
	      Where possible, use a separate <spanx style="verb">aud</spanx>
	      claim value to distinguish between the SET subscriber and the 
	      protected resource that is the audience of an access token.
	    </t>
	    <t>
	      Modify access token validation systems to check for the presence of 
	      the <spanx style="verb">events</spanx> claim as a means to detect
	      security event tokens. This is particularly useful if the same endpoint
	      may receive both types of tokens.
	    </t>
	    <t>
	      Employ explicit typing, as described in <xref target="ExplicitTyping"/>,
	      and modify access token validation systems to use the
	      <spanx style="verb">typ</spanx> header parameter value.
	    </t>
	  </list>
	</t>
      </section>

      <section anchor="SETsAndJWTs" title="Distinguishing SETs from other kinds of JWTs">
	<t>
	  JWTs are now being used in application areas beyond the identity applications
	  in which they first appeared.
	  For instance, the
	  Session Initiation Protocol (SIP) Via Header Field <xref target="RFC8055"/>
	  and
	  Personal Assertion Token (PASSporT) <xref target="I-D.ietf-stir-passport"/>
	  specifications both define JWT profiles that use mostly or completely different sets of claims
	  than are used by ID Tokens.
	  If it would otherwise be possible for an attacker to substitute a SET for one of these (or other)
	  kinds of JWTs, then the SET profile must be defined in such a way that any substituted SET
	  will result in its rejection when validated as the intended kind of JWT.
	</t>
	<t>
	  The most direct way to ensure that a SET is not confused with another kind of JWT
	  is to have the JWT validation logic reject JWTs containing an <spanx style="verb">events</spanx> claim
	  unless the JWT is intended to be a SET.
	  This approach can be employed for new systems but may not be applicable to existing systems.
	</t>
	<t>
	  Another direct way to prevent confusion is to
	  employ explicit typing, as described in <xref target="ExplicitTyping"/>,
	  and modify applicable token validation systems to use the
	  <spanx style="verb">typ</spanx> header parameter value.
	  This approach can be employed for new systems but may not be applicable to existing systems.
	</t>
	<t>
	  For many use cases, the simplest way to prevent substitution is requiring that the SET not include
	  claims that are required for the kind of JWT that might be the target of an attack.
	  For example, for <xref target="RFC8055"/>,
	  the <spanx style="verb">sip_callid</spanx> claim could be omitted
	  and for <xref target="I-D.ietf-stir-passport"/>,
	  the <spanx style="verb">orig</spanx> claim could be omitted.
	</t>
	<t>
	  In many contexts, simple measures such as these will accomplish the task,
	  should confusion otherwise even be possible.
	  Note that this topic is being explored in a more general fashion in
	  JSON Web Token Best Current Practices <xref target="I-D.sheffer-oauth-jwt-bcp"/>.
	  The proposed best practices in that draft may also be applicable
	  for particular SET profiles and use cases.
	</t>
      </section>

    </section>
    
    <section anchor="Privacy" title="Privacy Considerations">
    
      <t>If a SET needs to be retained for audit purposes, JWS MAY 
      be used to provide verification of its authenticity.</t>
      
      <t>Event Transmitters SHOULD attempt to specialize feeds so that the content
      is targeted to the specific business and protocol needs of subscribers.</t>
      
      <t>When sharing personally identifiable information or information
      that is otherwise considered confidential to affected users, Event 
      Transmitters and Receivers MUST have the appropriate legal agreements
      and user consent or terms of service in place.</t>
      
      <t>The propagation of subject identifiers can be perceived as personally
      identifiable information. Where possible, Event Transmitters and Receivers
      SHOULD devise approaches that prevent propagation -- for example, the
      passing of a hash value that requires the subscriber to already know
      the subject.</t>
    </section>

    <section anchor="IANA" title="IANA Considerations">

      <section anchor="ClaimsRegistry" title="JSON Web Token Claims Registration">
	<t>
	  This specification registers the <spanx style="verb">events</spanx> and
	  <spanx style="verb">txn</spanx> claims in the IANA
	  "JSON Web Token Claims" registry <xref target="IANA.JWT.Claims"/>
	  established by <xref target="RFC7519"/>.
	</t>

	<section anchor='ClaimsContents' title='Registry Contents'>
	  <t>
	    <?rfc subcompact="yes"?>
	    <list style='symbols'>
	      <t>
		Claim Name: <spanx style="verb">events</spanx>
	      </t>
	      <t>
		Claim Description: Security Event Object
	      </t>
	      <t>
		Change Controller: IESG
	      </t>
	      <t>
		Specification Document(s): <xref target="events"/> of [[ this specification ]]
	      <vspace blankLines="1"/></t>
	      
	      <t>
		Claim Name: <spanx style="verb">txn</spanx>
	      </t>
	      <t>
		Claim Description: Transaction Identifier
	      </t>
	      <t>
		Change Controller: IESG
	      </t>
	      <t>
		Specification Document(s): <xref target="events"/> of [[ this specification ]]
	      </t>
	    </list>
	  </t>
	</section>
	<?rfc subcompact="no"?>
      </section>

      <section title="Media Type Registration" anchor="MediaReg">
	<section title="Registry Contents" anchor="MediaContents">
	  <t>
	    This section registers the <spanx style="verb">application/secevent+jwt</spanx>
	    media type <xref target="RFC2046"/>
	    in the "Media Types" registry <xref target="IANA.MediaTypes"/>
	    in the manner described in <xref target="RFC6838"/>,
	    which can be used to indicate that the content is a SET.
	  </t>
	  <t> <?rfc subcompact="yes"?>
	    <list style="symbols">
	      <t>
		Type name: application
	      </t>
	      <t>
		Subtype name: secevent+jwt
	      </t>
	      <t>
		Required parameters: n/a
	      </t>
	      <t>
		Optional parameters: n/a
	      </t>
	      <t>
		Encoding considerations: 8bit;
		A SET is a JWT;
		JWT values are encoded as a
		series of base64url-encoded values (some of which may be the
		empty string) separated by period ('.') characters.
	      </t>
	      <t>
		Security considerations: See the Security Considerations section of [[ this specification ]]
	      </t>
	      <t>
		Interoperability considerations: n/a
	      </t>
	      <t>
		Published specification: <xref target="ExplicitTyping"/> of [[ this specification ]]
	      </t>
	      <t>
		Applications that use this media type:
		TBD
	      </t>
	      <t>
		Fragment identifier considerations: n/a
	      </t>
	      <t>
		Additional information:<list style="empty">
	        <t>Magic number(s): n/a</t>
		<t>File extension(s): n/a</t>
		<t>Macintosh file type code(s): n/a </t></list>
<vspace/>
	      </t>
	      <t>
		Person &amp; email address to contact for further information:
<vspace/>
		Michael B.&nbsp;Jones, mbj@microsoft.com
	      </t>
	      <t>
		Intended usage: COMMON
	      </t>
	      <t>
		Restrictions on usage: none
	      </t>
	      <t>
		Author: Michael B.&nbsp;Jones, mbj@microsoft.com
	      </t>
	      <t>
		Change controller: IESG
	      </t>
	      <t>
		Provisional registration? No
	      </t>
	    </list>
	  </t>
	</section>
	<?rfc subcompact="no"?>
      </section>
      
    </section>

  </middle>

  <back>
    <references title="Normative References">

    <!-- 
      <reference anchor="idevent-subscription">
        
        <front>
          <title>Identity Event Subscription Protocol (work in progress)</title>
          <author fullname="Phil Hunt"><organization>Oracle Corporation</organization></author>
          <date/>
        </front>  
      </reference>
       -->
       
      <?rfc include='http://xml2rfc.tools.ietf.org/public/rfc/bibxml/reference.RFC.2119.xml' ?><!-- Keywords -->
      <?rfc include='http://xml2rfc.tools.ietf.org/public/rfc/bibxml/reference.RFC.3986.xml'?><!-- URIs -->
      <?rfc include='http://xml2rfc.tools.ietf.org/public/rfc/bibxml/reference.RFC.5246.xml'?><!-- TLS 1.2 -->
      <?rfc include='http://xml2rfc.tools.ietf.org/public/rfc/bibxml/reference.RFC.6125.xml'?><!-- TLS Cert-->
      <?rfc include='http://xml2rfc.tools.ietf.org/public/rfc/bibxml/reference.RFC.6749.xml'?><!-- OAuth 2.0 -->
      <?rfc include='http://xml2rfc.tools.ietf.org/public/rfc/bibxml/reference.RFC.7519.xml'?><!-- JWT -->
      <?rfc include='http://xml2rfc.tools.ietf.org/public/rfc/bibxml/reference.RFC.7525.xml'?><!-- TLS BCP -->
      <?rfc include='http://xml2rfc.tools.ietf.org/public/rfc/bibxml/reference.RFC.7617.xml'?><!-- Basic Auth -->

      <reference anchor="IANA.JWT.Claims" target="http://www.iana.org/assignments/jwt">
        <front>
          <title>JSON Web Token Claims</title>
          <author>
            <organization>IANA</organization>
          </author>
	  <date/>
        </front>
      </reference>

      <reference anchor="IANA.MediaTypes" target="http://www.iana.org/assignments/media-types">
        <front>
          <title>Media Types</title>
          <author>
            <organization>IANA</organization>
          </author>
	  <date/>
        </front>
      </reference>

    </references>
 
    <references title="Informative References">
      <?rfc include='http://xml2rfc.tools.ietf.org/public/rfc/bibxml/reference.RFC.2046.xml' ?><!-- MIME -->
      <?rfc include='http://xml2rfc.tools.ietf.org/public/rfc/bibxml/reference.RFC.6838.xml' ?><!-- MIME Registration -->
      <?rfc include='http://xml2rfc.tools.ietf.org/public/rfc/bibxml/reference.RFC.7009.xml'?><!-- OAuth Revocation -->
      <?rfc include='http://xml2rfc.tools.ietf.org/public/rfc/bibxml/reference.RFC.7515.xml'?><!-- JWS -->
      <?rfc include='http://xml2rfc.tools.ietf.org/public/rfc/bibxml/reference.RFC.7516.xml'?><!-- JWE -->
      <?rfc include='http://xml2rfc.tools.ietf.org/public/rfc/bibxml/reference.RFC.7517.xml'?><!-- JWK -->
      <?rfc include='http://xml2rfc.tools.ietf.org/public/rfc/bibxml/reference.RFC.7644.xml'?><!-- SCIM Protocol -->
      <?rfc include='http://xml2rfc.tools.ietf.org/public/rfc/bibxml/reference.RFC.8055.xml'?><!-- SIP Via Header -->

      <?rfc include="http://xml2rfc.tools.ietf.org/public/rfc/bibxml3/reference.I-D.draft-ietf-stir-passport-11.xml" ?>
      <?rfc include="http://xml2rfc.tools.ietf.org/public/rfc/bibxml3/reference.I-D.draft-sheffer-oauth-jwt-bcp-00.xml" ?>

       
      <reference anchor="OpenID.Core" target="http://openid.net/specs/openid-connect-core-1_0.html">
        <front>
          <title>OpenID Connect Core 1.0</title>
 
          <author fullname="Nat Sakimura" initials="N." surname="Sakimura">
            <organization abbrev="NRI">Nomura Research Institute, Ltd.</organization>
          </author>
 
          <author fullname="John Bradley" initials="J." surname="Bradley">
            <organization abbrev="Ping Identity">Ping Identity</organization>
          </author>
 
          <author fullname="Michael B. Jones" initials="M.B." surname="Jones">
            <organization abbrev="Microsoft">Microsoft</organization>
          </author>
 
          <author fullname="Breno de Medeiros" initials="B." surname="de Medeiros">
            <organization abbrev="Google">Google</organization>
          </author>
 
                <author fullname="Chuck Mortimore" initials="C." surname="Mortimore">
                  <organization abbrev="Salesforce">Salesforce</organization>
                </author>
 
          <date day="8" month="November" year="2014"/>
        </front>
      </reference>
      <reference anchor="saml-core-2.0">
        <front>
          <title>Assertions and Protocols for the OASIS Security Assertion Markup Language (SAML) V2.0</title>
          <author fullname="Scott Cantor et al"><organization>Internet2</organization></author>
          <date day="15" month="March" year="2005"/>
        </front>
        <format type="PDF" target="http://docs.oasis-open.org/security/saml/v2.0/saml-core-2.0-os.pdf"/>
      </reference>
     
 <!-- 
      <reference anchor="RISC">
        <front>
          <title>OpenID Risk and Incident Sharing and Coordination (RISC) Working Group</title>
          <author> <organization>OpenID Foundation</organization></author>
          <date/>
        </front>
      </reference>

      <reference anchor="HEART" target="http://openid.net/wg/heart/">
        <front>
          <title>OpenID Health Relationship Trust (HEART) Working Group</title>
          <author> <organization>OpenID Foundation</organization></author>
          <date/>
        </front>
      </reference>
      
       -->

    </references>

    <!-- <section anchor="Contributors" title="Contributors"/> Uncomment if and when this section is non-empty -->

    <section anchor="Acknowledgments" title="Acknowledgments">
      <t>The editors would like to thank the members of the IETF SCIM working group, which 
      began discussions of provisioning events starting with draft-hunt-scim-notify-00 in 2015.</t>
      <t>The editors would like to thank the participants in the IETF id-event
      mailing list and related working groups for their support of this specification.</t>
    </section>

    <section anchor="History" title="Change Log">
      <t>From the original draft-hunt-idevent-token:</t>
      <t>Draft 01 - PH - Renamed eventUris to events</t>
      <t>Draft 00 - PH - First Draft</t>
      <t>Draft 01 - PH - Fixed some alignment issues with JWT. Remove event type attribute.</t>
      <t>Draft 02 - PH - Renamed to Security Events, removed questions, clarified examples and intro text, and added security and privacy section.</t>
      <t>Draft 03 - PH <list style="symboles">
        <t>General edit corrections from Sarah Squire</t>
        <t>Changed "event" term to "SET"</t>
        <t>Corrected author organization for William Denniss to Google</t>
        <t>Changed definition of SET to be 2 parts, an envelope and 1 or more payloads.</t>
        <t>Clarified that the intent is to express a single event with optional extensions only.</t>
      </list>
                  - mbj - Registered <spanx style="verb">events</spanx> claim, and proof-reading corrections.</t> 
      <t>Draft 04 - PH - <list style="symbols">
        <t>Re-added the "sub" claim with clarifications that any SET type may use it.</t>
        <t>Added additional clarification on the use of envelope vs. payload attributes</t>
        <t>Added security consideration for event timing.</t>
        <t>Switched use of "attribute" to "claim" for consistency.</t>
        <t>Revised examples to put "sub" claim back in the top level.</t>
        <t>Added clarification that SETs typically do not use "exp".</t>
        <t>Added security consideration for distinguishing Access Tokens and SETs.</t>
      </list></t>
      
      <t>Draft 05 - PH - Fixed find/replace error that resulted in claim being spelled claimc</t>
      <t>Draft 06 - PH - <list style="symbols">
        <t>Corrected typos</t>
        <t>New txn claim</t>
        <t>New security considerations Sequencing and Timing Issues</t>
      </list></t>
      <t>
	Draft 07 -
	<list style="symbols">
	  <t>PH - Moved payload objects to be values of event URI attributes, per discussion.</t>
	  <t>mbj - Applied terminology consistency and grammar cleanups.</t>
	</list>
      </t>
      <t>Draft 08 - PH - <list style="symbols">
        <t>Added clarification to status of examples</t>
        <t>Changed from primary vs. extension to state that multiple 
        events may be expressed, some of which may or may not
        be considered extensions of others (which is for the subscriber 
        or profiling specifications to determine).</t>
        <t>Other editorial changes suggested by Yaron </t>
      </list></t>
      <t><vspace/>From draft-ietf-secevent-token:</t>
      <t>Draft 00 - PH - First WG Draft based on draft-hunt-idevent-token</t>
      <t>Draft 01 - PH - Changes as follows:<list style="symbols">
        <t>Changed terminology away from pub-sub to transmitter/receiver based on WG feedback</t>
        <t>Cleaned up/removed some text about extensions (now only used as example)</t>
        <t>Clarify purpose of spec vs. future profiling specs that define actual events</t>
      </list></t>
      <t>
	Draft 02 - Changes are as follows:
	<list style="symbols">
	  <t>
	    mbj -
	    Added the Requirements for SET Profiles section.
	  </t>
	  <t>
	    mbj -
	    Expanded the Security Considerations section to describe
	    how to prevent confusion of SETs with ID Tokens, access tokens,
	    and other kinds of JWTs.
	  </t>
	  <t>
	    mbj -
	    Registered the <spanx style="verb">application/secevent+jwt</spanx> media type
	    and defined how to use it for explicit typing of SETs.
	  </t>
	  <t>
	    mbj -
	    Clarified the misleading statement that used to say that
	    a SET conveys a single security event.
	  </t>
	  <t>
	    mbj -
	    Added a note explicitly acknowledging that some SET profiles
	    may choose to convey event subject information in the event payload.
	  </t>
	  <t>
	    PH -
	    Corrected encoded claim example on page 10.
	  </t>
	  <t>
	    mbj -
	    Applied grammar corrections.
	  </t>
	</list>
      </t>
    </section>
  </back>
</rfc>
