Tiqr Protocoll

The tiqr-app and the tiqr server (website) need to communicate information during enrollment and authentication.

Enroll

During enrollment a user registers his Tiqr-app with the server

metadata_url

The metadata contains information about the tiqr service and the new user account this is being created. For security reasons the metadata_url must be uniqe so that a client can only retrieve the metadata once. The server invalidates the URL after providing the metadata so that it cannot be used a second time. A server can E.g. add a secure pseudorandom nonce to the URL to do this.

The format of the URL not specified. A client put extra restrictions on which servers it trusts.

Example metadata_url: https://tiqr.example.org/get_metadata/?enrollment_key=f835ae8f915433c11c9cded94280e3a7

enrollment_url

The erollemnt_url uses a custom URL scheme or universal link to start the enrollment process of a new user in the Tiqr client and to transfer the metadata_url to the client. The enrollment_url is transferred to the Tiqr client by the user scanning a QR code of by a clickable link.

There are two formats defined for the enrollemt URL

Custom URL Scheme

scheme://metadata URL

E.g.: tiqrenroll://https://tiqr.example.org/get_metadata/?enrollment_key=f835ae8f915433c11c9cded94280e3a7 where tiqrenroll is the cutorm url scheme that rigstered by the tiqr client.

Universal Link

universal link?metadata=URL encoded metadata_url

E.g.: metadata=https%3A%2F%2Ftiqr.example.org%2Fget_metadata%2F3Fkey%3Df835ae8f915433c11c9cded94280e3a7

Metadata format

The tiqr client makes a HTTP GET request to the tiqr server. When the metadata URL is valid the server responds with an application/json encoded message.

• service/displayName: The friendly name of the tiqr server for display purposes
• service/identifier: A uniqe identifier of for this tiqr server
• service/logoUrl: A URL where the client can get a .png of .jpg image to associate with the account
• service/infoUrl: A URL where the user can get more information about the tiqr server
• service/authenticationUrl: The URL what the authentication response will be POSTed to when the user authenticates to the server
• service/ocraSuite: The OCRA suite to use, used to calculate responses. Not that the protocol currently does not support switching to a different suite.

• service/enrollmentUrl: The url where the client POSTs the secret. This URL must be uniqe and must be kept secret between the client and the server for the duration of the enrollemnt. This enrollment_key and the enrollment_secret must be different.

• identity/identifier: The identitfier of the user account. e.g. the login name, account name of the user at the server
• identity/displayName: The name of the user or some other description of the account.

  {
    "service":{
      "displayName":"Tiqr example authentication server",
      "identifier":"tiqr.example.org",
      "logoUrl":"https:\/\/tiqr.example.org\/logo",
      "infoUrl":"https:\/\/tiqr.example.org\/info",
      "authenticationUrl":"https:\/\/tiqr.example.org\/authenticate",
      "ocraSuite":"OCRA-1:HOTP-SHA1-6:QH10-S064",
      "enrollmentUrl":"http:\/\/tiqr.example.org\/finish-enrollment?enrollment_secret=3cc68ea291fc5fbef20174d493fba41c"
   },
   "identity":{
      "identifier":"example-user",
      "displayName":"Example user"
   }
  }
  

The app wil preform the enrollment, and will send the results to the enrollmentUrl using a FORM POST

With this information the tiqr client can create a user account in the client and generate the OCRA secret. This is a shared secret between the client and the server.

Finish Enrollemnt

The tiqr client POSTs the FORM DATA to the server.

• secret: The ocra secret the the client generated. The server will store that and associate it with the userid. It is required to later authenticate the user.
• language: The preferred langue of the user
• notificationAddress: Optional. The device notification addess for receiving push notifications
• notificationType: Optional. The type of the address, this specifies the method that must be used to the notifiaction to the client.
• operation: Must always be register

Spported notification types:

• APNS: Apple push notification service. The notificationAddress is a pseudotoken from a tiqr token exchange.
• APNS_DIRECT: Apple push notification service. The notificationAddress is the APNS device token.
• FCM: Firebase cloud messaging. The notificationAddress is a pseudotoken from a tiqr token exchange.
• FCM_DIRECT: Firebase cloud messaging. The notificationAddress is the FCM address.

Example:

secret=b57940c0939bd997628f36264409b29e9a5e10834fd227347698bb9146ae09a6
language=nl
notificationAddress=D5D760D233FC48194A546EB718917451FDC268E4E416A0AE87CEF77909F1EA81
notificationType=APNS_DIRECT
operation=register

If the enrollment information was processed corectly, the tiqr-server will return a HTTP 200 message containing the string OK.

Authentication

authentication_url

The authentication_url generated by the tiqr server and contains all information that the tiqr client requiers to start an authentication. This url can be presented to the user as a push-message, QR code or a clickable link.

The server sends:

• userid: Optional. This is the identity/identifier that the server sent in the metadata during enrollment. Informs the tiqr client which user the server expects to authenticated
• identifier: This is the service/identifier that the server sent in the metadata during enrollment
• session_key: The OCRA SessionInformation (S) A secure pseudo random key that identifies this authentication
• challenge_question: The OCRA challenge question (Q) According to the service/ocraSuite that the server sent in the metadata during enrollment
• server_identifier: Identifier of the service to which the client is authenticating. Implementation defined. Set to identity/identifier when unknown
• version: The protocol version. Currenly 1 or 2.

There are two formats supported, depending on whether a custom URL scheme or a Universal Link is used.

Custom URL Scheme

With userid: scheme://userid@identifier/session_key/challenge_question/server_identifier/version

Example: tiqrauth://example-user@tiqr.example.org/0da1c51c3c3be54441527d4e5bde3710/747d558f3d/tiqr.example.org/2

Without userid: scheme://identifier/session_key/challenge_question/server_identifier/version

Example: tiqrauth://tiqr.example.org/0da1c51c3c3be54441527d4e5bde3710/747d558f3d/tiqr.example.org/2

Universal Link

With userid: unversal Link?u=userid&i=identifier&s=session_key&q=challenge_question&v=version

Example: https://tiqr.example.org/tiqrauth/?u=example-user&i=tiqr.example.org&s=0da1c51c3c3be54441527d4e5bde3710&q=747d558f3d&v=2

With userid: unversal Link?i=identifier&s=session_key&q=challenge_question&v=version

Example: https://tiqr.example.org/tiqrauth/?i=tiqr.example.org&s=0da1c51c3c3be54441527d4e5bde3710&q=747d558f3d&v=2

Note that all URL paramater values must be URL encoded and that this format does not support specifying a server_identifier

POST /authenticate FORM DATA

The client calculates the OCRA response using the information from the authentication_url, the OCRA suit it received in the metadata and the OCRA client secret that it generated during enrollment.

It sends a POST with FORM DATA back using with:

• sessionKey: the session_key from the authentication_url
• userId: the usedid of the user that it authenticated
• response: the OCRA response that it calculated
• language: the preffered language of the user
• operation: always set to login
• notificationType: Optional. See enrollemnt.
• notificationAddress: Optional. See enrollemnt.

Example:

sessionKey=0da1c51c3c3be54441527d4e5bde3710
userId=example-user
response=012345
language=nl
operation=login
notificationType: APNS_DIRECT
notificationAddress: D5D760D233FC48194A546EB718917451FDC268E4E416A0AE87CEF77909F1EA81

If the authentication is processed corectly, the tiqr-server will return a HTTP 200 message containing the string OK.