[Openid-specs-risc] Request for vote on RISC Implementer's Draft
Marius Scurtescu
mscurtescu at google.com
Wed Apr 25 01:56:37 UTC 2018
Comments inline...
On Mon, Apr 23, 2018 at 5:15 PM, Mike Jones via Openid-specs-risc <
openid-specs-risc at lists.openid.net> wrote:
> Based a quick skim wearing my foundation secretary hat, I need the
> following things to get these ready to post:
>
> - Rename risc-secevent to openid-risc-secevent-1_0
>
> renamed to openid-risc-profile-1_0, see bellow
>
> -
> - Rename risc-event-types to openid-risc-event-types-1_0
>
> done
>
> -
> - Rename oauth-event-types to oauth-event-types_1_0
>
> done
>
> -
> - Provide the openid-risc-profile-1_0 to also post
>
> sorry about the confusion, that was risc-secevent, renamed to
openid-risc-profile-1_0
>
> -
> - Add “1.0” to the end of each of the spec titles.
>
> done
>
> -
> - Optionally, also prefix the first two spec titles with “OpenID”,
> such as “OpenID RISC Event Types 1.0”.
>
> done
>
> -
> - Include a URL for any specification references. For instance, the
> RISC-PROFILE should include the URL “http://openid.net/specs/
> openid-risc-profile-1_0.html”.
>
> done
>
> -
> - Include dates and authors in all specification references – both for
> the WG specs and for IETF specs. For instance, the SET reference is
> missing the data and author information (and the URL).
>
> done
>
> -
> - Run a spelling and grammar check. For instance, I’m sure you didn’t
> mean to say “This document defines the RTISC Event Types”.
>
> done
>
> -
> - Provide a copy of the primary source documents for each of the
> specifications (the .xml files) as well as the .txt and .html output from
> xml2rfc that you intend for me to post at http:/openid.net/specs/. If
> you’re using MarkDown, please also provide me the .md files and the
> procedure you use to convert the .md files to .xml. I may verify that they
> build correctly.
>
> Attached
Thanks a lot Mike!
>
> -
>
>
>
> -- Mike
>
>
>
> *From:* Adam Dawes <adawes at google.com>
> *Sent:* Monday, April 23, 2018 3:49 PM
> *To:* Mike Jones <Michael.Jones at microsoft.com>
> *Cc:* Dick Hardt via Openid-specs-risc <openid-specs-risc at lists.openid.net
> >
> *Subject:* Request for vote on RISC Implementer's Draft
>
>
>
> Hi Mike,
>
>
>
> This is a formal request from the RISC working group to call a vote to
> make the following specs implementers draft:
>
>
>
> RISC secevents
> <https://bitbucket.org/openid/risc/src/98ade8086b82c080e1bcd2060252c20116b44009/risc-secevent.txt?at=master&fileviewer=file-view-default>
>
> RISC event types
> <https://bitbucket.org/openid/risc/src/98ade8086b82c080e1bcd2060252c20116b44009/risc-event-types.txt?at=master&fileviewer=file-view-default>
>
> OAuth event types
> <https://bitbucket.org/openid/risc/src/98ade8086b82c080e1bcd2060252c20116b44009/oauth-event-types.txt?at=master&fileviewer=file-view-default>
>
>
>
> As per our conversation last week, you said that you would review the
> drafts this week for proper formatting/references/etc and would likely come
> back with changes before issuing the specs for a vote.
>
>
>
> The group wanted to take next week's call, 4/30 @9:30, to run through the
> errata changes and lock them down. Would be ideal if you can attend as well.
>
>
>
> Please let me know if you have any other questions.
>
>
>
> thanks,
>
> AD
>
> --
>
> Adam Dawes | Sr. Product Manager | adawes at google.com | +1 650-214-2410
>
>
>
> _______________________________________________
> Openid-specs-risc mailing list
> Openid-specs-risc at lists.openid.net
> http://lists.openid.net/mailman/listinfo/openid-specs-risc
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openid.net/pipermail/openid-specs-risc/attachments/20180424/35f7c3fa/attachment-0004.html>
-------------- next part --------------
M. Scurtescu
Google
A. Backman
Amazon
P. Hunt
Oracle
J. Bradley
Yubico
April 24, 2018
OAuth Event Types 1.0
oauth-event-types-1_0
Abstract
This document defines the OAuth Event Types. Event Types are
introduced and defined in Security Event Token (SET) [SET].
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 1
1.1. Notational Conventions . . . . . . . . . . . . . . . . . 2
2. OAuth Specific Subject Identifier Types . . . . . . . . . . . 2
2.1. Token Subject Identifier Type . . . . . . . . . . . . . . 2
2.2. Client Subject Identifier Type . . . . . . . . . . . . . 3
3. Event Types . . . . . . . . . . . . . . . . . . . . . . . . . 3
3.1. Token Issued . . . . . . . . . . . . . . . . . . . . . . 3
3.2. Token Revoked . . . . . . . . . . . . . . . . . . . . . . 4
3.3. Tokens Revoked . . . . . . . . . . . . . . . . . . . . . 6
3.4. Client Disabled . . . . . . . . . . . . . . . . . . . . . 7
3.5. Client Enabled . . . . . . . . . . . . . . . . . . . . . 8
3.6. Client Credential Changed . . . . . . . . . . . . . . . . 8
4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8
4.1. Subject Identifier Type Registry . . . . . . . . . . . . 8
5. Normative References . . . . . . . . . . . . . . . . . . . . 9
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 9
1. Introduction
This specification is based on RISC Profile [RISC-PROFILE] and uses
the subject identifiers defined there.
The "aud" claim identifies the OAuth 2 client and its value SHOULD be
the OAuth 2 [RFC6749] client id.
Scurtescu, et al. Expires October 26, 2018 [Page 1]
oauth-event-types April 2018
1.1. Notational Conventions
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in BCP
14 [RFC2119] [RFC8174] when, and only when, they appear in all
capitals, as shown here.
2. OAuth Specific Subject Identifier Types
This section defines OAuth specific Subject Identifier Types.
Subject identifiers are defined in Section 2 of [RISC-PROFILE].
2.1. Token Subject Identifier Type
A Token Subject Identifier Type describes an OAuth 2 token subject
and it is identified by the name "oauth_token".
Subject Identifiers of this type MUST contain the following claims:
o token_type - required, describes the OAuth 2 token type. Possible
values:
* access_token
* authorization_code
* refresh_token
o token_identifier_alg - required, describes how is the token string
in the "token" attribute to be interpreted. Possible values:
* plain - plain token string
* prefix - token string prefix
* hash_* - token string hash, actual hash algorithms added as a
suffix. TODO: create individual values for each hash
algorithm.
o token - required, the token identifier, as described by
"token_identifier_alg".
Scurtescu, et al. Expires October 26, 2018 [Page 2]
oauth-event-types April 2018
"subject": {
"subject_type": "oauth_token",
"token_type": "refresh_token",
"token_identifier_alg": "plain",
"token": "7265667265736820746F6B656E20737472696E67"
}
Figure 1: Example: Token Subject Identifier Type
2.2. Client Subject Identifier Type
A Client Subject Identifier Type describes an OAuth 2 client subject
and it is identified by the name "oauth_client".
Subjects identifiers of this type MUST contain the following claim:
o client_id - required, the OAuth 2 client id.
"subject": {
"subject_type": "oauth_client",
"client_id": "636C69656E74206964"
}
Figure 2: Example: Client Subject Identifier Type
3. Event Types
The base URI for OAuth Event Types is:
https://schemas.openid.net/secevent/oauth/event-type/
3.1. Token Issued
Event Type URI:
https://schemas.openid.net/secevent/oauth/event-type/token-issued
Token Issued signals that a new token was issued.
Attributes:
o subject - required, a Subjectect Identifier as defined by
Section 2.1 that identifies the token.
o token_subject - optional, a Subject Identifier as defined by
Section 2.1 of [RISC-PROFILE] that identifies the account
associated with the token.
o TODO: OAuth flow and endpoints involved in the process? For
example: redirect_uri, response_type, origin?
Scurtescu, et al. Expires October 26, 2018 [Page 3]
oauth-event-types April 2018
The token SHOULD be uniquely identified by the provided attributes,
either by "subject" alone or by "subject" in combination with
"token_subject". The token is unique in the context of a given
Transmitter and not globally unique. TODO: do we need a "iss"
attribute for the "oauth_token" Subject Type?
{
"iss": "https://idp.example.com/",
"jti": "756E69717565206964656E746966696572",
"iat": 1508184845,
"aud": "636C69656E745F6964",
"events": {
"https://schemas.openid.net/secevent/oauth/event-type/\
token-issued": {
"subject": {
"subject_type": "oauth_token",
"token_type": "refresh_token",
"token_identifier_alg": "token_string",
"token": "7265667265736820746F6B656E20737472696E67"
},
"token_subject" {
"subject_type": "iss-sub",
"iss": "https://idp.example.com/",
"sub": "75736572206964"
}
}
}
}
_(the event type URI is wrapped, the backslash is the continuation
character)_
Figure 3: Example: Token Issued
3.2. Token Revoked
Event Type URI:
https://schemas.openid.net/secevent/oauth/event-type/token-revoked
Token Revoked signals that the token identified by this event was
revoked.
Attributes:
o subject - required, a Subjectect Identifier as defined by
Section 2.1 that identifies the token.
Scurtescu, et al. Expires October 26, 2018 [Page 4]
oauth-event-types April 2018
o token_subject - optional, a Subject Identifier as defined by
Section 2.1 of [RISC-PROFILE] that identifies the account
associated with the token.
o reason - optional, the reason why the token was revoked. Possible
values:
* inactive - token was revoked by the issuer because of
inactivity
* too_many - token was revoked by the issuer because an internal
limit was reached
* api - token was revoked through an API call like [RFC7009]
* user - token was revoked explicitly by the user
* issuer - token was revoked by the issuer for some other reason
* TODO: add extension mechanism (either through URIs or IANA
registry)
The token SHOULD be uniquely identified by the provided attributes,
either by "subject" alone or by "subject" in combination with
"token_subject". The token is unique in the context of a given
Transmitter and not globally unique. TODO: do we need a "iss"
attribute for the "oauth_token" Subject Type?
Scurtescu, et al. Expires October 26, 2018 [Page 5]
oauth-event-types April 2018
{
"iss": "https://idp.example.com/",
"jti": "756E69717565206964656E746966696572",
"iat": 1508184845,
"aud": "636C69656E745F6964",
"events": {
"https://schemas.openid.net/secevent/oauth/event-type/\
token-revoked": {
"subject": {
"subject_type": "oauth_token",
"token_type": "refresh_token",
"token_identifier_alg": "token_string",
"token": "7265667265736820746F6B656E20737472696E67"
},
"token_subject" {
"subject_type": "iss-sub",
"iss": "https://idp.example.com/",
"sub": "75736572206964"
},
"reason": "inactive"
}
}
}
_(the event type URI is wrapped, the backslash is the continuation
character)_
Figure 4: Example: Token Revoked
3.3. Tokens Revoked
Event Type URI:
https://schemas.openid.net/secevent/oauth/event-type/tokens-revoked
Tokens Revoked signals that all tokens issued for the account
identified by the subject have been revoked.
Attributes:
o subject - optional, a Subject Identifier as defined by Section 2.1
of [RISC-PROFILE] that identifies the account associated with the
token.
o reason - optional, the reason why all the tokens were revoked.
Possible values:
* user - all tokens were revoked explicitly by the user
Scurtescu, et al. Expires October 26, 2018 [Page 6]
oauth-event-types April 2018
* issuer - all tokens were revoked by the issuer
* TODO: add extension mechanism (either through URIs or IANA
registry)
{
"iss": "https://idp.example.com/",
"jti": "756E69717565206964656E746966696572",
"iat": 1508184845,
"aud": "636C69656E745F6964",
"events": {
"https://schemas.openid.net/secevent/oauth/event-type/\
tokens-revoked": {
"subject": {
"subject_type": "iss-sub",
"iss": "https://idp.example.com/",
"sub": "7375626A656374",
},
}
}
}
_(the event type URI is wrapped, the backslash is the continuation
character)_
Figure 5: Example: Tokens Revoked
3.4. Client Disabled
Event Type URI:
https://schemas.openid.net/secevent/oauth/event-type/client-disabled
Client Disabled signals that the client identified by the "aud" claim
has been disabled. The client may be enabled (Section 3.5) in the
future.
Attributes: TODO use client subject identifier
Scurtescu, et al. Expires October 26, 2018 [Page 7]
oauth-event-types April 2018
{
"iss": "https://idp.example.com/",
"jti": "756E69717565206964656E746966696572",
"iat": 1508184845,
"aud": "636C69656E745F6964",
"events": {
"https://schemas.openid.net/secevent/oauth/event-type/\
client-disabled": {}
}
}
_(the event type URI is wrapped, the backslash is the continuation
character)_
Figure 6: Example: Client Disabled
3.5. Client Enabled
Event Type URI:
https://schemas.openid.net/secevent/oauth/event-type/client-enabled
Client Enabled signals that the client identified by the "aud" claim
has been enabled.
Attributes: TODO use client subject identifier
3.6. Client Credential Changed
Event Type URI:
https://schemas.openid.net/secevent/oauth/event-type/client-
credential-changed
Client Credential Changed signals that one of the credentials of the
client identified by the "aud" claim has changed. For example the
client secret has changed.
Attributes: TODO use client subject identifier
4. IANA Considerations
4.1. Subject Identifier Type Registry
TODO: register "oauth_token" and "oauth_client" subject identifier
types.
Scurtescu, et al. Expires October 26, 2018 [Page 8]
oauth-event-types April 2018
5. Normative References
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997, <https://www.rfc-
editor.org/info/rfc2119>.
[RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework",
RFC 6749, DOI 10.17487/RFC6749, October 2012,
<https://www.rfc-editor.org/info/rfc6749>.
[RFC7009] Lodderstedt, T., Ed., Dronia, S., and M. Scurtescu, "OAuth
2.0 Token Revocation", RFC 7009, DOI 10.17487/RFC7009,
August 2013, <https://www.rfc-editor.org/info/rfc7009>.
[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
May 2017, <https://www.rfc-editor.org/info/rfc8174>.
[RISC-PROFILE]
Scurtescu, M., Backman, A., and J. Bradley, "OpenID RISC
Profile of IETF Security Events 1.0", April 2018,
<http://openid.net/specs/openid-risc-profile-1_0.html>.
[SET] Hunt, P., Ed., Jones, M., Denniss, W., and M. Ansari,
"Security Event Token (SET)", April 2018,
<https://tools.ietf.org/html/draft-ietf-secevent-token-
09>.
Authors' Addresses
Marius Scurtescu
Google
Email: mscurtescu at google.com
Annabelle Backman
Amazon
Email: richanna at amazon.com
Phil Hunt
Oracle Corporation
Email: phil.hunt at yahoo.com
Scurtescu, et al. Expires October 26, 2018 [Page 9]
oauth-event-types April 2018
John Bradley
Yubico
Email: secevemt at ve7jtb.com
Scurtescu, et al. Expires October 26, 2018 [Page 10]
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openid.net/pipermail/openid-specs-risc/attachments/20180424/35f7c3fa/attachment-0005.html>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: oauth-event-types-1_0.xml
Type: text/xml
Size: 20674 bytes
Desc: not available
URL: <http://lists.openid.net/pipermail/openid-specs-risc/attachments/20180424/35f7c3fa/attachment-0003.xml>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openid.net/pipermail/openid-specs-risc/attachments/20180424/35f7c3fa/attachment-0006.html>
-------------- next part --------------
M. Scurtescu
Google
A. Backman
Amazon
P. Hunt
Oracle
J. Bradley
Yubico
April 24, 2018
OpenID RISC Event Types 1.0
openid-risc-event-types-1_0
Abstract
This document defines the RISC Event Types. Event Types are
introduced and defined in Security Event Token (SET) [SET].
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 1
1.1. Notational Conventions . . . . . . . . . . . . . . . . . 2
2. Event Types . . . . . . . . . . . . . . . . . . . . . . . . . 2
2.1. Account Credential Change Required . . . . . . . . . . . 2
2.2. Account Purged . . . . . . . . . . . . . . . . . . . . . 3
2.3. Account Disabled . . . . . . . . . . . . . . . . . . . . 3
2.4. Account Enabled . . . . . . . . . . . . . . . . . . . . . 4
2.5. Identifier Changed . . . . . . . . . . . . . . . . . . . 4
2.6. Identifier Recycled . . . . . . . . . . . . . . . . . . . 5
2.7. Opt Out . . . . . . . . . . . . . . . . . . . . . . . . . 6
2.7.1. Opt In . . . . . . . . . . . . . . . . . . . . . . . 7
2.7.2. Opt Out Initiated . . . . . . . . . . . . . . . . . . 7
2.7.3. Opt Out Cancelled . . . . . . . . . . . . . . . . . . 8
2.7.4. Opt Out Effective . . . . . . . . . . . . . . . . . . 8
2.8. Recovery Activated . . . . . . . . . . . . . . . . . . . 8
2.9. Recovery Information Changed . . . . . . . . . . . . . . 8
2.10. Sessions Revoked . . . . . . . . . . . . . . . . . . . . 9
3. Normative References . . . . . . . . . . . . . . . . . . . . 9
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 9
1. Introduction
This specification is based on RISC Profile [RISC-PROFILE] and uses
the subject identifiers defined there.
Scurtescu, et al. Expires October 26, 2018 [Page 1]
openid-risc-event-types April 2018
1.1. Notational Conventions
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in BCP
14 [RFC2119] [RFC8174] when, and only when, they appear in all
capitals, as shown here.
2. Event Types
The base URI for RISC event types is:
https://schemas.openid.net/secevent/risc/event-type/
2.1. Account Credential Change Required
Event Type URI:
https://schemas.openid.net/secevent/risc/event-type/account-
credential-change-required
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.
Attributes: none
{
"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",
}
}
}
}
_(the event type URI is wrapped, the backslash is the continuation
character)_
Figure 1: Example: Account Credential Change Required
Scurtescu, et al. Expires October 26, 2018 [Page 2]
openid-risc-event-types April 2018
2.2. Account Purged
Event Type URI:
https://schemas.openid.net/secevent/risc/event-type/account-purged
Account Purged signals that the account identified by the subject has
been permanently deleted.
Attributes: none
2.3. Account Disabled
Event Type URI:
https://schemas.openid.net/secevent/risc/event-type/account-disabled
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 "reason" attribute described
below. The account may be enabled (Section 2.4) in the future.
Attributes:
o reason - optional, describes why was the account disabled.
Possible values:
* hijacking
* bulk-account
Scurtescu, et al. Expires October 26, 2018 [Page 3]
openid-risc-event-types April 2018
{
"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",
}
}
}
_(the event type URI is wrapped, the backslash is the continuation
character)_
Figure 2: Example: Account Disabled
2.4. Account Enabled
Event Type URI:
https://schemas.openid.net/secevent/risc/event-type/account-enabled
Account Enabled signals that the account identified by the subject
has been enabled.
Attributes: none
2.5. Identifier Changed
Event Type URI:
https://schemas.openid.net/secevent/risc/event-type/identifier-
changed
Identifier Changed signals that the identifier specified in the
subject has changed. The subject type MUST be either "email" or
"phone" and it MUST specify the old value.
This event SHOULD be issued only by the provider that is
authoritative over the identifier. For example, if the person that
owns "john.doe at example.com" goes through a name change and wants the
new "john.row at example.com" email then *only* the email provider
Scurtescu, et al. Expires October 26, 2018 [Page 4]
openid-risc-event-types April 2018
"example.com" SHOULD issue an Identifier Changed event as shown in
the example below.
If an identifier used as a username or recovery option is changed, at
a provider that is not authoritative over that identifier, then
Recovery Information Changed (Section 2.9) SHOULD be used instead.
Attributes:
o new-value - optional, the new value of the identifier.
{
"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 at example.com",
},
"new-value": "john.roe at example.com",
}
}
}
The "foo at example.com" email changed to "bar at example.com". _(the
event type URI is wrapped, the backslash is the continuation
character)_
Figure 3: Example: Identifier Changed
2.6. Identifier Recycled
Event Type URI:
https://schemas.openid.net/secevent/risc/event-type/identifier-
recycled
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 "email" or "phone".
Attributes: none
Scurtescu, et al. Expires October 26, 2018 [Page 5]
openid-risc-event-types April 2018
{
"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 at example.com",
}
}
}
}
The 'foo at example.com' email address was recycled. _(the event type
URI is wrapped, the backslash is the continuation character)_
Figure 4: Example: Identifier Recycled
2.7. Opt Out
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:
1. opt-in - the account is participating in RISC event exchange.
2. 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.
3. opt-out - the account is NOT participating in RISC event
exchange.
Scurtescu, et al. Expires October 26, 2018 [Page 6]
openid-risc-event-types April 2018
State changes trigger Opt-Out Events as represented bellow:
+--------+ opt-out-initiated +-------------------+
| +---------------------> |
| opt-in | | opt-out-initiated |
| | pt-out-cancelled | |
| <---------------------+ |
+---^----+ +----------+--------+
| |
| opt-in | opt-out-effective
| |
| +----------V--------+
| | |
+--------------------------| opt-out |
| |
+-------------------+
Figure 5: Opt-Out States and Opt-Out Events
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.
2.7.1. Opt In
Event Type URI:
https://schemas.openid.net/secevent/risc/event-type/opt-in
Opt In signals that the account identified by the subject opted into
RISC event exchanges. The account is in the "opt-in" state.
Attributes: none
2.7.2. Opt Out Initiated
Event Type URI:
https://schemas.openid.net/secevent/risc/event-type/opt-out-initiated
Opt Out Initiated signals that the account identified by the subject
initiated to opt out from RISC event exchanges. The account is in
the "opt-out-initiated" state.
Attributes: none
Scurtescu, et al. Expires October 26, 2018 [Page 7]
openid-risc-event-types April 2018
2.7.3. Opt Out Cancelled
Event Type URI:
https://schemas.openid.net/secevent/risc/event-type/opt-out-cancelled
Opt Out Cancelled signals that the account identified by the subject
cancelled the opt out from RISC event exchanges. The account is in
the "opt-in" state.
Attributes: none
2.7.4. Opt Out Effective
Event Type URI:
https://schemas.openid.net/secevent/risc/event-type/opt-out-effective
Opt Out Effective signals that the account identified by the subject
was effectively opted out from RISC event exchanges. The account is
in the "opt-out" state.
Attributes: none
2.8. Recovery Activated
Event Type URI:
https://schemas.openid.net/secevent/risc/event-type/recovery-
activated
Recovery Activated signals that the account identified by the subject
activated a recovery flow.
Attributes: none
2.9. Recovery Information Changed
Event Type URI:
https://schemas.openid.net/secevent/risc/event-type/recovery-
information-changed
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.
Attributes: none
Scurtescu, et al. Expires October 26, 2018 [Page 8]
openid-risc-event-types April 2018
2.10. Sessions Revoked
Event Type URI:
https://schemas.openid.net/secevent/risc/event-type/sessions-revoked
Sessions Revoked signals that all the sessions for the account
identified by the subject have been revoked.
Attributes: none
3. Normative References
[JSON] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data
Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March
2014, <https://www.rfc-editor.org/info/rfc7159>.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997, <https://www.rfc-
editor.org/info/rfc2119>.
[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
May 2017, <https://www.rfc-editor.org/info/rfc8174>.
[RISC-PROFILE]
Scurtescu, M., Backman, A., and J. Bradley, "OpenID RISC
Profile of IETF Security Events 1.0", April 2018,
<http://openid.net/specs/openid-risc-profile-1_0.html>.
[SET] Hunt, P., Ed., Jones, M., Denniss, W., and M. Ansari,
"Security Event Token (SET)", April 2018,
<https://tools.ietf.org/html/draft-ietf-secevent-token-
09>.
Authors' Addresses
Marius Scurtescu
Google
Email: mscurtescu at google.com
Annabelle Backman
Amazon
Email: richanna at amazon.com
Scurtescu, et al. Expires October 26, 2018 [Page 9]
openid-risc-event-types April 2018
Phil Hunt
Oracle Corporation
Email: phil.hunt at yahoo.com
John Bradley
Yubico
Email: secevemt at ve7jtb.com
Scurtescu, et al. Expires October 26, 2018 [Page 10]
-------------- next part --------------
A non-text attachment was scrubbed...
Name: openid-risc-event-types-1_0.xml
Type: text/xml
Size: 19603 bytes
Desc: not available
URL: <http://lists.openid.net/pipermail/openid-specs-risc/attachments/20180424/35f7c3fa/attachment-0004.xml>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openid.net/pipermail/openid-specs-risc/attachments/20180424/35f7c3fa/attachment-0007.html>
-------------- next part --------------
M. Scurtescu
Google
A. Backman
Amazon
J. Bradley
Yubico
April 24, 2018
OpenID RISC Profile of IETF Security Events 1.0
openid-risc-profile-1_0
Abstract
This spec is a general profile for IETF Security Events [1] and it
defines:
o Subject Identifiers
o a configuration information discovery method for Transmitters
o a Management API for Event Streams
This spec also directly profiles several IETF Security Events drafts:
o Security Event Token (SET) [SET]
o Push-Based SET Token Delivery Using HTTP [DELIVERYPUSH]
o Poll-Based SET Token Delivery Using HTTP [DELIVERYPOLL]
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1. Notational Conventions . . . . . . . . . . . . . . . . . 3
2. Subject Identifiers . . . . . . . . . . . . . . . . . . . . . 3
2.1. Subject Identifier Types . . . . . . . . . . . . . . . . 4
2.1.1. Email Subject Identifier Type . . . . . . . . . . . . 4
2.1.2. Phone Number Subject Identifier Type . . . . . . . . 5
2.1.3. Issuer and Subject Subject Identifier Type . . . . . 5
2.1.4. ID Token Claims Subject Identifier Type . . . . . . . 5
3. Transmitter Configuration Discovery . . . . . . . . . . . . . 5
3.1. Transmitter Configuration Metadata . . . . . . . . . . . 6
3.2. Obtaining Transmitter Configuration Information . . . . . 6
3.2.1. Transmitter Configuration Request . . . . . . . . . . 7
3.2.2. Transmitter Configuration Response . . . . . . . . . 7
3.2.3. Transmitter Configuration Validation . . . . . . . . 8
4. Management API for SET Event Streams . . . . . . . . . . . . 8
Scurtescu, et al. Expires October 26, 2018 [Page 1]
openid-risc-profile April 2018
4.1. Event Stream Management . . . . . . . . . . . . . . . . . 9
4.1.1. Stream Status . . . . . . . . . . . . . . . . . . . . 10
4.1.1.1. Reading a Stream's Status . . . . . . . . . . . . 10
4.1.1.2. Updating a Stream's Status . . . . . . . . . . . 11
4.1.2. Stream Configuration . . . . . . . . . . . . . . . . 12
4.1.2.1. Reading a Stream's Configuration . . . . . . . . 13
4.1.2.2. Updating a Stream's Configuration . . . . . . . . 15
4.1.2.3. Removing a Stream Configuration . . . . . . . . . 18
4.1.3. Subjects . . . . . . . . . . . . . . . . . . . . . . 19
4.1.3.1. Adding a Subject to a Stream . . . . . . . . . . 19
4.1.3.2. Removing a Subject . . . . . . . . . . . . . . . 21
4.1.4. Verification . . . . . . . . . . . . . . . . . . . . 22
4.1.4.1. Verification Event . . . . . . . . . . . . . . . 22
4.1.4.2. Triggering a Verification Event. . . . . . . . . 23
4.2. Authorization . . . . . . . . . . . . . . . . . . . . . . 25
4.3. Security Considerations . . . . . . . . . . . . . . . . . 25
4.3.1. Subject Probing . . . . . . . . . . . . . . . . . . . 25
4.3.2. Information Harvesting . . . . . . . . . . . . . . . 26
4.3.3. Malicious Subject Removal . . . . . . . . . . . . . . 26
5. Profiles . . . . . . . . . . . . . . . . . . . . . . . . . . 26
5.1. Security Event Token Profle . . . . . . . . . . . . . . . 27
5.1.1. Signature Key Resolution . . . . . . . . . . . . . . 27
5.1.2. RISC Event Subject . . . . . . . . . . . . . . . . . 27
5.1.3. Explicit Typing of SETs . . . . . . . . . . . . . . . 27
5.1.4. The "exp" Claim . . . . . . . . . . . . . . . . . . . 28
5.1.5. The "aud" Claim . . . . . . . . . . . . . . . . . . . 28
5.1.6. The "events" claim . . . . . . . . . . . . . . . . . 29
5.1.7. Security Considerations . . . . . . . . . . . . . . . 29
5.1.7.1. Distingushing SETs from other Kinds of JWTs . . . 29
5.2. SET Token Delivery Using HTTP Profile . . . . . . . . . . 29
5.2.1. Stream Configuration Metadata . . . . . . . . . . . . 29
5.2.1.1. Push Delivery using HTTP . . . . . . . . . . . . 30
5.2.1.2. Polling Delivery using HTTP . . . . . . . . . . . 30
6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 30
6.1. Security Event Subject Identifier Types Registry . . . . 30
6.1.1. Registration Template . . . . . . . . . . . . . . . . 30
6.1.2. Initial Registry Contents . . . . . . . . . . . . . . 31
6.1.3. Guidance for Expert Reviewers . . . . . . . . . . . . 31
6.2. Well-Known URI Registry . . . . . . . . . . . . . . . . . 32
6.2.1. Registry Contents . . . . . . . . . . . . . . . . . . 32
7. Privacy Considerations . . . . . . . . . . . . . . . . . . . 32
7.1. Subject Information Leakage . . . . . . . . . . . . . . . 32
8. References . . . . . . . . . . . . . . . . . . . . . . . . . 33
8.1. Normative References . . . . . . . . . . . . . . . . . . 33
8.2. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 35
Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 35
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 35
Scurtescu, et al. Expires October 26, 2018 [Page 2]
openid-risc-profile April 2018
1. Introduction
1.1. Notational Conventions
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in BCP
14 [RFC2119] [RFC8174] when, and only when, they appear in all
capitals, as shown here.
2. Subject Identifiers
The RISC profile defines a structure called a Subject Identifier: a
JSON [RFC7159] object containing a set of claims that collectively
uniquely identify a subject, according to a simple schema called a
Subject Identifier Type. Every Subject Identifier MUST contain a
"subject_type" claim, whose value MUST be a name that uniquely
identifies the Subject Identifier Type of the Subject Identifier.
Any remaining claims within the Subject Identifier MUST be
interpreted according to the definition of the Subject Identifier
Type. A Subject Identifier MUST conform to the Subject Identifier
Type identified by its "subject_type" claim, and MUST NOT contain any
claims not defined by its Subject Identifier Type.
{
"iss": "https://idp.example.com/",
"jti": "756E69717565206964656E746966696572",
"iat": 1520364019,
"aud": "636C69656E745F6964",
"events": {
"https://schemas.openid.net/secevent/risc/event-type/account-\
enabled": {
"subject": {
"subject_type": "email",
"email": "foo at example.com"
}
}
}
}
A Subject Identifier that identifies a subject by email address.
Figure 1: Example: SET Containing a RISC Event with an Email Subject
Identifier
Scurtescu, et al. Expires October 26, 2018 [Page 3]
openid-risc-profile April 2018
{
"iss": "https://idp.example.com/",
"jti": "756E69717565206964656E746966696572",
"iat": 1520364019,
"aud": "636C69656E745F6964",
"events": {
"https://schemas.openid.net/secevent/risc/event-type/account-\
enabled": {
"subject": {
"subject_type": "iss_sub",
"iss": "https://issuer.example.com/",
"sub": "abc1234"
}
}
}
}
A Subject Identifier that identifies a subject by an identifier
provided by an issuer.
Figure 2: Example: SET Containing a RISC Event with an Issuer and
Subject Subject Identifier
2.1. Subject Identifier Types
A Subject Identifier Type is a light-weight schema that describes a
set of claims that uniquely identifies a subject. Every Subject
Identifier Type MUST have a unique name registered in the IANA
"Security Event Subject Identifier Types" registry established by
Section 6.1. A Subject Identifier Type MAY contain more claims than
are strictly necessary to uniquely identify a subject, however a
Subject Identifier MUST contain all of the claims required by its
type (See Privacy Considerations).
The following Subject Identifier Types are registered in the IANA
"Security Event Subject Identifier Types" registry established by
Section 6.1.
2.1.1. Email Subject Identifier Type
The Email Subject Identifier Type describes a subject by email
address. Subject Identifiers of this type MUST contain an "email"
claim whose value is a string containing the email address of the
subject. The "email" claim MUST NOT be null or empty. The Email
Subject Identifier Type is identified by the name "email".
Scurtescu, et al. Expires October 26, 2018 [Page 4]
openid-risc-profile April 2018
2.1.2. Phone Number Subject Identifier Type
The Phone Number Subject Identifier Type describes a subject by
telephone number. Subject Identifiers of this type MUST contain a
"phone" claim whose value is a string containing the full telephone
number of the subject, including international dialing prefix,
formatted according to E.164 [E164]. The "phone" claim MUST NOT be
null or empty. The Phone Number Subject Identifier Type is
identified by the name "phone".
2.1.3. Issuer and Subject Subject Identifier Type
The Issuer and Subject Subject Identifier Type describes a subject by
an issuer and a subject. Subject Identifiers of this type MUST
contain an "iss" claim whose value identifies the issuer, and a "sub"
claim whose value identifies the subject with respect to the issuer.
These claims MUST follow the formats of the "iss" claim and "sub"
claim defined by [RFC7519], respectively. Both the "iss" claim and
the "sub" claim MUST NOT be null or empty. The Issuer and Subject
Subject Identifier Type is identified by the name "iss_sub".
2.1.4. ID Token Claims Subject Identifier Type
The ID Token Claims Subject Identifier Type describes a subject by a
subset of the claims from an ID token. Subject Identifiers of this
type MUST contain at least one of the following claims:
email
An "email" claim, as defined in [IDTOKEN].
phone_number
An "phone_number" claim, as defined in [IDTOKEN].
sub
A "sub" claim, as defined in [RFC7519].
If the Subject Identifier contains a "sub" claim, it MUST also
contain an "iss" claim, as defined in [RFC7519]. The ID Token Claims
Subject Identifier Type is identified by the name "id_token_claims".
3. Transmitter Configuration Discovery
This section defines a mechanism for Receivers to obtain Transmitter
configuration information.
Scurtescu, et al. Expires October 26, 2018 [Page 5]
openid-risc-profile April 2018
3.1. Transmitter Configuration Metadata
Transmitters have metadata describing their configuration:
issuer REQUIRED. URL using the https scheme with no query or
fragment component that the Transmitter asserts as its Issuer
Identifier. This MUST be identical to the iss Claim value in
Security Event Tokens issued from this Transmitter.
jwks_uri REQUIRED. URL of the Transmitter's JSON Web Key Set
[RFC7517] document. This contains the signing key(s) the Receiver
uses to validate signatures from the Transmitter.
delivery_methods_supported RECOMMENDED. List of supported delivery
method URIs.
configuration_endpoint OPTIONAL. The URL of the Configuration
Endpoint.
status_endpoint OPTIONAL. The URL of the Status Endpoint.
add_subject_endpoint OPTIONAL. The URL of the Add Subject Endpoint.
remove_subject_endpoint OPTIONAL. The URL of the Remove Subject
Endpoint.
verification_endpoint OPTIONAL. The URL of the Verification
Endpoint.
TODO: consider adding a IANA Registry for metadata, similar to
Section 7.1.1 of [OAUTH-DISCOVERY]. This would allow other specs to
add to the metadata.
3.2. Obtaining Transmitter Configuration Information
Using the Issuer as documented by the Transmitter, the Transmitter
Configuration Information can be retrieved.
Transmitters supporting Discovery MUST make a JSON document available
at the path formed by inserting the string "/.well-known/risc-
configuration" into the Issuer between the host component and the
path component, if any. The syntax and semantics of ".well-known"
are defined in [RFC5785]. "risc-configuration" MUST point to a JSON
document compliant with this specification and MUST be returned using
the "application/json" content type.
Scurtescu, et al. Expires October 26, 2018 [Page 6]
openid-risc-profile April 2018
3.2.1. Transmitter Configuration Request
A Transmitter Configuration Document MUST be queried using an HTTP
"GET" request at the previously specified path.
The Receiver would make the following request to the Issuer
"https://tr.example.com" to obtain its Configuration information,
since the Issuer contains no path component:
GET /.well-known/risc-configuration HTTP/1.1
Host: tr.example.com
Figure 3: Example: Transmitter Configuration Request (without path)
If the Issuer value contains a path component, any terminating "/"
MUST be removed before inserting "/.well-known/risc-configuration"
between the host component and the path component. The Receiver
would make the following request to the Issuer
"https://tr.example.com/issuer1" to obtain its Configuration
information, since the Issuer contains a path component:
GET /.well-known/risc-configuration/issuer1 HTTP/1.1
Host: tr.example.com
Figure 4: Example: Transmitter Configuration Request (with path)
Using path components enables supporting multiple issuers per host.
This is required in some multi-tenant hosting configurations. This
use of ".well-known" is for supporting multiple issuers per host;
unlike its use in [RFC5785], it does not provide general information
about the host.
3.2.2. Transmitter Configuration Response
The response is a set of Claims about the Transmitter's
configuration, including all necessary endpoints and public key
location information. A successful response MUST use the 200 OK HTTP
status code and return a JSON object using the "application/json"
content type that contains a set of Claims as its members that are a
subset of the Metadata values defined in Section 3.1. Other Claims
MAY also be returned.
Claims that return multiple values are represented as JSON arrays.
Claims with zero elements MUST be omitted from the response.
An error response uses the applicable HTTP status code value.
Scurtescu, et al. Expires October 26, 2018 [Page 7]
openid-risc-profile April 2018
HTTP/1.1 200 OK
Content-Type: application/json
{
"issuer":
"https://tr.example.com",
"jwks_uri":
"https://tr.example.com/jwks.json",
"delivery_methods_supported": [
"https://schemas.openid.net/secevent/risc/delivery-method/push",
"https://schemas.openid.net/secevent/risc/delivery-method/poll"],
"configuration_endpoint":
"https://tr.example.com/risc/mgmt/stream",
"status_endpoint":
"https://tr.example.com/risc/mgmt/status",
"add_subject_endpoint":
"https://tr.example.com/risc/mgmt/subject:add",
"remove_subject_endpoint":
"https://tr.example.com/risc/mgmt/subject:remove",
"verification_endpoint":
"https://tr.example.com/risc/mgmt/verification"
}
Figure 5: Example: Transmitter Configuration Response
3.2.3. Transmitter Configuration Validation
If any of the validation procedures defined in this specification
fail, any operations requiring the information that failed to
correctly validate MUST be aborted and the information that failed to
validate MUST NOT be used.
The "issuer" value returned MUST be identical to the Issuer URL that
was directly used to retrieve the configuration information. This
MUST also be identical to the "iss" Claim value in Security Event
Tokens issued from this Transmitter.
4. Management API for SET Event Streams
This section defines an HTTP API to be implemented by Event
Transmitters and that can be used by Event Receivers to query and
update the Event Stream configuration and status, to add and remove
subjects and to trigger verification.
This section is based on Management API for SET Event Streams
[MGMTAPI].
Scurtescu, et al. Expires October 26, 2018 [Page 8]
openid-risc-profile April 2018
+------------+ +------------+
| | Stream Config | |
| Event <----------------+ Event |
| Stream | | Receiver |
| Management | Stream Status | |
| API <----------------+ |
| | | |
| | Add Subject | |
| <----------------+ |
| | | |
| | Remove Subject | |
| <----------------+ |
| | | |
| | Verification | |
| <----------------+ |
| | | |
+------------+ +------------+
Figure 6: Event Stream Management API
It is OPTIONAL for Transmitters to implement a Management API, but it
is RECOMMENDED that they implement it, especially the endpoints for
querying the Stream Status and for triggering Verification.
4.1. Event Stream Management
Event Receivers manage how they receive events, and the subjects
about which they want to receive events over an Event Stream by
making HTTP requests to endpoints in the Event Stream Management API.
The Event Stream Management API is implemented by the Event
Transmitter and consists of the following endpoints:
Configuration Endpoint
An endpoint used to read the Event Stream's current configuration.
Status Endpoint
An endpoint used to read the Event Stream's current status.
Add Subject Endpoint
An endpoint used to add subjects to an Event Stream.
Remove Subject Endpoint
An endpoint used to remove subjects from an Event Stream.
Verification Endpoint
An endpoint used to request the Event Transmitter transmit a
Verification Event over the Event Stream.
Scurtescu, et al. Expires October 26, 2018 [Page 9]
openid-risc-profile April 2018
An Event Transmitter MAY use the same URLs as endpoints for multiple
streams, provided that the Event Transmitter has some mechanism
through which they can identify the applicable Event Stream for any
given request, e.g. from authentication credentials. The definition
of such mechanisms is outside the scope of this specification.
4.1.1. Stream Status
4.1.1.1. Reading a Stream's Status
An Event Receiver checks the current status of an event stream by
making an HTTP GET request to the stream's Status Endpoint. On
receiving a valid request the Event Transmitter responds with a 200
OK response containing a JSON [RFC7159] object with a single
attribute "status", whose string value MUST have one of the following
values:
enabled
The transmitter will transmit events over the stream, according to
the stream's configured delivery method.
paused
The transmitter will not transmit events over the stream. The
transmitter will hold any events it would have transmitted while
paused, and will transmit them when the stream's status becomes
"enabled".
disabled
The transmitter will not transmit events over the stream, and will
not hold any events for later transmission.
The following is a non-normative example request to check an event
stream's status:
GET /set/status HTTP/1.1
Host: transmitter.example.com
Authorization: Bearer eyJ0b2tlbiI6ImV4YW1wbGUifQo=
Figure 7: Example: Check Stream Status Request
The following is a non-normative example response:
Scurtescu, et al. Expires October 26, 2018 [Page 10]
openid-risc-profile April 2018
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
{
"status": "enabled"
}
Figure 8: Example: Check Stream Status Response
Errors are signaled with HTTP status codes as follows:
+------+------------------------------------------------------------+
| Code | Description |
+------+------------------------------------------------------------+
| 401 | if authorization failed or it is missing |
| | |
| 403 | if the Event Receiver is not allowed to read the stream |
| | status |
| | |
| 404 | if there is no Event Stream configured for this Event |
| | Receiver |
+------+------------------------------------------------------------+
Table 1: Read Stream Status Errors
4.1.1.2. Updating a Stream's Status
An Event Receiver updates the current status of a stream by making an
HTTP POST request to the Status Endpoint. The POST body contains a
JSON [RFC7159] representation of the updated status. On receiving a
valid request the Event Transmitter responds with a "200 OK" response
containing a JSON [RFC7159] representation of the updated stream
status in the body.
The following is a non-normative example request to update an Event
Stream's status:
POST /set/status HTTP/1.1
Host: transmitter.example.com
Authorization: Bearer eyJ0b2tlbiI6ImV4YW1wbGUifQo=
{
"status": "paused",
}
Figure 9: Example: Update Stream Status Request
Scurtescu, et al. Expires October 26, 2018 [Page 11]
openid-risc-profile April 2018
The following is a non-normative example response:
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
{
"status": "paused"
}
Figure 10: Example: Update Stream Status Response
Errors are signaled with HTTP status codes as follows:
+------+------------------------------------------------------------+
| Code | Description |
+------+------------------------------------------------------------+
| 400 | if the request body cannot be parsed or if the request is |
| | otherwise invalid |
| | |
| 401 | if authorization failed or it is missing |
| | |
| 403 | if the Event Receiver is not allowed to update the stream |
| | status |
| | |
| 404 | if there is no Event Stream configured for this Event |
| | Receiver |
+------+------------------------------------------------------------+
Table 2: Update Stream Status Errors
4.1.2. Stream Configuration
An Event Stream's configuration is represented as a JSON [RFC7159]
object with the following properties:
iss
*Read-Only*, A URL using the https scheme with no query or
fragment component that the Transmitter asserts as its Issuer
Identifier. This MUST be identical to the "iss" Claim value in
Security Event Tokens issued from this Transmitter.
aud
*Read-Only*, A string or an array of strings containing an
audience claim as defined in JSON Web Token (JWT) [RFC7519] that
identifies the Event Receiver(s) for the Event Stream. This
property cannot be updated. If multiple Receivers are specified
Scurtescu, et al. Expires October 26, 2018 [Page 12]
openid-risc-profile April 2018
then the Transmitter SHOULD know that these Receivers are the same
entity.
events_supported
*Read-Only*, An array of URIs identifying the set of events
supported by the Transmitter for this Receiver. If omitted, Event
Transmitters SHOULD make this set available to the Event Receiver
via some other means (e.g. publishing it in online documentation).
events_requested
*Read-Write*, An array of URIs identifying the set of events that
the Receiver requested. A Receiver should request only the events
that it understands and it can act on. This is configurabel by
the Receuver.
events_delivered
*Read-Only*, An array of URIs which is the intersection of
"events_supported" and "events_requested". These events MAY be
delivered over the Event Stream.
delivery
*Read-Write*, A JSON object containing a set of name/value pairs
specifying configuration parameters for the SET delivery method.
The actual delivery method is identified by the special key
"method" with the value being a URI as defined in Section 5.2.1.
min_verification_interval
*Read-Only*, An integer indicating the minimum amount of time in
seconds that must pass in between verification requests. If an
Event Receiver submits verification requests more frequently than
this, the Event Transmitter MAY respond with a 429 status code.
An Event Transmitter SHOULD NOT respond with a 429 status code if
an Event Receiver is not exceeding this frequency.
subject_type
*Read-Write*, The Subject Identifier Type that the Receiver wants
for the events. If not set then the Transmitter might decide to
use a type that discloses more information than necessary.
TODO: consider adding a IANA Registry for stream configuration
metadata, similar to Section 7.1.1 of [OAUTH-DISCOVERY]. This would
allow other specs to add to the stream configuration.
4.1.2.1. Reading a Stream's Configuration
An Event Receiver gets the current configuration of a stream by
making an HTTP GET request to the Configuration Endpoint. On
receiving a valid request the Event Transmitter responds with a "200
Scurtescu, et al. Expires October 26, 2018 [Page 13]
openid-risc-profile April 2018
OK" response containing a JSON [RFC7159] representation of the
stream's configuration in the body.
The following is a non-normative example request to read an Event
Stream's configuration:
GET /set/stream HTTP/1.1
Host: transmitter.example.com
Authorization: Bearer eyJ0b2tlbiI6ImV4YW1wbGUifQo=
Figure 11: Example: Read Stream Configuration Request
The following is a non-normative example response:
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
{
"iss": "https://tr.example.com",
"aud": [
"http://receiver.example.com/web",
"http://receiver.example.com/mobile"
],
"delivery": {
"delivery_method":
"https://schemas.openid.net/secevent/risc/delivery-method/push",
"url": "https://receiver.example.com/events"
},
"events_supported": [
"urn:example:secevent:events:type_1",
"urn:example:secevent:events:type_2",
"urn:example:secevent:events:type_3"
],
"events_requested": [
"urn:example:secevent:events:type_2",
"urn:example:secevent:events:type_3",
"urn:example:secevent:events:type_4"
],
"events_delivered": [
"urn:example:secevent:events:type_2",
"urn:example:secevent:events:type_3"
]
}
Figure 12: Example: Read Stream Configuration Response
Scurtescu, et al. Expires October 26, 2018 [Page 14]
openid-risc-profile April 2018
Errors are signaled with HTTP status codes as follows:
+------+------------------------------------------------------------+
| Code | Description |
+------+------------------------------------------------------------+
| 401 | if authorization failed or it is missing |
| | |
| 403 | if the Event Receiver is not allowed to read the stream |
| | configuration |
| | |
| 404 | if there is no Event Stream configured for this Event |
| | Receiver |
+------+------------------------------------------------------------+
Table 3: Read Stream Configuration Errors
4.1.2.2. Updating a Stream's Configuration
An Event Receiver updates the current configuration of a stream by
making an HTTP POST request to the Configuration Endpoint. The POST
body contains a JSON [RFC7159] representation of the updated
configuration. On receiving a valid request the Event Transmitter
responds with a "200 OK" response containing a JSON [RFC7159]
representation of the updated stream configuration in the body.
The full set of editable properties must be present in the POST body,
not only the ones that are specifically intended to be changed.
Missing properties SHOULD be interpreted as requested to be deleted.
Event Receivers should read the configuration first, modify the JSON
[RFC7159] representation, then make an update request.
Properties that cannot be updated MAY be present, but they MUST match
the expected value.
The following is a non-normative example request to update an Event
Stream's configuration:
Scurtescu, et al. Expires October 26, 2018 [Page 15]
openid-risc-profile April 2018
POST /set/stream HTTP/1.1
Host: transmitter.example.com
Authorization: Bearer eyJ0b2tlbiI6ImV4YW1wbGUifQo=
{
"iss": "https://tr.example.com",
"aud": [
"http://receiver.example.com/web",
"http://receiver.example.com/mobile"
],
"delivery": {
"delivery_method":
"https://schemas.openid.net/secevent/risc/delivery-method/push",
"url": "https://receiver.example.com/events"
},
"events_requested": [
"urn:example:secevent:events:type_2",
"urn:example:secevent:events:type_3",
"urn:example:secevent:events:type_4"
]
}
Figure 13: Example: Update Stream Configuration Request
The following is a non-normative example response:
Scurtescu, et al. Expires October 26, 2018 [Page 16]
openid-risc-profile April 2018
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
{
"iss": "https://tr.example.com",
"aud": [
"http://receiver.example.com/web",
"http://receiver.example.com/mobile"
],
"delivery": {
"delivery_method":
"https://schemas.openid.net/secevent/risc/delivery-method/push",
"url": "https://receiver.example.com/events"
},
"events_supported": [
"urn:example:secevent:events:type_1",
"urn:example:secevent:events:type_2",
"urn:example:secevent:events:type_3"
],
"events_requested": [
"urn:example:secevent:events:type_2",
"urn:example:secevent:events:type_3",
"urn:example:secevent:events:type_4"
],
"events_delivered": [
"urn:example:secevent:events:type_2",
"urn:example:secevent:events:type_3"
]
}
Figure 14: Example: Update Stream Configuration Response
Errors are signaled with HTTP status codes as follows:
Scurtescu, et al. Expires October 26, 2018 [Page 17]
openid-risc-profile April 2018
+------+------------------------------------------------------------+
| Code | Description |
+------+------------------------------------------------------------+
| 400 | if the request body cannot be parsed or if the request is |
| | otherwise invalid |
| | |
| 401 | if authorization failed or it is missing |
| | |
| 403 | if the Event Receiver is not allowed to update the stream |
| | configuration |
| | |
| 404 | if there is no Event Stream configured for this Event |
| | Receiver |
+------+------------------------------------------------------------+
Table 4: Update Stream Configuration Errors
4.1.2.3. Removing a Stream Configuration
An Event Receiver removes the configuration of a stream by making an
HTTP DELETE request to the Configuration Endpoint. On receiving a
request the Event Transmitter responds with a "200 OK" response if
the configuration was successfully removed.
The following is a non-normative example request to remove an Event
Stream's configuration:
DELETE /set/stream HTTP/1.1
Host: transmitter.example.com
Authorization: Bearer eyJ0b2tlbiI6ImV4YW1wbGUifQo=
Figure 15: Example: Remove Stream Configuration Request
Errors are signaled with HTTP status codes as follows:
+------+------------------------------------------------------------+
| Code | Description |
+------+------------------------------------------------------------+
| 401 | if authorization failed or it is missing |
| | |
| 403 | if the Event Receiver is not allowed to update the stream |
| | configuration |
+------+------------------------------------------------------------+
Table 5: Update Stream Configuration Errors
Scurtescu, et al. Expires October 26, 2018 [Page 18]
openid-risc-profile April 2018
4.1.3. Subjects
An Event Receiver can indicate to an Event Transmitter whether or not
the receiver wants to receive events about a particular subject by
"adding" or "removing" that subject to the Event Stream,
respectively.
4.1.3.1. Adding a Subject to a Stream
To add a subject to an Event Stream, the Event Receiver makes an HTTP
POST request to the Add Subject Endpoint, containing in the body a
JSON object the following claims:
subject
REQUIRED. A Subject Identifier identifying the subject to be
added.
verified
OPTIONAL. A boolean value; when true, it indicates that the Event
Receiver has verified the Subject Identifier. When false, it
indicates that the Event Receiver has not verified the Subject
Identifier. If omitted, Event Transmitters SHOULD NOT assume that
verification has not occurred.
On a successful response, the Event Transmitter responds with an
empty "200 OK" response. The Event Transmitter MAY choose to
silently ignore the request, for example if the subject has
previously indicated to the transmitter that they do not want events
to be transmitted to the Event Receiver. In this case, the
transmitter MAY return an empty "200 OK" response or an appropriate
error code. See Security Considerations (Section 4.3).
Errors are signaled with HTTP status codes as follows:
Scurtescu, et al. Expires October 26, 2018 [Page 19]
openid-risc-profile April 2018
+------+------------------------------------------------------------+
| Code | Description |
+------+------------------------------------------------------------+
| 400 | if the request body cannot be parsed or if the request is |
| | otherwise invalid |
| | |
| 401 | if authorization failed or it is missing |
| | |
| 403 | if the Event Receiver is not allowed to add this |
| | particular subject, or not allowed to add in general |
| | |
| 404 | if the subject is not recognized by the Event Transmitter, |
| | the Event Transmitter may chose to stay silent in this |
| | case and respond with "200" |
| | |
| 429 | if the Event Receiver is sending too many requests in a |
| | gvien amount of time |
+------+------------------------------------------------------------+
Table 6: Add Subject Errors
The following is a non-normative example request to add a subject to
a stream, where the subject is identified by an Email Subject
Identifier.
POST /set/subjects:add HTTP/1.1
Host: transmitter.example.com
Authorization: Bearer eyJ0b2tlbiI6ImV4YW1wbGUifQo=
{
"subject": {
"subject_type": "email",
"email": "example.user at example.com"
},
"verified": true
}
Figure 16: Example: Add Subject Request
The following is a non-normative example response to a successful
request:
HTTP/1.1 200 OK
Server: transmitter.example.com
Cache-Control: no-store
Pragma: no-cache
Figure 17: Example: Add Subject Response
Scurtescu, et al. Expires October 26, 2018 [Page 20]
openid-risc-profile April 2018
4.1.3.2. Removing a Subject
To remove a subject from an Event Stream, the Event Receiver makes an
HTTP POST request to the Remove Subject Endpoint, containing in the
body a JSON object with the following claims:
subject
A Subject Identifier identifying the subject to be removed.
REQUIRED.
On a successful response, the Event Transmitter responds with a "204
No Content" response.
Errors are signaled with HTTP status codes as follows:
+------+------------------------------------------------------------+
| Code | Description |
+------+------------------------------------------------------------+
| 400 | if the request body cannot be parsed or if the request is |
| | otherwise invalid |
| | |
| 401 | if authorization failed or it is missing |
| | |
| 403 | if the Event Receiver is not allowed to remove this |
| | particular subject, or not allowed to remove in general |
| | |
| 404 | if the subject is not recognized by the Event Transmitter, |
| | the Event Transmitter may chose to stay silent in this |
| | case and respond with "204" |
| | |
| 429 | if the Event Receiver is sending too many requests in a |
| | gvien amount of time |
+------+------------------------------------------------------------+
Table 7: Remove Subject Errors
The following is a non-normative example request where the subject is
identified by a Phone Number Subject Identifier:
Scurtescu, et al. Expires October 26, 2018 [Page 21]
openid-risc-profile April 2018
POST /set/subjects:remove HTTP/1.1
Host: transmitter.example.com
Authorization: Bearer eyJ0b2tlbiI6ImV4YW1wbGUifQo=
{
"subject": {
"subject_type": "phone",
"phone_number": "+1 206 555 0123"
}
}
Figure 18: Example: Remove Subject Request
The following is a non-normative example response to a successful
request:
HTTP/1.1 204 No Content
Server: transmitter.example.com
Cache-Control: no-store
Pragma: no-cache
Figure 19: Example: Remove Subject Response
4.1.4. Verification
In some cases, the frequency of event transmission on an Event Stream
will be very low, making it difficult for an Event Receiver to tell
the difference between expected behavior and event transmission
failure due to a misconfigured stream. Event Receivers can request
that a verification event be transmitted over the Event Stream,
allowing the receiver to confirm that the stream is configured
correctly upon successful receipt of the event. The acknowledgment
of a Verification Event also confirms to the Event Transmitter that
end-to-end delivery is working, including signature verification and
encryption.
An Event Transmitter MAY send a Verification Event at any time, even
if one was not requested by the Event Receiver.
4.1.4.1. Verification Event
The Verification Event is a standard SET with the following
attributes:
event type
The Event Type URI is: "https://schemas.openid.net/secevent/risc/
event-type/verification".
Scurtescu, et al. Expires October 26, 2018 [Page 22]
openid-risc-profile April 2018
state
OPTIONAL An opaque value provided by the Event Receiver when the
event is triggered. This is a nested attribute in the event
payload.
Upon receiving a Verification Event, the Event Receiver SHALL parse
the SET and validate its claims. In particular, the Event Receiver
SHALL confirm that the value for "state" is as expected. If the
value of "state" does not match, an error response of "setData"
SHOULD be returned (see Section 2.3 of [DELIVERYPUSH] or
[DELIVERYPOLL]).
In many cases, Event Transmitters MAY disable or suspend an Event
Stream that fails to successfully verify based on the acknowledgement
or lack of acknowledgement by the Event Receiver.
4.1.4.2. Triggering a Verification Event.
To request that a verification event be sent over an Event Stream,
the Event Receiver makes an HTTP POST request to the Verification
Endpoint, with a JSON [RFC7159] object containing the parameters of
the verification request, if any. On a successful request, the event
transmitter responds with an empty "204 No Content" response.
Verification requests have the following properties:
state
OPTIONAL. An arbitrary string that the Event Transmitter MUST
echo back to the Event Receiver in the verification event's
payload. Event Receivers MAY use the value of this parameter to
correlate a verification event with a verification request. If
the verification event is initiated by the transmitter then this
parameter MUST not be set.
A successful response from a POST to the Verification Endpoint does
not indicate that the verification event was transmitted
successfully, only that the Event Transmitter has transmitted the
event or will do so at some point in the future. Event Transmitters
MAY transmit the event via an asynchronous process, and SHOULD
publish an SLA for verification event transmission times. Event
Receivers MUST NOT depend on the verification event being transmitted
synchronously or in any particular order relative to the current
queue of events.
Errors are signaled with HTTP status codes as follows:
Scurtescu, et al. Expires October 26, 2018 [Page 23]
openid-risc-profile April 2018
+------+------------------------------------------------------------+
| Code | Description |
+------+------------------------------------------------------------+
| 400 | if the request body cannot be parsed or if the request is |
| | otherwise invalid |
| | |
| 401 | if authorization failed or it is missing |
| | |
| 429 | if the Event Receiver is sending too many requests in a |
| | gvien amount of time; see related |
| | "min_verification_interval" in Section 4.1.2 |
+------+------------------------------------------------------------+
Table 8: Verification Errors
The following is a non-normative example request to trigger a
verification event:
POST /set/verify HTTP/1.1
Host: transmitter.example.com
Authorization: Bearer eyJ0b2tlbiI6ImV4YW1wbGUifQo=
Content-Type: application/json; charset=UTF-8
{
"state": "VGhpcyBpcyBhbiBleGFtcGxlIHN0YXRlIHZhbHVlLgo="
}
Figure 20: Example: Trigger Verification Request
The following is a non-normative example response to a successful
request:
HTTP/1.1 204 No Content
Server: transmitter.example.com
Cache-Control: no-store
Pragma: no-cache
Figure 21: Example: Trigger Verification Response
And the following is a non-normative example of a verification event
sent to the Event Receiver as a result of the above request:
Scurtescu, et al. Expires October 26, 2018 [Page 24]
openid-risc-profile April 2018
{
"jti": "123456",
"iss": "https://transmitter.example.com",
"aud": "receiver.example.com",
"iat": "1493856000",
"events": [
"https://schemas.openid.net/secevent/risc/event-type/verification":{
"state": "VGhpcyBpcyBhbiBleGFtcGxlIHN0YXRlIHZhbHVlLgo="
}
]
}
Figure 22: Example: Verification SET
4.2. Authorization
HTTP API calls from a Receiver to a Transmitter SHOULD be authorized
by providing an OAuth 2 Access Token as defined by [RFC6750].
The receiver may obtain an access token using the Client Credential
Grant [CLIENTCRED], or any other method suitable for the Receiver and
the Transmitter.
Other authorization methods MAY be used if the Transmitter and the
Receiver have agreement on the method.
4.3. Security Considerations
4.3.1. Subject Probing
It may be possible for an Event Transmitter to leak information about
subjects through their responses to add subject requests. A "404"
response may indicate to the Event Receiver that the subject does not
exist, which may inadvertantly reveal information about the subject
(e.g. that a particular individual does or does not use the Event
Transmitter's service).
Event Transmitters SHOULD carefully evaluate the conditions under
which they will return error responses to add subject requests.
Event Transmitters MAY return a "204" response even if they will not
actually send any events related to the subject, and Event Receivers
MUST NOT assume that a 204 response means that they will receive
events related to the subject.
Scurtescu, et al. Expires October 26, 2018 [Page 25]
openid-risc-profile April 2018
4.3.2. Information Harvesting
SETs may contain personally identifiable information (PII) or other
non-public information about the event transmitter, the subject (of
an event in the SET), or the relationship between the two. It is
important for Event Transmitters to understand what information they
are revealing to Event Receivers when transmitting events to them,
lest the event stream become a vector for unauthorized access to
private information.
Event Transmitters SHOULD interpret add subject requests as
statements of interest in a subject by an Event Receiver, and ARE NOT
obligated to transmit events related to every subject an Event
Receiver adds to the stream. Event Transmitters MAY choose to
transmit some, all, or no events related to any given subject and
SHOULD validate that they are permitted to share the information
contained within an event with the Event Receiver before transmitting
the event. The mechanisms by which such validation is performed are
outside the scope of this specification.
4.3.3. Malicious Subject Removal
A malicious party may find it advantageous to remove a particular
subject from a stream, in order to reduce the Event Receiver's
ability to detect malicious activity related to the subject,
inconvenience the subject, or for other reasons. Consequently it may
be in the best interests of the subject for the Event Transmitter to
continue to send events related to the subject for some time after
the subject has been removed from a stream.
Event Transmitters MAY continue sending events related to a subject
for some amount of time after that subject has been removed from the
stream. Event Receivers MUST tolerate receiving events for subjects
that have been removed from the stream, and MUST NOT report these
events as errors to the Event Transmitter.
5. Profiles
This section is a profile of the following IETF SecEvent
specifications:
o "Security Event Token (SET)" [SET]
o Push-Based SET Token Delivery Using HTTP [DELIVERYPUSH]
o Poll-Based SET Token Delivery Using HTTP [DELIVERYPOLL]
Scurtescu, et al. Expires October 26, 2018 [Page 26]
openid-risc-profile April 2018
The RISC use cases that set the requirements are described in
Security Events RISC Use Cases [USECASES].
5.1. Security Event Token Profle
This section provides RISC profiling specifications for the "Security
Event Token (SET)" [SET] spec.
5.1.1. Signature Key Resolution
The signature key can be obtained through "jwks_uri", see Section 3.
5.1.2. RISC Event Subject
The subject of a RISC event is identified by the "subject" claim
within the event payload, whose value is a Subject Identifier. The
"subject" claim is REQUIRED for all RISC events. The JWT "sub" claim
MUST NOT be present in any SET containing a RISC event.
{
"iss": "https://idp.example.com/",
"jti": "756E69717565206964656E746966696572",
"iat": 1520364019,
"aud": "636C69656E745F6964",
"events": {
"https://schemas.openid.net/secevent/risc/event-type/account-\
disabled": {
"subject": {
"subject_type": "phone",
"phone_number": "+1 206 555 0123"
},
"reason": "hijacking",
"cause-time": 1508012752
}
}
}
Figure 23: Example: SET Containing a RISC Event with a Phone Number
Subject
5.1.3. Explicit Typing of SETs
RISC events MUST use explicit typing as defined in Section 2.3 of
[SET].
Scurtescu, et al. Expires October 26, 2018 [Page 27]
openid-risc-profile April 2018
{
"typ":"secevent+jwt",
"alg":"HS256"
}
Figure 24: Explicitly Typed JOSE Header
The purpose is defense against confusion with other JWTs, as
described in Sections 4.5, 4.6 and 4.7 of [SET]. While current Id
Token [IDTOKEN] validators may not be using the "typ" header
parameter, by requiring it for RISC SETs a distinct value is
guaranteed for future validators.
5.1.4. The "exp" Claim
The "exp" claim MUST NOT be used in RISC SETs.
The purpose is defense in depth against confusion with other JWTs, as
described in Sections 4.5 and 4.6 of [SET].
5.1.5. The "aud" Claim
The "aud" claim can be a single value or an array. Each value SHOULD
be the OAuth 2 client id. Other values that uniquely identifies the
Receiver to the Transmitter MAY be used, if the two parties have
agreement on the format.
More than one values can be present if the corresponding Receivers
are known to the Transmitter to be the same entity, for example a web
client and I mobile client of the same application. All the
Receivers in this case MUST use the exact same delivery method.
If multiple Receivers have the exact same delivery configuration but
the Transmitter does not know if they belong to the same entity then
the Transmitter SHOULD issue distinct SETs for each Receiver and
deliver them separately. In this case the multiple Receivers might
use the same service to process SETs, and this service might reroute
SETs to respective Receivers, an "aud" claim with multiple Receivers
would lead to unintended data disclosure.
Scurtescu, et al. Expires October 26, 2018 [Page 28]
openid-risc-profile April 2018
{
"jti": "123456",
"iss": "https://transmitter.example.com",
"aud": ["receiver.example.com/web", "receiver.example.com/mobile"],
"iat": "1493856000",
"events": [
"https://schemas.openid.net/secevent/risc/event-type/verification":{
"state": "VGhpcyBpcyBhbiBleGFtcGxlIHN0YXRlIHZhbHVlLgo="
}
]
}
Figure 25: Example: SET with array 'aud' claim
5.1.6. The "events" claim
The "events" claim SHOULD contain only one event. Multiple event
type URIs are permitted only if they are alternative URIs defining
the exact same event type.
5.1.7. Security Considerations
5.1.7.1. Distingushing SETs from other Kinds of JWTs
Of particular concern is the possibility that SETs are confused for
other kinds of JWTs. The Security Considerations sesction of [SET]
has several sub-sections on this subject. The RISC Profile is asking
for further restrioctons:
o The "sub" claim MUST NOT be present, as described in
Section 5.1.2.
o RISC SETs MUST use explicit typing, as described in Section 5.1.3.
o The "exp" claim MUST NOT be present, as described in
Section 5.1.4.
5.2. SET Token Delivery Using HTTP Profile
This section provides RISC profiling specifications for the
[DELIVERYPUSH] and [DELIVERYPOLL] specs.
5.2.1. Stream Configuration Metadata
Each delivery method is identified by a URI, specified below by the
"method" metadata.
Scurtescu, et al. Expires October 26, 2018 [Page 29]
openid-risc-profile April 2018
5.2.1.1. Push Delivery using HTTP
This section provides RISC profiling specifications for the
[DELIVERYPUSH] spec.
method "https://schemas.openid.net/secevent/risc/delivery-method/
push"
endpoint_url The URL where events are pushed through HTTP POST.
This is set by the Receiver.
authorization_header The HTTP Authorization header that the
Transmitter MUST set with each event delivery, if the
configuration is present. The value is optional and it is set by
the Receiver.
5.2.1.2. Polling Delivery using HTTP
This section provides RISC profiling specifications for the
[DELIVERYPOLL] spec.
method "https://schemas.openid.net/secevent/risc/delivery-method/
poll"
endpoint_url The URL where events can be retrieved from. This is
specified by the Transmitter.
6. IANA Considerations
6.1. Security Event Subject Identifier Types Registry
This document defines Subject Identifier Types, for which IANA is
asked to create and maintain a new registry titled "Security Event
Subject Identifier Types". Initial values for the Security Event
Subject Identifier Types registry are given in Section 6.1.2. Future
assignments are to be made through the Expert Review registration
policy [BCP26] and shall follow the template presented in
Section 6.1.1.
6.1.1. Registration Template
Type Name:
The name of the Subject Identifier Type, as described in
Section 2.1. The name MUST be an ASCII string consisting only of
lower-case characters ("a" - "z"), digits ("0" - "9"), and hyphens
("-"), and SHOULD NOT exceed 20 characters in length.
Type Description:
Scurtescu, et al. Expires October 26, 2018 [Page 30]
openid-risc-profile April 2018
A brief description of the Subject Identifier Type.
Change Controller:
For types defined in documents published by the OpenID Foundation
or its working groups, list "OIDF RISC Working Group". For all
other types, list the name of the party responsible for the
registration. Contact information such as mailing address, email
address, or phone number may also be provided.
Defining Document(s):
A reference to the document or documents that define the Subject
Identifier Type. The definition MUST specify the name, format,
and meaning of each claim that may occur within a Subject
Identifier of the defined type, as well as whether each claim is
optional or required, or the circumstances under which the claim
is optional or required. URIs that can be used to retrieve copies
of each document SHOULD be included.
6.1.2. Initial Registry Contents
o Type Name: "email"
o Type Description: Subject identifier based on email address.
o Change Controller: OIDF RISC Working Group
o Defining Document(s): Section 2.1.1 of this document.
o Type Name: "id_token_claims"
o Type Description: Subject identifier based on OpenID Connect ID
Token claims.
o Change Controller: OIDF RISC Working Group
o Defining Document(s): Section 2.1.4 of this document.
o Type Name: "iss_sub"
o Type Description: Subject identifier based on issuer and subject.
o Change Controller: OIDF RISC Working Group
o Defining Document(s): Section 2.1.3 of this document.
o Type Name: "phone"
o Type Description: Subject identifier based on phone number.
o Change Controller: OIDF RISC Working Group
o Defining Document(s): Section 2.1.2 of this document.
6.1.3. Guidance for Expert Reviewers
The Expert Reviewer is expected to review the documentation
referenced in a registration request to verify its completeness. The
Expert Reviewer must base their decision to accept or reject the
request on a fair and impartial assessment of the request. If the
Expert Reviewer has a conflict of interest, such as being an author
Scurtescu, et al. Expires October 26, 2018 [Page 31]
openid-risc-profile April 2018
of a defining document referenced by the request, they must recuse
themselves from the approval process for that request. In the case
where a request is rejected, the Expert Reviewer should provide the
requesting party with a written statement expressing the reason for
rejection, and be prepared to cite any sources of information that
went into that decision.
Subject Identifier Types need not be generally applicable and may be
highly specific to a particular domain; it is expected that types may
be registered for niche or industry-specific use cases. The Expert
Reviewer should focus on whether the type is thoroughly documented,
and whether its registration will promote or harm interoperability.
In most cases, the Expert Reviewer should not approve a request if
the registration would contribute to confusion, or amount to a
synonym for an existing type.
6.2. Well-Known URI Registry
TODO: follow steps in Section 5.1 of [RFC5785] to send a registration
request.
This specification registers the well-known URI defined in Section 3
in the IANA Well-Known URI registry defined in [RFC5785].
6.2.1. Registry Contents
o URI suffix: "risc-configuration"
o Change controller: OpenID Foundation RISC Working Group - openid-
specs-risc at lists.openid.net
o Specification document: Section 3 of this document
o Related information: (none)
7. Privacy Considerations
7.1. Subject Information Leakage
Event issuers and recipients SHOULD take precautions to ensure that
they do not leak information about subjects via Subject Identifiers,
and choose appropriate Subject Identifier Types accordingly. Parties
SHOULD NOT identify a subject using a given Subject Identifier Type
if doing so will allow the recipient to correlate different claims
about the subject that they are not known to already have knowledge
of. Issuers and recipients SHOULD always use the same Subject
Identifier Type and the same claim values to identify a given subject
Scurtescu, et al. Expires October 26, 2018 [Page 32]
openid-risc-profile April 2018
when communicating with a given party in order to reduce the
possibility of information leakage.
8. References
8.1. Normative References
[BCP26] Cotton, M., Leiba, B., and T. Narten, "Guidelines for
Writing an IANA Considerations Section in RFCs", BCP 26,
RFC 8126, DOI 10.17487/RFC8126, June 2017,
<https://tools.ietf.org/html/rfc8126>.
[CLIENTCRED]
Hardt, D., Ed., "The OAuth 2.0 Authorization Framework -
Client Credentials Grant", RFC 6749, DOI 10.17487/RFC6749,
October 2012, <https://tools.ietf.org/html/
rfc6749#section-4.4>.
[DELIVERYPOLL]
Backman, A., Ed., Jones, M., Ed., Hunt, P., Ed.,
Scurtescu, M., Ansari, M., and A. Nadalin, "Poll-Based SET
Token Delivery Using HTTP", April 2018,
<https://tools.ietf.org/html/draft-ietf-secevent-http-
poll-00>.
[DELIVERYPUSH]
Backman, A., Ed., Jones, M., Ed., Hunt, P., Ed.,
Scurtescu, M., Ansari, M., and A. Nadalin, "Push-Based SET
Token Delivery Using HTTP", April 2018,
<https://tools.ietf.org/html/draft-ietf-secevent-http-
push-00>.
[E164] International Telecommunication Union, "The international
public telecommunication numbering plan", 2010,
<http://www.itu.int/rec/T-REC-E.164-201011-I/en>.
[IDTOKEN] Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., and
C. Mortimore, "OpenID Connect Core 1.0 - ID Token", April
2017, <http://openid.net/specs/
openid-connect-core-1_0.html#IDToken>.
[MGMTAPI] Scurtescu, M. and A. Backman, "Management API for SET
Event Streams", June 2017, <https://tools.ietf.org/html/
draft-scurtescu-secevent-simple-control-plane>.
Scurtescu, et al. Expires October 26, 2018 [Page 33]
openid-risc-profile April 2018
[OAUTH-DISCOVERY]
Jones, M., Sakimura, N., and J. Bradley, "OAuth 2.0
Authorization Server Metadata - Version 10", March 2018,
<https://tools.ietf.org/html/draft-ietf-oauth-discovery-
10>.
[OIDC-DISCOVERY]
Sakimura, N., Bradley, J., Jones, M., and E. Jay, "OpenID
Connect Discovery 1.0", November 2014,
<https://openid.net/specs/openid-connect-discovery-
1_0.html>.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997, <https://www.rfc-
editor.org/info/rfc2119>.
[RFC5785] Nottingham, M. and E. Hammer-Lahav, "Defining Well-Known
Uniform Resource Identifiers (URIs)", RFC 5785,
DOI 10.17487/RFC5785, April 2010, <https://www.rfc-
editor.org/info/rfc5785>.
[RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization
Framework: Bearer Token Usage", RFC 6750,
DOI 10.17487/RFC6750, October 2012, <https://www.rfc-
editor.org/info/rfc6750>.
[RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data
Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March
2014, <https://www.rfc-editor.org/info/rfc7159>.
[RFC7517] Jones, M., "JSON Web Key (JWK)", RFC 7517,
DOI 10.17487/RFC7517, May 2015, <https://www.rfc-
editor.org/info/rfc7517>.
[RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token
(JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015,
<https://www.rfc-editor.org/info/rfc7519>.
[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
May 2017, <https://www.rfc-editor.org/info/rfc8174>.
[SET] Hunt, P., Ed., Jones, M., Denniss, W., and M. Ansari,
"Security Event Token (SET)", April 2018,
<https://tools.ietf.org/html/draft-ietf-secevent-token-
09>.
Scurtescu, et al. Expires October 26, 2018 [Page 34]
openid-risc-profile April 2018
[USECASES]
Scurtescu, M., "Security Events RISC Use Cases", June
2017, <https://tools.ietf.org/html/draft-scurtescu-
secevent-risc-use-cases-00>.
8.2. URIs
[1] https://datatracker.ietf.org/wg/secevent/about/
Appendix A. Acknowledgements
Transmitter Configuration Discovery (Section 3) is based on both
OpenID Connect Discovery 1.0 [OIDC-DISCOVERY] and OAuth 2.0
Authorization Server Metadata [OAUTH-DISCOVERY].
Authors' Addresses
Marius Scurtescu
Google
Email: mscurtescu at google.com
Annabelle Backman
Amazon
Email: richanna at amazon.com
John Bradley
Yubico
Email: secevemt at ve7jtb.com
Scurtescu, et al. Expires October 26, 2018 [Page 35]
-------------- next part --------------
A non-text attachment was scrubbed...
Name: openid-risc-profile-1_0.xml
Type: text/xml
Size: 86285 bytes
Desc: not available
URL: <http://lists.openid.net/pipermail/openid-specs-risc/attachments/20180424/35f7c3fa/attachment-0005.xml>
More information about the Openid-specs-risc
mailing list