Open source authentication solution for smart phones and web applications

Tiqr Protocol

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

Flow diagram enrollment

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 enrollment 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?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.

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 Enrollment

The tiqr client POSTs the FORM DATA to the server.

Spported notification types:

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

Flow diagram enrollment

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:

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

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:

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.