[Openid-specs-ab] Updated FastIDV Spec
William Denniss
wdenniss at google.com
Sun May 8 17:53:04 UTC 2016
I've updated the FastIDV spec based on the comments on this list, and our
deployment feedback.
Key changes:
1. Added new ID Token claims email_authority, and phone_number_authority
after discussion on-list.
2. Relaxing of the prohibition against "prompt=none", converted this to
being an OP choice (but have recommended OPs do employ a mitigation against
bulk programmatic access). We still don't support prompt=none in our
deployment, but enough have asked for it that I felt it reasonable to make
this an OP choice. I'm expecting to iterate further on that topic as more
people deploy and use FastIDV.
3. Added a section in the security considerations discussing the risks
of accepting OP claims other than 'sub'.
Github: https://github.com/williamdenniss/fastidv
HTML version available here: https://wdenniss.com/fastidv
And it's attached.
And with that, I'm on vacation for a week, but will respond to any comments
when I'm back :-)
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openid.net/pipermail/openid-specs-ab/attachments/20160508/d45558af/attachment.html>
-------------- next part --------------
OAuth Working Group W. Denniss
Internet-Draft Google
Intended status: Standards Track May 6, 2016
Expires: November 7, 2016
OpenID Connect Fast Identity Verification
draft-wdenniss-oidc-fastidv-01
Abstract
Fast Identity Verification is a technique that OpenID Connect
providers can implement to enable relying parties to verify identity
information they already know about a user, in a way that is
completely transparent to the user (provided they have an active
authentication session).
Status of This Memo
This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."
This Internet-Draft will expire on November 7, 2016.
Copyright Notice
Copyright (c) 2016 IETF Trust and the persons identified as the
document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License.
Denniss Expires November 7, 2016 [Page 1]
Internet-Draft oauth_mobile May 2016
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
2. Notational Conventions . . . . . . . . . . . . . . . . . . . 3
3. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3
4. The FastIDV Optimisation . . . . . . . . . . . . . . . . . . 3
4.1. Qualifying FastIDV Requests . . . . . . . . . . . . . . . 3
4.2. Processing FastIDV Requests . . . . . . . . . . . . . . . 4
5. OpenID Provider Discovery . . . . . . . . . . . . . . . . . . 5
6. Authoritative ID Token Claims . . . . . . . . . . . . . . . . 6
7. Privacy Considerations . . . . . . . . . . . . . . . . . . . 7
7.1. Confirming the Login State of the User . . . . . . . . . 7
7.2. Asserting Hinted Values . . . . . . . . . . . . . . . . . 7
7.3. Hint-to-sub Mapping . . . . . . . . . . . . . . . . . . . 7
8. Security Considerations . . . . . . . . . . . . . . . . . . . 8
8.1. Programmatic Detection of Signed-in Users . . . . . . . . 8
8.2. Cross-site forgery . . . . . . . . . . . . . . . . . . . 9
8.3. OP Asserted Claims . . . . . . . . . . . . . . . . . . . 9
8.4. Accepting email_verified and phone_number_verified claims 9
9. References . . . . . . . . . . . . . . . . . . . . . . . . . 9
9.1. Normative References . . . . . . . . . . . . . . . . . . 9
9.2. Informative References . . . . . . . . . . . . . . . . . 10
Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 10
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 10
1. Introduction
The OpenID Connect specification, as an identity layer on OAuth 2.0,
allows relying parties to get identity assertions from identity
providers. Typically the user is prompted to grant access to their
identity as part of the authentication flow.
In some cases, the relying party (RP) may already have identity
information about the user, such as their email address or phone
number which may have been supplied in an identifier first sign-in
flow, from an account chooser (such as AccountChooser.com), or in a
registration form. In these cases, it may be possible to not prompt
the user to consent to share identity information, as the relying
party already has that information.
If user consent is not required in certain specific circumstances,
OpenID Connect flows can be used seamlessly to verify the identity of
the supplied user by using their signed-in state at the identity
provider. This technique is referred to as FastIDV, and is the
subject of this specification.
By using the FastIDV pattern, OPs can enable email first flows with a
highly efficient user experience for federated sign-in. It also
Denniss Expires November 7, 2016 [Page 2]
Internet-Draft oauth_mobile May 2016
offers an alternative UX to traditional "verify your email address"
emails and "verify your phone number" SMS messages. Another
potential advantage over those traditional verification flows is that
if the provider supports account signals as being developed by the
OIDF RISK workgroup, then this FastIDV flow can be used to enable the
provider to remember that the site requesting the verification should
be notified of any account signals in the future.
2. 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 Key
words for use in RFCs to Indicate Requirement Levels [RFC2119]. If
these words are used without being spelled in uppercase then they are
to be interpreted with their normal natural language meanings.
3. Terminology
In addition to the terms defined in referenced specifications, this
document uses the following terms:
"OpenID Provider (OP)" OAuth 2.0 Authorization Server that is
capable of Authenticating the End-User and providing Claims to a
Relying Party about the Authentication event and the End-User.
"Relying Party (RP)" OAuth 2.0 Client application requiring End-User
Authentication and Claims from an OpenID Provider.
"FastIDV" Fast Identity Verification, an optimisation to OpenID
Connect that is the subject of this specification.
"FastIDV Request" An OpenID Connect request that qualifies for
FastIDV processing, as per Section 4.2
4. The FastIDV Optimisation
FastIDV enhances the Authorization Code, Implicit and Hybrid flows of
OpenID Connect with additional logic that if met means that the user
consent step can be bypassed.
4.1. Qualifying FastIDV Requests
FastIDV requests represent a subset of valid OpenID Connect requests.
Any invalid OpenID Connect request is by definition also invalid for
FastIDV. In addition to being a normal, valid, OpenID Connect
request, FastIDV requests must meet the following requirements:
Denniss Expires November 7, 2016 [Page 3]
Internet-Draft oauth_mobile May 2016
1. "login_hint" MUST be supplied.
2. "response_type" MUST be 'code', 'id_token', or both.
3. The scope 'openid' MUST be present.
4. One of the scopes 'email' and 'phone' MAY be present.
5. Scopes other than those listed above MAY also be present although
it is NOT RECOMMENDED for clients to supply them. Any such
scopes are referred to as 'Additional Scopes' for the purposes of
FastIDV.
6. If the 'email' or 'phone' scope is present, the login_hint
supplied MUST match that scope's format, i.e. the login_hint
should be an email address when 'email' is supplied, and a phone
number when 'phone' is supplied. Where the login_hint format
does not match these scopes, they are treated as Additional
Scopes.
7. Requests with the "prompt" parameter MAY be also excluded from
FastIDV handling at the OPs choice, per Section 8.1.2. It is
RECOMMENDED that the OPs choice in this regard is discoverable,
per Section 5.
OpenID Connect requests meeting the above requirements qualify as
"FastIDV Requests and can be processed per Section 4.2.
Requests that are not FastIDV Requests MUST be processed following
the OpenID Connect standard. The OP MUST NOT respond with a FastIDV
specific error message if an OpenID Connect request does not qualify
as a FastIDV Request.
4.2. Processing FastIDV Requests
4.2.1. Validating the FastIDV Request for the signed-in user
On receipt of a FastIDV Request, the OP performs the following
additional checks to see if the request is valid for the current
signed-in user state.
1. "login_hint" MUST match a valid, logged in user.
2. If a "login_hint" of type other than the subject identifier is
used, the OP MAY disqualify an otherwise valid FastIDV request if
hint-to-sub lookups are disallowed by policy (see Section 7 for a
non-normative discussion of the privacy implications of the hint-
Denniss Expires November 7, 2016 [Page 4]
Internet-Draft oauth_mobile May 2016
to-sub lookup). The policy choices of an OP regarding hint-to-
sub lookups is outside the scope of this specification.
3. If the request contains Additional Scopes, as defined by
Section 4.1, the OP SHOULD disqualify an otherwise valid FastIDV
request if proper user consent has not been previously obtained
for those scopes, as per the policy of the OP. The exact policy
for handling of Additional Scopes within FastIDV Requests is
outside the scope of this specification.
4.2.2. Processing Valid FastIDV Requests
If the FastIDV Request isn't invalidated by the above checks, then
the OP SHOULD process the request according to the OpenID Connect
specification but without an interactive dialog (as defined in
3.1.2.4., and referenced in sections 3.2.2.4. and 3.3.2.4.) that
interrupts the flow.
FastIDV supporting OPs MAY prompt the user even on a valid FastIDV
request, if they determine it is needed for any reason. It is
expected however, by declaring support for this standard, that OPs do
not present an interactive dialog in normal circumstances for valid
FastIDV requests.
4.2.3. Processing Invalid FastIDV Requests
If the FastIDV request was invalidated, it MUST be processed
according to the OpenID Connect standard as usual. The OP MUST NOT
respond with a FastIDV specific error message if an OpenID Connect
request was disqualified as a FastIDV Request.
It is a common case for users to be signed-out of the OP, thus it is
expected for honest clients attempting to use FastIDV to hint
identifiers for users that are not signed-in. When the user
specified by 'login_hint' is not signed-in, the OP SHOULD redirect to
a sign-in page, reverting to normal OpenID Connect protocol behavior.
It is RECOMMENDED that the 'login_hint' is used to optimise the sign-
in experience (for example, by pre-filling the email address field).
5. OpenID Provider Discovery
If the OP supports OpenID Connect Discovery, it uses this metadata
value to advertise its support for Fast Identity Verification:
"fastidv_supported" OPTIONAL. Boolean value specifying whether the
OP supports Fast Identity Verification, with true indicating
support (and compliance with this specification). If omitted, the
default value is false.
Denniss Expires November 7, 2016 [Page 5]
Internet-Draft oauth_mobile May 2016
"fastidv_prompt_supported" OPTIONAL. Boolean value specifying
whether the OP supports Fast Identity Verification requests that
include the "prompt" param.
"fastidv_scopes" OPTIONAL. String value specifying the list of
scopes the OP supports for FastIDV, any combination of 'openid',
'email' and 'phone'. Multiple scope values are separated by
spaces. The OP MUST support login_hint formats that match scopes
declared here. For example "openid email" implies that
login_hints in the form of either the OpenID Connect subject
identifier ('sub'), or email will be accepted.
6. Authoritative ID Token Claims
One of the reasons for FastIDV is to avoid a manual identity
verification. In order to skip manual identity verification but
achieve the same end result (an assurance that the identity does
currently belong to the user), the OP must be authoritative for the
identity information being asserted. Merely having validated that
information in the past may not always be good enough, see
Section 8.4. The claims below provide a way to communicate the
authoritative status of the identity information, within the trust
framework established by the OP and RP.
email_authority: True if the OP authoritatively represents the End-
User's email address; otherwise false. When this Claim Value
is true, the OP asserts that the End-User is in control of the
e-mail account, and thus would be the same person who would
receive an email to the account if it was sent at that moment.
For example, OPs that manage the mailbox of the e-mail address
are considered authoritative, as are OPs contracted by the
owner of the mailbox to provide identity services. The exact
logic to determine whether the OP is authoritative is dependent
upon the trust framework or contractual agreements within which
the parties are operating.
phone_number_authority: True if the OP authoritatively represents
the End-User's phone number; otherwise false. When this Claim
Value is true, the OP asserts that the End-User is in control
of the phone number, and thus would be the same person who
would receive an sms or call to the number if it was made at
that moment. For example, OPs that manage the line service of
the phone number are considered authoritative, as are OPs
contracted by the owner of the phone line to provide identity
services. The exact logic to determine whether the OP is
authoritative is dependent upon the trust framework or
contractual agreements within which the parties are operating.
Denniss Expires November 7, 2016 [Page 6]
Internet-Draft oauth_mobile May 2016
7. Privacy Considerations
The following is a non-normative discussion of the privacy
considerations with by-passing user consent for OpenID Connect
requests that qualify for FastIDV handling.
7.1. Confirming the Login State of the User
Successful FastIDV requests result in the login state of the user
being revealed. FastIDV does not explicitly confirm the negative
(that the user was not logged in), though it can be roughly inferred
by the lack of a response.
Typically the user supplied their account identifier to the RP with
the intent to sign-in or verify their identity at the RP, which is
what prompted the RP to initiate the FastIDV flow. Thus, the RP
confirming the signed-in state of the user using the identifier they
supplied is reasonable behavior.
OPs that do not wish to reveal the sign-in state of a user based on a
hint supplied by the RP SHOULD NOT implement this spec. In that
case, the OP should evaluate what visual experience their users will
encounter if an RP uses an account chooser like AccountChooser.com.
Users may be confused if they feel they used an account chooser to
consent to sharing their identifier with a site, but are then "asked
again" to consent on another page.
7.2. Asserting Hinted Values
ID Tokens contain user information beyond the simple fact that the
user is logged in, such as their 'sub' and in some cases 'email' and
'phone' identifiers. Typically this information is not revealed via
OpenID Connect without user consent. In the case of FastIDV however,
the RP has given the identifiers to the OP in the form of the
login_hint, and thus when the ID Token contains this information, it
is not new information for the RP.
As the RP already has access to the information they hinted, the OP
does not need additional consent to return that same information as
claims in an ID Token.
7.3. Hint-to-sub Mapping
When FastIDV is used with the 'email' or 'phone' login_hint types,
the 'sub' is still included in the ID Token despite that fact that
this identifier was not hinted by the RP.
Denniss Expires November 7, 2016 [Page 7]
Internet-Draft oauth_mobile May 2016
For some OPs, hint-to-sub mapping with FastIDV is not a concern, as
hint-to-sub lookups are already supported in an unauthenticated
fashion. For example, an email provider may already support the
looking up of a user's profile page when an email is supplied, to
enrich the email composition experience.
OPs that return a client-specific subject identifier (also known as a
directed identifier) would normally be unconcerned with providing
hint-to-sub mapping, as the identifier is only useful the context of
that client.
The exact policy of revealing the 'sub' to RPs who know other user
identifiers varies from OP to OP, and is outside the scope of this
specification. OPs who do not support hint-to-sub lookups for
particular login_hint types, may chose to disqualify FastIDV requests
for the unsupported login_hint types as per Section 4.2, and process
them as normal OpenID Connect requests instead.
OPs that support OpenID Connect Discovery SHOULD declare the scopes
that match the login_hint types they support in their OpenID Connect
discovery document as per Section 5.
8. Security Considerations
8.1. Programmatic Detection of Signed-in Users
A risk of FastIDV is that a relying party could potentially query the
OP with a large list of email addresses, in order to scan for a
currently signed-in user. This can be mitigated in a number of ways.
8.1.1. Rate Limiting
Rate limiting of FastIDV requests is RECOMMENDED to mitigate the risk
of a rogue RP attempting to programmatically detect users.
8.1.2. Handling of 'prompt=none'
For OPs that don't rate limit FastIDV requests, an alternative
simpler mitigation is to disqualify all requests with a "prompt"
parameter during the FastIDV evaluation (Section 4.1). For such OPs,
they would never return an error for a FastIDV qualified request they
would either return a success response, or redirect the user to a
prompt. This doesn't prevent normal use of "prompt", with such OPs,
it just means that FastIDV processing should not apply to those
requests.
Denniss Expires November 7, 2016 [Page 8]
Internet-Draft oauth_mobile May 2016
8.1.3. Preventing use in iframes
To prevent a malicious RP using hidden iframes to execute multiple
requests looking for a success response, the Authorization Endpoint
MUST set a X-Frame-Options header (as defined by [RFC7034]) on every
HTTP request to prevent the RP embedding the request. For example,
"X-Frame-Options: DENY".
8.2. Cross-site forgery
To protect against an unrelated party sending users through a FastIDV
flow, the 'state' MUST be used as recommended in Section 10.12 of
[RFC6749].
8.3. OP Asserted Claims
Any value for the "email" and "phone_number" claims may be asserted
by any OP. RPs must establish trust with the OPs in order to accept
any identity claims beyond ?sub?. The trust framework by which the
parties to the FastIDV transaction operate is out of scope for this
specification.
8.4. Accepting email_verified and phone_number_verified claims
Depending on the context that FastIDV is being used the
"email_verified" and "email_number_verified" may not be a strong
enough claim to actually skip a fresh manual verification of the
identity information, as these claims require only that the OP have
verified the information once in the past. Instead, the new claims,
defined in this spec "email_authority" and "email_number_authority"
can be used from trusted OPs to avoid the need for a fresh
verification.
9. References
9.1. Normative References
[RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework",
RFC 6749, DOI 10.17487/RFC6749, October 2012,
<http://www.rfc-editor.org/info/rfc6749>.
[OIDC.Core]
Sakimura, N., Ed., Bradley, J., Jones, M., de Medeiros,
B., and C. Mortimore, "OpenID Connect Core 1.0
incorporating errata set 1", February 2015,
<http://openid.net/specs/openid-connect-core-1_0.html>.
Denniss Expires November 7, 2016 [Page 9]
Internet-Draft oauth_mobile May 2016
[RFC7034] Ross, D. and T. Gondrom, "HTTP Header Field X-Frame-
Options", RFC 7034, DOI 10.17487/RFC7034, October 2013,
<http://www.rfc-editor.org/info/rfc7034>.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997,
<http://www.rfc-editor.org/info/rfc2119>.
9.2. Informative References
[RFC6819] Lodderstedt, T., Ed., McGloin, M., and P. Hunt, "OAuth 2.0
Threat Model and Security Considerations", RFC 6819,
DOI 10.17487/RFC6819, January 2013,
<http://www.rfc-editor.org/info/rfc6819>.
Appendix A. Acknowledgements
The author would like to acknowledge the contributions of the
following individuals: Adam Dawes, Breno de Medeiros, Eric Sachs,
Mengcheng Duan, Michael Dietz, Naveen Agarwal, Steven Soneff, John
Bradley, Nat Sakimura, Mike Jones.
Author's Address
William Denniss
Google
1600 Amphitheatre Pkwy
Mountain View, CA 94043
USA
Phone: +1 650-253-0000
Email: wdenniss at google.com
URI: http://google.com/
Denniss Expires November 7, 2016 [Page 10]
-------------- next part --------------
A non-text attachment was scrubbed...
Name: draft-wdenniss-fastidv.xml
Type: text/xml
Size: 23938 bytes
Desc: not available
URL: <http://lists.openid.net/pipermail/openid-specs-ab/attachments/20160508/d45558af/attachment.xml>
More information about the Openid-specs-ab
mailing list