OpenID Connect User Questioning API 1.0
Orangenicolas.aillery@orange.comOrangecharles.marais@orange.comOpenID MODRNA Working GroupThis specification defines a specific endpoint used by a Client (i.e. Service Provider)
in order to question an End-User and get his Statement (i.e. his answer).This specification defines a specific endpoint used by a Client (i.e. Service Provider)
in order to question an End-User and get his Statement (i.e. his answer).This endpoint is specified as an OAuth 2.0-protected Resource Server accessible with an Access Token.The way the Access Token has been obtained by the Client is out of scope of this specification.Whether the End-User is currently using the Client or not is also out of scope of this specification.The User Questioning API is an asynchronous API. There are 2 main ways to get the End-User's Statement: the first one requires some polling of the API and the second requires the Client to expose a callback endpoint.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in .
Throughout this document, values are quoted to indicate that they are
to be taken literally. When using these values in protocol messages, the
quotes MUST NOT be used as part of the value.
All uses of JSON Web Signature (JWS)
and JSON Web Encryption (JWE)
data structures in this specification utilize
the JWS Compact Serialization or the JWE Compact Serialization;
the JWS JSON Serialization and the JWE JSON Serialization are not used.
This specification uses the terms "Access Token", "Resource Server", and "Client" defined by OAuth 2.0,
the terms "JSON Web Token (JWT)", "JWT Claims Set", and "Nested JWT" defined by JSON Web Token (JWT),
and the terms "Header Parameter" and "JOSE Header" defined by JSON Web Signature (JWS).
This specification also defines the following terms:
End-User receiving the question and requested to give his statement.
The User Questioning protocol, in abstract, follows the following steps.The Client sends a User Questioning Request to the OpenID Provider (OP).The OP interacts with the Questioned User and obtains his Statement.The OP responds to the Client with a User Questioning Response.The following use cases are non-normative examples to illustrate the usage of the User Questioning API by a Client.The Client can be a bank and the User Questioning API can be used to challenge the End-User when he wants to pay on Internet in order to secure the transaction. This is similar to 3D-Secure. The question could be: "Do you allow a payment of x euros to party y? (Yes) (No)".
The Client can be a bank and the User Questioning API can be used to challenge the End-User when he wants to add a new payee for a bank transfer. The question could be: "Do you allow party y to be added to your payees? (I accept) (I refuse)".
The Client can be a drive-in food market and the User Questioning API can be used to ask the End-User if he accepts the exchange of one missing product by another. The question could be: "Do you agree to get product x instead of product y? (I agree) (I disagree)".
The Client can be a ticketing platform and the User Questioning API can be used to prevent transactions by bots. The question could be: "Do you confirm that you are currently booking a ticket? (I confirm) (I deny)".
The Client can be an airline company and the User Questioning API can be used to be sure that the End-User is notified of a delay. The question could be: "Your flight is postponed. Can you confirm that you are aware? (I read this)".
The Client can be a survey company and the User Questioning API can be used to get the End-User's choice. The question could be: "Which is your favorite brand? (brand_A) (brand_B) (brand_C)".
The User Questioning API should be used when the following contraints must be fulfilled:The Client needs to have a real-time interaction with an offline End-User.
The Client needs to have the End-User's statement on a given question.
The Client needs to be sure that the responding End-User has been authenticated before responding.
The Client needs to have a non-repudiable proof of the End-User's statement.
The Client needs the End-User's statement to enforce a policy (i.e. take a decision).
The User Statement Token is a security token that contains Claims about the statement made by the Questioned User.
The User Statement Token is represented as a JSON Web Token (JWT).
The following Claims are used within the User Statement Token in all Questioning API flows.
MANDATORY.
The question_id is a unique identifier of the Question.
The question_id value is a case sensitive string.
MANDATORY.
Issuer Identifier for the Issuer of the response.
The iss value is a case-sensitive URL using the https scheme that contains scheme, host, and optionally, port number and path components and no query or fragment components.
MANDATORY.
Audience(s) that this User Statement Token is intended for.
It MUST contain the OAuth 2.0 client_id of the Relying Party as an audience value.
It MAY also contain identifiers for other audiences. In the general case, the aud value is an array of case-sensitive strings.
In the common special case when there is one audience, the aud value MAY be a single case-sensitive string.
MANDATORY.
Subject Identifier.
A locally unique and never reassigned identifier within the Issuer for the End-User, which is intended to be consumed by the Client, e.g. g117YBtCZO3mAKPQKP8o.
It MUST NOT exceed 255 ASCII characters in length.
The sub value is a case-sensitive string.
OPTIONAL. The user_id is present in the User Statement Token only if the user_id and user_id_type were present in the User Questioning Request.
The user_id is a unique identifier allowing to identify the Questioned User (e.g. Mobile phone, sub, ...).
The user_id value is a case sensitive string.
OPTIONAL. The user_id_type is present in the User Statement Token only if the user_id and user_id_type were present in the User Questioning Request.
The user_id_type indicates the type of the End-User's identifier used for User Questioning.
The user_id_type value is a case sensitive string.
MANDATORY.
The question_displayed is the question displayed to the Questioned User.
If the question_to_display has not been displayed as is, the question_displayed MUST be the exact message displayed to Questioned User.
The question_displayed value is a case sensitive string.
MANDATORY. Statement made by the User Questioning.
The statement SHALL be the exact statement made by the Questioned User.
The statement value is a case sensitive string.
MANDATORY. Date indicating when the End-User gave his Statement on the Question.
The statement_date value is a JSON number representing the number of seconds from 1970-01-01T0:0:0Z as measured in UTC.
MANDATORY. Questioning Context Class Reference.
Questioning Context Class Reference value that identifies the Authentication Context Class used by the OP to authenticate the Questioned User before he made his statement.
The used_qcr value is a case sensitive string.
MANDATORY. Questioning Method Reference.
This is the authentication method used by the OP to authenticate the Questioned User before he made his statement.
The used_qmr value is a case sensitive string.
User Statement Tokens MUST be signed using JWS and optionally both signed and then
encrypted using JWS and JWE respectively, thereby providing
authentication, integrity,
non-repudiation, and optionally, confidentiality,
per .
If the User Statement Token is encrypted, it MUST be signed then encrypted,
with the result being a Nested JWT, as defined in .
User Statement Tokens MUST NOT use none
as the alg value.
User Statement Tokens SHOULD NOT use the JWS or JWE
x5u,
x5c,
jku, or
jwk
Header Parameter fields.
Instead, references to keys used are
communicated in advance using Discovery and Registration parameters,
per .
In order to use the User Questioning API, the Client should:
MANDATORY.
The right for a Client to access the User Questioning API is the right to use the User Questioning API's scope. This scope value is question.
OPTIONAL.
If the Client wants to be notified of the User Question Response (cf. ), it MUST register its client_notification_endpoint. The client_notification_endpoint is a callback URL on the Client.
This document specifies two User Questioning flows:
In this flow, after the User Questioning Request, the Client must call the OP in order to get the User Questioning Response. Refer to for more details.
In this flow, after the User Questioning Request, the OP calls the Client to deliver the User Questioning Response. Refer to for more details.
The flow a Client will use is configured at registration. Refer to for more details.
In this flow, the Client will poll the OP to get the User Statement Token.
About the "(2a) User interactions to get the Questioned User's Statement" step, note that the way the OP obtains the Questioned User's Statement is out of the scope of this specification.
In this flow, the OP will send the User Statement Token on the client_notification_endpoint registered by the Client.
About the "(2a) User interactions to get the Questioned User's Statement" step, note that the way the OP obtains the Questioned User's Statement is out of the scope of this specification.
The Client sends the User Questioning Request using an HTTP POST Request.
The Client MUST have a valid Access Token for the scope question.
The HTTP POST request contains the following header:
MANDATORY.
The Authorization value is an Access Token obtained from an OAuth Authorization request and used as a Bearer Token.
The Authorization value is a case sensitive string.
The User Questioning Request MUST contain a JSON structure in the body of the HTTP POST, with the following attributes:
MANDATORY if the Client uses the Pushed-To-Client Flow described in . IGNORED otherwise.
The client_notification_token is an opaque token issued by the Client.
The client_notification_token is Bearer Token used by the Client to authorize the OP when the OP sends the User Questioning Response to the Client Notification Endpoint.
The client_notification_token value is a case sensitive string.
FORBIDDEN if the Access Token is tied with an End-User, MANDATORY if the Access Token is not tied with an End-User.
The user_id is a unique identifier allowing to identify the Questioned User (e.g. Mobile phone, sub, ...).
The user_id value is a case sensitive string.
FORBIDDEN if the Access Token is tied with an End-User, MANDATORY if the Access Token is not tied with an End-User.
The user_id_type indicates the type of the End-User's identifier used for User Questioning.
The user_id_type value is a case sensitive string.
MANDATORY.
The question_to_display is the question to be displayed to the Questioned User.
The question_to_display SHALL be displayed with no modification to Questioned User. If some modifications occur, it MUST be due to restrictions imposed by the Questioning Method.
The question_to_display value is a case sensitive string.
MANDATORY.
The statements_to_display is the list of possible statements to be displayed to the Questioned User.
The statements_to_display SHALL be displayed with no modification to Questioned User.
The statements_to_display value is a JSON array of case sensitive strings.
MANDATORY. Questioning Context Class Reference.
The wished_qcr is Questioning Context Class Reference value that identifies the Authentication Context Class to be used by the OP to authenticate the Questioned User before he made his statement.
The wished_qcr value is a case sensitive string.
OPTIONAL. Questioning Method Reference.
The wished_qmr is the authentication method to be used by the OP to authenticate the Questioned User before he made his statement.
The wished_qmr value is a case sensitive string.
The parameters are included in the entity-body of the HTTP POST
using the "application/json" media type as defined by . The
parameters are serialized into a JavaScript Object Notation (JSON)
structure by adding each parameter at the highest structure level.
Parameter names and string values are included as JSON strings.
Numerical values are included as JSON numbers. The order of
parameters does not matter and can vary.
The user_id is an identifier used to identify the Questioned User and to retrieve a reachability mean.
If the user_id is a reachability identifier, it SHOULD be used by reachability mean.
user_id_type member can take the following values:
If the user_id_type value is msisdn,
the user_id value is the mobile phone number corresponding to the Questioned User.
E.164
is RECOMMENDED as the format of this Claim,
for example, +1 (425) 555-1212
or +5626872400.
If the user_id_type value is email,
the user_id value is the email adress corresponding to the Questioned User.
Its value MUST conform to the RFC 5322 addr-spec syntax.
If the user_id_type value is sub,
the user_id value is the sub corresponding to the Questioned User for the requesting client_id.
A successful response to the User Questioning Request is a HTTP 201 Created response.
The HTTP 201 Created response contains the following headers:
MANDATORY.
The Location value is a unique polling URL for the Question.
The Location value is a URL on the User Questioning Polling Endpoint.
MANDATORY.
The Question_id contains the question_id value.
The Question_id value is a case sensitive string.
The Client receives the error in a HTTP 400 Bad Request.The response body contains an error_info JSON structure as defined in .The error_info JSON structure can contain the following error codes, defined in :
invalid_requestno_suitable_methodunknown_userunreachable_userIn order to detect that User Questioning Response is ready, the Client MUST request the User Questioning Polling Endpoint.
If User Questioning Response is ready, it will be returned in the response.
Else, the OP responds with HTTP 304 Not Modified.
A Client configured with a client_notification_endpoint MUST NOT sent a request to the User Questioning Polling Endpoint.
The Client get the User Questioning Response using HTTP GET.
The HTTP GET request contains the following headers:
MANDATORY.
The Authorization value is an Access Token obtained from an OAuth Authorization request and used as a Bearer Token.
The Authorization value is a case sensitive string.
The Client_timeout indicates how much time, in seconds, the Client will wait for a HTTP response.
The Client_timeout value is a number.
If the User Questioning Response is not ready, the Client will get a HTTP 304 Not Modified.
The Client receives the successful User Questioning Response in a HTTP 200 OK response.The successful User Questioning Response is a JSON object, with the following attributes.
MANDATORY.
The question_id is a unique identifier of the Question.
The question_id value is a case sensitive string.
MANDATORY.
The user_statement_token is a User Statement Token as described in
The parameters are included in the entity-body of the HTTP 200 OK
using the "application/json" media type as defined by . The
parameters are serialized into a JavaScript Object Notation (JSON)
structure by adding each parameter at the highest structure level.
Parameter names and string values are included as JSON strings.
Numerical values are included as JSON numbers. The order of
parameters does not matter and can vary.
The Client receives the error in a HTTP 400 Bad Request.The response body contains an error_info JSON structure as defined in .The error_info JSON structure can contain the following error codes, defined in :
duplicate_requestsforbiddenhigh_rate_clienthigh_rate_questioninvalid_question_idinvalid_requesttimeoutuser_refused_to_answer
The OP sends the User Questioning Response to the Client using HTTP POST.
The User Questioning Response is a JSON object.
The User Questioning Response contains a status attribute that indicates if the User Questioning Response is successful or not.
The OP sends the User Questioning Response to the Client using HTTP POST.
The HTTP POST request contains the following header:
MANDATORY.
The Authorization value is the client_notification_token specified in the User Questioning Request and used as a Bearer Token.
The Authorization value is a case sensitive string.
A successful User Questioning Response is a JSON object, with the following attributes.
MANDATORY.
The question_id is a unique identifier of the Question.
The question_id value is a case sensitive string.
MANDATORY.
Status of the User Questioning Response.
When the User Questioning Response is successful, the value of status is ok.
MANDATORY.
The user_statement_token is a User Statement Token as described in .
The OP sends the erroneous User Questioning Response to the Client using HTTP POST.
The HTTP POST request contains the following header:
MANDATORY.
The Authorization value is the client_notification_token specified in the User Questioning Request and used as a Bearer Token.
The Authorization value is a case sensitive string.
An erroneous User Questioning Response is a JSON object, with the following attributes.
MANDATORY.
The question_id is a unique identifier of the Question.
The question_id value is a case sensitive string.
MANDATORY.
Status of the User Questioning Response.
An erroneous User Questioning Response contains a status attribute with the value error.
MANDATORY.
An erroneous User Questioning Response contains a error_info JSON structure as defined in .
The error_info JSON structure can contain the following error codes, defined in :
timeoutuser_refused_to_answer
The acknowledgement MUST be a HTTP 200 OK. This HTTP response SHOULD be ignored by the OP.
error_info is a JSON object which contains the following properties:
REQUIRED. Code representing the error. See for possible values.
OPTIONAL. Human-readable ASCII encoded text description of the error.
OPTIONAL. URI of a web page that includes additional information about the error.
The parameters are serialized into a JavaScript Object Notation (JSON)
structure by adding each parameter at the highest structure level.
Parameter names and string values are included as JSON strings.
Numerical values are included as JSON numbers. The order of
parameters does not matter and can vary.
The error_info JSON structure can contain the following error codes:
The Client sent simultaneous requests to the User Questioning Polling Endpoint for the same question_id. This error is responded to oldest requests. The last request is processed normally.
The Client sent a request to the User Questioning Polling Endpoint whereas it is configured with a client_notification_endpoint.
The Client sent requests at a too high rate, amongst all question_id. Information about the allowed and recommended rates can be included in the error_description.
The Client sent requests at a too high rate for a given question_id. Information about the allowed and recommended rates can be included in the error_description.
The Client sent a request to the User Questioning Polling Endpoint for a question_id that does not exist or is not valid for the requesting Client.
The User Questioning Request is not valid.
There is no Questioning Method suitable with the User Questioning Request.
The Questioned User did not answer in the allowed period of time.
The Questioned User mentioned in the user_id attribute of the User Questioning Request is unknown.
The Questioned User mentioned in User Questioning Request (either in the Access Token or in the user_id attribute) is unreachable.
The Questioned User refused to give a statement to the question.
cf. OpenID Connect - chapter 10
TBD
cf. OpenID Connect - chapter 16.14
TBDThis document makes no requests of IANA.OpenID Connect Standard 1.0Nomura Research Institute, Ltd.Ping IdentityMicrosoftGoogleSalesforceIllumilaOpenID Connect Dynamic Client Registration 1.0Nomura Research Institute, Ltd.Ping IdentityMicrosoftOpenID Connect Discovery 1.0Nomura Research Institute, Ltd.Ping IdentityMicrosoftIllumilaJSON Web Token (JWT)MicrosoftPing IdentityNomura Research Institute, Ltd.JSON Web Signature (JWS)MicrosoftPing IdentityNomura Research Institute, Ltd.JSON Web Encryption (JWE)MicrosoftRTFM, Inc.Cisco Systems, Inc.ASCII format for Network InterchangeUniversity California Los Angeles (UCLA)E.164: The international public telecommunication numbering planInternational Telecommunication UnionThe following have contributed to the development of this specification.Copyright (c) 2014 The OpenID Foundation.
The OpenID Foundation (OIDF) grants to any Contributor, developer,
implementer, or other interested party a non-exclusive, royalty free,
worldwide copyright license to reproduce, prepare derivative works from,
distribute, perform and display, this Implementers Draft or
Final Specification solely for the purposes of (i) developing
specifications, and (ii) implementing Implementers Drafts and
Final Specifications based on such documents, provided that attribution
be made to the OIDF as the source of the material, but that such attribution
does not indicate an endorsement by the OIDF.
The technology described in this specification was
made available from contributions from various sources,
including members of the OpenID Foundation and others.
Although the OpenID Foundation has taken steps to help ensure
that the technology is available for distribution, it takes
no position regarding the validity or scope of any intellectual
property or other rights that might be claimed to pertain to
the implementation or use of the technology described in
this specification or the extent to which any license under
such rights might or might not be available; neither does it
represent that it has made any independent effort to identify
any such rights. The OpenID Foundation and the contributors
to this specification make no (and hereby expressly disclaim any)
warranties (express, implied, or otherwise), including implied
warranties of merchantability, non-infringement, fitness for
a particular purpose, or title, related to this specification,
and the entire risk as to implementing this specification is
assumed by the implementer. The OpenID Intellectual
Property Rights policy requires contributors to offer
a patent promise not to assert certain patent claims against
other contributors and against implementers. The OpenID Foundation invites
any interested party to bring to its attention any copyrights,
patents, patent applications, or other proprietary rights
that may cover technology that may be required to practice
this specification.
[[ To be removed from the final specification ]]-01 Initial draftAdded OIDF Standard Notice