Orange

nicolas.aillery@orange.com

Orange

charles.marais@orange.com

OpenID MODRNA Working Group 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 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. The Client can use the endpoint defined in this specification whether the End-User is currently using the Client or not. 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.

These steps are illustrated in the following diagram: +--------+ +--------+ | | | | | |----(1) User Questioning Request-------------->| | | | | | | | +--------+ | | | | | | | | | Client | | End- |<--(2) User interactions to get--->| OP | | | | User | the Questioned User's Statement | | | | | | | | | | +--------+ | | | | | | | |<----(3) 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 End-User that may not be currently using the Client. 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. This identifier is created by the OP. The question_id value is a case sensitive string. MANDATORY. Issuer Identifier for the Issuer of the response. iss is defined in chapter 2 of . The issuer is the OP. MANDATORY. Subject Identifier. sub is defined in chapter 2 of . MANDATORY. Audience(s) that this User Statement Token is intended for. aud is defined in chapter 2 of . 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, ...). When present, this is the identifier actually used to reach the Questioned User. 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. Authentication Method References. These are the authentication methods used by the OP to authenticate the Questioned User before he made his statement. Authentication Method References are defined in chapter 2 of , where they are named amr. The used_amr value is an array of case sensitive strings. MANDATORY. Authentication Context Class Reference. Authentication Context Class Reference value that identifies the Authentication Context Class used by the OP to authenticate the Questioned User before he made his statement. Authentication Context Class Reference is defined in chapter 2 of , where it is named acr. The used_acr value is a case sensitive string. User Statement Tokens MUST be signed by the OP using a digital signature as defined in JWS providing authentication, integrity and non-repudiation. The signature MUST be a digital signature. Message Authentication Codes (MACs) are FORBIDDEN. User Statement Tokens CAN optionally be both signed and then encrypted using JWS and JWE respectively, thereby providing authentication, integrity, non-repudiation, and 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, HS256, HS384 and HS512 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 . The signature MUST be verified by the Client.

The following is a non-normative example of the set of Claims (the JWT Claims Set) in a User Statement Token: { "question_id":"984dcc7d3d4d4b0f9f8022e344f9", "iss":"https://server.example.com", "aud":"s8V3wm8IXMW6TboazXZX", "sub":"g117YBtCZO3mAKPQKP8o", "user_id":"+33612345678", "user_id_type":"msisdn", "question_displayed":"Do you allow ...?", "statement":"Yes", "statement_date":1311282975, "used_acr":"2", "used_amr":"CLICK_OK" }

Signing the User Statement Token with the RS256 algorithm results in this Object value (with line wraps within values for display purposes only):

The following RSA public key, represented in JWK format, can be used to validate the Object signature in this example (with line wraps within values for display purposes only):

The user_id is an identifier used to identify the Questioned User and to retrieve a reachability mean. The user_id is determined from the User Questioning Request, either from the user_id attribute or from the Access Token. If the user_id is present in both the User Questioning Request and the Access Token, an error is raised. If the user_id is absent of both the User Questioning Request and the Access Token, an error is also raised. If the user_id is a reachability identifier, it SHOULD be used by reachability mean. Otherwise, the OP must use the user_id to determine a suitable reachability identifier. 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. Other user_id_type can be specified for specific use cases.

In order to use the User Questioning API, the Client MUST have the right to access the User Questioning API. 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. If the 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. If the client does not use the client notification, it MUST obtain the result by using the user questioning polling endpoint. Both mechanisms are mutual exclusive, i.e. a particular client_id can only be used with one of these mechanisms.

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.

+--------+ +--------+ | |---(1a) User Questioning Request-------------->| | | | | | | |<--(1b) Question Created-----------------------| | | | | | | | +--------+ | | | Client | | End- |<--(2a) User interactions to get-->| OP | | | | User | the Questioned User's Statement | | | | +--------+ | | | | | | | |--(3a) Get User Questioning Response---------->| | | | | | | |<---(3b) User Questioning Response-------------| | +--------+ +--------+

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 to the client_notification_endpoint registered by the Client.

+--------+ +--------+ | |---(1a) User Questioning Request-------------->| | | | | | | |<--(1b) Question Created-----------------------| | | | | | | | +--------+ | | | Client | | End- |<--(2a) User interactions to get-->| OP | | | | User | the Questioned User's Statement | | | | +--------+ | | | | | | | |<---(3a) User Questioning Response-------------| | | | | | | |---(3b) Acknowledgement----------------------->| | +--------+ +--------+

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.

Communication with the User Questioning Request Endpoint MUST utilize TLS. See Section 16.17 in for more information on using TLS.

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 MUST contain 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 . FORBIDDEN 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 amongst the values defined in . 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. OPTIONAL. Authentication Method Reference. The wished_amr is the authentication methods to be used by the OP to authenticate the Questioned User before he made his statement. Authentication Method References are defined in chapter 2 of , where they are named amr. The wished_amr value is an array of case sensitive strings. MANDATORY. Authentication Context Class Reference. The wished_acr is Authentication 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. Authentication Context Class Reference is defined in chapter 2 of , where it is named acr. The wished_acr 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 following is a non-normative example of the JSON structure. POST /questions HTTP/1.1 Host: server.client.com Accept: application/json Authorization: Bearer SlAV32hkKG Content-Type: application/json Content-Length: xxx { "client_notification_token":"vO4n2DAeRrcWE0VAlo4I", "user_id":"+33612345678", "user_id_type":"msisdn", "question_to_display":"Do you allow ...?", "statements_to_display":["Yes","No"], "wished_acr":"3", "wished_amr":"PIN_OK" }

A successful response to the User Questioning Request is a HTTP 200 OK response. The HTTP 200 OK response contains the following headers: OPTIONAL. The Location value is a unique polling URL for the Question. The Location value is a URL on the User Questioning Polling Endpoint. When the Client is configured to use the Pushed-to-Client flow, this URL MUST be ignored by the Client. When the Client is configured to use the Pull-by-Client flow, if present, this URL MUST be used by the Client. If absent, the Client MUST use the question_id contained in the header Question_id and use it as a parameter to the user_questioning_polling_endpoint retrieved using . MANDATORY. The Question_id contains the question_id value. The Question_id value is a case sensitive string.

The following is a non-normative example of the JSON structure. HTTP/1.1 200 OK Location: https://server.example.com/questions_polling/984dcc7d3d4d4b0f9f8022e344f9 Question_id: 984dcc7d3d4d4b0f9f8022e344f9

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_request no_suitable_method unknown_user unreachable_user

The following is a non-normative example of error in a HTTP 400 Bad Request. This example can occur in the Pulled-By-Client flow (cf. ) and Pushed-To-Client flow (cf. ). HTTP/1.1 400 Bad Request Content-Type: application/json Content-Length: xxx { "error_code":"invalid_request", "error_description":"user_id is FORBIDDEN if the Access Token is tied with an End-User", "error_uri":"https://server.example.com/errors/invalid_request" }

In 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. Communication with the User Questioning Polling Endpoint MUST utilize TLS. See Section 16.17 in for more information on using TLS. 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 MUST contain 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.

The following is a non-normative example. GET /questions_polling/984dcc7d3d4d4b0f9f8022e344f9 HTTP/1.1 Host: server.example.com Accept: application/json Authorization: Bearer SlAV32hkKG Client_timeout: 10

If the User Questioning Response is not ready, the Client will get a HTTP 304 Not Modified.

The following is a non-normative example. HTTP/1.1 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 SHOULD check that the question_id in the User Questioning Response is the same as the question_id in the user_statement_token.

The following is a non-normative example. HTTP/1.1 200 OK Content-Type: application/json Content-Length: xxx { "question_id":"984dcc7d3d4d4b0f9f8022e344f9", "user_statement_token":"eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImt pZCI6ImsyYmRjIn0.eyJxdWVzdGlvbl9pZCI6Ijk4NGRjYzdkM2Q0ZDRiMGY5Zj gwMjJlMzQ0ZjkiLCJpc3MiOiJodHRwczovL3NlcnZlci5leGFtcGxlLmNvbSIsI mF1ZCI6InM4VjN3bThJWE1XNlRib2F6WFpYIiwic3ViIjoiZzExN1lCdENaTzNt QUtQUUtQOG8iLCJ1c2VyX2lkIjoiKzMzNjEyMzQ1Njc4IiwidXNlcl9pZF90eXB lIjoibXNpc2RuIiwicXVlc3Rpb25fZGlzcGxheWVkIjoiRG8geW91IGFsbG93IC 4uLj8iLCJzdGF0ZW1lbnQiOiJZZXMiLCJzdGF0ZW1lbnRfZGF0ZSI6MTMxMTI4M jk3NSwidXNlZF9hY3IiOiIyIiwidXNlZF9hbXIiOiJDTElDS19PSyJ9.vj5DOJA ZPE3-t0GmBMvaoKE8QB1VQYz94-nXbP5bUkwE9BYwixbU0sFxhmabRbEZgrEmhJ p1LFNw6OMPDlJsUHPgnqo_NbrxcmRYxpz07dKMLcOk8SbGcyL3eRPG-wiT0PCbx OFw9qjrjFJHCTFdkGfTnuyf0cOia9oEInTN49dPt_WkL1JHgs9SkjAUUlY9zcQc 9KMjwjcXGN2Z6ypNHu0jZXdplm3CIaxc7vSa0eHZrimCg4PSwAhuFoe7SbquLcV U56Bl4PvBBv6jGBtHW7O2Mo-ZhdoLeHqBOPWe707Wd0spbV1aekNdw8LB_ID-Ts OsWTQn7S8NfsFkk1dZXw" }

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_requests forbidden high_rate_client high_rate_question invalid_question_id invalid_request timeout user_refused_to_answer

The following is a non-normative example of error in a HTTP 400 Bad Request. This example can occur in the Pulled-By-Client flow (cf. ) and Pushed-To-Client flow (cf. ). HTTP/1.1 400 Bad Request Content-Type: application/json Content-Length: xxx { "error_code":"duplicate_requests", "error_description":"A newer request was sent for this question_id", "error_uri":"https://server.example.com/errors/invalid_request" }

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. Communication with the Client Notification Endpoint MUST utilize TLS. See Section 16.17 in for more information on using TLS.

The OP sends the User Questioning Response to the Client using HTTP POST. The HTTP POST request MUST contain 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 Client SHOULD check that the question_id in the User Questioning Response is the same as the question_id in the user_statement_token.

The following is a non-normative example. POST /notification HTTP/1.1 Host: client.example.com Content-Type: application/json Authorization: Bearer vO4n2DAeRrcWE0VAlo4I Content-Length: xxx { "question_id":"984dcc7d3d4d4b0f9f8022e344f9", "status":"ok", "user_statement_token":"eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImt pZCI6ImsyYmRjIn0.eyJxdWVzdGlvbl9pZCI6Ijk4NGRjYzdkM2Q0ZDRiMGY5Zj gwMjJlMzQ0ZjkiLCJpc3MiOiJodHRwczovL3NlcnZlci5leGFtcGxlLmNvbSIsI mF1ZCI6InM4VjN3bThJWE1XNlRib2F6WFpYIiwic3ViIjoiZzExN1lCdENaTzNt QUtQUUtQOG8iLCJ1c2VyX2lkIjoiKzMzNjEyMzQ1Njc4IiwidXNlcl9pZF90eXB lIjoibXNpc2RuIiwicXVlc3Rpb25fZGlzcGxheWVkIjoiRG8geW91IGFsbG93IC 4uLj8iLCJzdGF0ZW1lbnQiOiJZZXMiLCJzdGF0ZW1lbnRfZGF0ZSI6MTMxMTI4M jk3NSwidXNlZF9hY3IiOiIyIiwidXNlZF9hbXIiOiJDTElDS19PSyJ9.vj5DOJA ZPE3-t0GmBMvaoKE8QB1VQYz94-nXbP5bUkwE9BYwixbU0sFxhmabRbEZgrEmhJ p1LFNw6OMPDlJsUHPgnqo_NbrxcmRYxpz07dKMLcOk8SbGcyL3eRPG-wiT0PCbx OFw9qjrjFJHCTFdkGfTnuyf0cOia9oEInTN49dPt_WkL1JHgs9SkjAUUlY9zcQc 9KMjwjcXGN2Z6ypNHu0jZXdplm3CIaxc7vSa0eHZrimCg4PSwAhuFoe7SbquLcV U56Bl4PvBBv6jGBtHW7O2Mo-ZhdoLeHqBOPWe707Wd0spbV1aekNdw8LB_ID-Ts OsWTQn7S8NfsFkk1dZXw" }

The OP sends the erroneous User Questioning Response to the Client using HTTP POST. The HTTP POST request MUST contain 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 : timeout user_refused_to_answer

The following is a non-normative example. POST /notification HTTP/1.1 Host: client.example.com Content-Type: application/json Authorization: Bearer vO4n2DAeRrcWE0VAlo4I Content-Length: xxx { "question_id":"984dcc7d3d4d4b0f9f8022e344f9", "status":"error", "error_info": { "error_code":"unknown_user", "error_description":"The user is unknown", "error_uri":"https://server.example.com/errors/unknown_user" } }

The acknowledgement MUST be a HTTP 200 OK. This HTTP response SHOULD be ignored by the OP.

The following is a non-normative example. HTTP/1.1 200 OK

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. Human-readable ASCII text providing additional information, used to assist the client developer in understanding the error that occurred. Values for the "error_description" parameter MUST NOT include characters outside the set %x20-21 / %x23-5B / %x5D-7E. OPTIONAL. A URI identifying a human-readable web page with information about the error, used to provide the client developer with additional information about the error. Values for the "error_uri" parameter MUST conform to the URI-reference syntax and thus MUST NOT include characters outside the set %x21 / %x23-5B / %x5D-7E. 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 following is a non-normative example. { "error_code":"unknown_user", "error_description":"The user is unknown", "error_uri":"https://server.example.com/errors/unknown_user" }

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. The request is missing a required parameter, includes an unsupported parameter value (other than grant type), repeats a parameter, includes multiple credentials, utilizes more than one mechanism for authenticating the client, or is otherwise malformed. 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.

In order to interact with the Questioned User, the OP has to implement at least one questioning method. A questioning method has three purposes: authenticating the Questioned User, displaying the question and saving the Question User's statement. The authentication method and the associated level of assurance are refered by the AMR and ACR attributes. There is no specific attribute to describe how the question was displayed and how the statement was saved. However, the OP is responsible to display the question as it is. If the question has be modified, the displayed question MUST be returned to the Client as it was displayed, in the displayed_question attribute of the User Statement Token. In the same logic, the Questioned User's statement MUST be returned to the Client as it was displayed, in the statement attribute of the User Statement Token. The fact that a User Questing Request and an Authentication Request (as defined in ) are handled using the same AMR does not mean that the same mechanism instance is used. It only means that the authentication method is the same. For instance, if the AMR value is SMS_URL is used, the URL contained in the SMS can refer to two different components. It can also refer to a unique component able to handle both User Questioning Requests and Authentication Requests. If an OP can not display a question or the statements, it MUST return an error. To prevent these errors, it can inform the Clients of its limitation and limit the possible questions or statements. For instance, if the mechanism used for User Questioning can only display a question of limited size with only two predefined statements, the Client SHOULD send a User Questioning Request with a question_to_display limited in size and the two predefined statements as statements_to_display values.

In the User Questioning Request, the wished_amr value is a list of authentication methods. The OP SHOULD choose some of these authentication methods in order to achieve the wished_acr. The OP CAN also decide to either use other authentication methods or achieve another Authentication Context Class Reference as the one specified in wished_acr. The used authentication methods MUST be stated in used_amr and the achieved Authentication Context Class Reference MUST be stated in used_acr of the USer Statement Token.

In order to validate the User Statement Token, the Client MUST verify the signature, using . Then, the Client MUST verify the used_amr, used_acr and statement_date. The Client is responsible to use the statement_date to prevent replay. The Client is responsible to use the used_amr and used_acr match with its security policy. Then, the Client MUST verify the displayed_question value and the statement value, regarding the question_to_display value and the possible_statements value sent in the User Questioning Request. The Client is responsible of its decision to accept the statement and the displayed_question. The Client is also responsible of any decision based on the statement value and the displayed_question value.

Non-repudiation is an important feature of User Statement Token. To enable this feature, the asymetric signatures are the only allowed signatures for User Statement Tokens. This way, the Client can store the User Statement Token and use it as a proof of the statement made by Questioned User. This proof engages the signer's responsibility, i.e the OP's reponsibility.

Signatures and Encryption should respect the requirements defined in chapter 10 of with one restriction: symetric signatures are FORBIDDEN.

Signing and Encryption Order should respect the requirements defined in chapter 16.14 of .

The User Statement Token contains the Questioned User's statement on a question. This information is personal. If the user_id is present in the User Questioning Request, it will also be present in the User Statement Token, therefore Questioned User is directly identifiable. In order to protect the Questioned User's privacy, Client SHOULD only store encrypted User Statement Tokens. The encryption can be computed either by the OP or by the Client, using .

The OpenID Connect User Questioning API can be discovered within the OpenID Provider Metadata thanks to . The scope question MUST be present in the scopes_supported array. The URL of User Questioning Request Endpoint MUST be configured as the value of uq_request_endpoint. The URL of User Questioning Polling Endpoint MUST be configured as the value of uq_polling_endpoint.

This document makes no requests of IANA.

Nomura Research Institute, Ltd. Ping Identity Microsoft Google Salesforce Illumila Nomura Research Institute, Ltd. Ping Identity Microsoft Nomura Research Institute, Ltd. Ping Identity Microsoft Illumila Microsoft Ping Identity Nomura Research Institute, Ltd. Microsoft Ping Identity Nomura Research Institute, Ltd. Microsoft RTFM, Inc. Cisco Systems, Inc. University California Los Angeles (UCLA) International Telecommunication Union

The 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