Skip to main content

Announcing: Short-lived QR codes and URIs

Edson Monteiro
  • Updated

What is this feature about?

Some social engineering attacks exploit the duration of an authentication or an enrollment session to convince the legitimate user into sharing their Futurae session credentials with the attacker, enabling the attacker to maliciously access the account in lieu of the legitimate user.

One way to mitigate this is to shorten the window for the attack to make taking a screenshot of the QR code or copying the URI and exchanging it with the attacker within this time frame infeasible in practice. 

Short-lived QR codes and URIs allow to step up security without compromising on efficiency and user experience. On frontend interfaces like a web login portall, Customers can now constantly refresh the credentials shown to the user, displaying only the one with the closest expiration time. While a legitimate user can complete the flow normally, slower, malicious manipulations will fail because the short-lived credentials rotate and expire before the attack can be completed.

 

What are Short-lived Exchange Tokens?

Short-lived exchange tokens are ephemeral credentials designed to achieve an efficient implementation of Short-lived QR codes and URIs. Short-lived exchange tokens can be issued on request for any enrollment and authentication flow, presented to the user as QR codes/URIs and can then be exchanged for regular credentials to proceed with the flow as usual. This flow enhancement compels users to scan the QR code or open the URI within a timeline typically shorter than the overall session duration (e.g., 5 seconds instead of 60 sec) in order to reduce the time window for social engineering attacks.  

 

How does it work?

Short-lived QR codes and URIs can be used both for enrollment and for authentication. After starting the flow the usual way, the customer backend fetches a batch of short-lived exchange tokens and shares them with the app via a transport channel of their choice – QR code, URI schema or universal link. 

If the user scans the QR code or consumes the URI within the intended time window, the app can exchange the embedded exchange token for the dedicated flow token: activation code for enrollment, or session token for authentication, and successfully complete the corresponding flow the usual way. 

We include a flow diagram for Enrollment and Authentication in the next sections.

 

SDK requirements

Mobile iOS SDK: v3.9.4

Mobile Android SDK: v3.9.3

 

How to implement Short-lived QR codes and URIs for Authentication

The diagram below illustrates how the end-to-end flow for authentication using Short-lived QR codes or URIs (the lower part of the diagram) compares to the usual authentication flow (in the upper part):

Implementation steps: 

  1. [Backend] Initiate Authentication:
    Start authentication or transaction confirmation, by calling the respective endpoint:
    POST /srv/auth/v1/user/auth
    POST /srv/auth/v1/user/auth/transaction

    Futurae returns 200 in case of success, along with the response body. 
    1.1. Retrieve session_id from the response. 
    1.2 If you are planning to use URI schemas, retrieve the URL scheme from mobile_auth_uri: it is equal to the prefix before “//”. 
    1.3 If you are planning to use universal links, retrieve the associated domain from mobile_auth_universal_link. 
    1.4 DO NOT share any of the response values with the mobile SDK. Instead, proceed to the next step to generate the exchange tokens, using session_id.
     

  1. [Backend] Generate Short-lived Exchange Tokens:
    Call the Auth API endpoint to generate the exchange tokens for authentication or transaction confirmation, respectively:
    POST /srv/auth/v1-extended/user/auth/exchange_tokens
    POST /srv/auth/v1-extended/user/transaction/exchange_tokens

    2.1 Call the relevant endpoint: POST /srv/auth/v1-extended/user/*/exchange_tokens. 

    As arguments, provide the exchange token base duration, the number of tokens to be returned,  as well as the user_id and session_id from the previous step. 

    All of the exchange tokens will be valid from the moment of their creation. An exchange token expiration timestamp is determined by its index in the returned array. E.g. token_0 expires at start_time + exchange_token_lifetime_seconds, token_1 expires at start_time + exchange_token_lifetime_seconds * 2, etc

    You can additionally provide the uri_schema and associated_domain to be used for URIs and universal links associated with your app (see step 1.2 or 1.3). It will be embedded in the returned exchange tokens instead of the default futurae values.

    In a successful scenario, Futurae Auth API replies with 200 OK and a response payload containing the lists of exchange tokens in different formats: one with QR code content (session_exchange_token_qr_codes), one with URI schemes (session_exchange_token_uris) and one with universal links (session_exchange_token_universal_links). 
     

{
    "session_exchange_token_qr_codes": [
        {
            "exp": 1765800090,
            "qr_code_content": "ZXlKaGJHY2lPaUp..."
        },
        {
            "exp": 1765800150,
            "qr_code_content": "ZXlKaGJHY2lPaUpCT..."
        }
    ],
    "session_exchange_token_universal_links": [
        {
            "exp": 1765800090,
            "session_exchange_token_universal_link": "https://futurae.com/auth_exchange?exchange_token=eyJhbGciOiJ...&validUntilUnixTimestamp=1765800090"
        },
        {
            "exp": 1765800150,
            "session_exchange_token_universal_link": "https://futurae.com/auth_exchange?exchange_token=eyJhbGciOiJ...&validUntilUnixTimestamp=1765800150"
        }
    ],
    "session_exchange_token_uris": [
        {
            "exp": 1765800090,
            "session_exchange_token_uri": "futurae://auth_exchange?exchange_token=eyJhbGciOiJBM....&validUntilUnixTimestamp=1765800090"
        },
        {
            "exp": 1765800150,
            "session_exchange_token_uri": "futurae://auth_exchange?exchange_token=eyJhbGciOiJBMjU2...&validUntilUnixTimestamp=1765800150"
        }
    ]
}

2.2. Display tokens to the User: Depending on your application logic, prepare the received exchange tokens for sharing with the user. URIs and universal links are ready to use. qr_code_content items need to be encoded into QR codes as opaque values.

2.3 Display the short-lived QR codes or URIs to the end user one by one, replacing the current item with the next at intervals defined by exchange_token_lifetime_seconds. To ensure a seamless user experience and account for network latency, introduce an overlap by displaying the next token shortly before the active one expires. Adjust this rotation timing according to your specific business logic and security requirements.

3. [Futurae SDK] Extracting and Exchanging the Exchange Token

3.1. Extract the exchange token

  • 3.1.1. QR code flow: scan the QR. Extract the exchange token from the qr_code_content.
  • 3.1.2. URIs and Universal Links. We assume that the host app is configured to handle URIs and/or universal links. Extract the exchange_token from the URI.
  • 3.2. Extract the exchange token
    3.3. In case of success, Futurae returns the session_token. If the provided exchange token has already expired, an API error will be returned. As a fallback, guide the app user to retry scanning / following the “refreshed” deep link.
  1. [Futurae SDK] Proceed with the authentication/transaction confirmation. 
    Use the session_token to retrieve the session extra information, if needed, and then to approve/reject the session.

 

How to implement Short-lived QR codes and URIs for Enrollment

The diagram below illustrates how the end-to-end flow for authentication using Short-lived QR codes or URIs (the lower part of the diagram) compares to the usual authentication flow (in the upper part):

Implementation steps: 

  1. [Backend] Initiate Enrollment: Start enrollment by calling one of the enrollment endpoints, e.g.
    POST /srv/auth/v1/user/enroll. Set short_code to value true in the request body.

    Futurae returns 200 in case of success, along with the response body.

    1.1. Retrieve activation_code_short from the response.

    1.2. If you are planning to use URI schemas, retrieve the URL scheme from activation_code_uri: it is equal to the prefix before “//”.

    1.3. If you are planning to use universal links, retrieve the associated domain from activation_universal_link

    1.4. DO NOT share any of the response values with the mobile SDK. Instead, proceed to the next step to generate the exchange tokens, using activation_code.

     

  2. [Backend] Generate Exchange Tokens for Enrollment:
    Call the Auth API endpoint to generate the exchange tokens for enrollment:
    POST /srv/auth/v1-extended/user/enroll/exchange_tokens
    As arguments, provide the exchange token base duration, the number of tokens to be returned,  as well as the user_id and activation_code_short from the previous step. 

    All of the exchange tokens will be valid from the moment of their creation. An exchange token expiration timestamp is determined by its index in the returned array. E.g. token_0 expires at start_time + exchange_token_lifetime_seconds, token_1 expires at start_time + exchange_token_lifetime_seconds * 2, etc 

    You can additionally provide the uri_schema and associated_domain to be used for URIs and universal links associated with your app (see step 1.2 or 1.3). It will be embedded in the returned exchange tokens instead of the default futurae values.In a successful scenario Futurae Auth API replies with 200 OK and a response payload containing the lists of exchange tokens in different formats: one with QR contents, one with URI schemes and one with universal links.

{
    "enrollment_exchange_token_qr_codes": [
        {
            "exp": 1765800090,
            "qr_code_content": "ZXlKaGJHY2lPaUp..."
        },
        {
            "exp": 1765800150,
            "qr_code_content": "ZXlKaGJHY2lPaUpCT..."
        }
    ],
    "enrollment_exchange_token_universal_links": [
        {
            "exp": 1765800090,
            "enrollment_exchange_token_universal_link": "https://futurae.com/enroll_exchange?exchange_token=eyJhbGciOiJ...&validUntilUnixTimestamp=1765800090"
        },
        {
            "exp": 1765800150,
            "enrollment_exchange_token_universal_link": "https://futurae.com/enroll_exchange?exchange_token=eyJhbGciOiJ...&validUntilUnixTimestamp=1765800150"
        }
    ],
    "enrollment_exchange_token_uris": [
        {
            "exp": 1765800090,
            "enrollment_exchange_token_uri": "futurae://enroll_exchange?exchange_token=eyJhbGciOiJBM....&validUntilUnixTimestamp=1765800090"
        },
        {
            "exp": 1765800150,
            "enrollment_exchange_token_uri": "futurae://enroll_exchange?exchange_token=eyJhbGciOiJBMjU2...&validUntilUnixTimestamp=1765800150"
        }
    ]
}

 

2.1 Display tokens to the User: Depending on your application logic, prepare the returned exchange tokens for sharing with the user. URIs and universal links are ready to share. qr_code_content items need to be encoded into QR codes as they are provided, in order to be interpreted by the SDK.

2.2. Present the QR codes or URIs to the end user one by one, replacing the current item with the next at intervals defined by exchange_token_lifetime_seconds. To ensure a seamless user experience and account for network latency, introduce an overlap by displaying the next token shortly before the active one expires. Adjust this rotation timing according to your specific business logic and security requirements.

3. [Futurae SDK] Extracting and Exchanging the Exchange Token

     3.1. Extract the exchange token

  • 3.1.1. QR code flow: scan the QR. Extract the exchange token from the qr_code_content
  • 3.1.2. URIs and Universal Links. We assume that the host app is configured to handle URIs and/or universal links. Extract the exchange_token from the URI.
     3.2. Extract the exchange token
     3.3. In case of success, Futurae returns the session_token. If the provided exchange token has already expired, an API error will be returned. As a fallback, guide the app user to retry scanning / following the “refreshed” deep link.

4. [Futurae SDK] Proceed with the SDK enrollment. Use the activation_code_short to complete the enrollment.

 

Retrieving and displaying short-lived QRs and URIs

Managing how to retrieve and display the short-lived QRs and URIs to the end user is left to Customers. In particular, the choice of the parameters for the batch – the number of exchange tokens to be retrieved and stored by Customer as well as the validity of a single token – will be determined by the Customer’s business constraints. 

Example Rotation Workflow:
If the QR codes with exchange tokens are generated with a lifetime of 3 seconds, the first one expires after 3 seconds, the second one after 6 seconds, etc. Each QR/Exchange Token becomes active and can be used the moment it is displayed. Displaying the next QR code 2 seconds before the current one expires creates an overlap, allowing a total window of 5 seconds during which the new token can be successfully exchanged (while being visible on-screen for 3 seconds). 

  • Important: we recommend to disclose at most two QR codes or URIs with the shortest remaining time to live.  
  • There can be a practical limit to how short a short-lived QR code or URI can be valid due to network latency and user experience limitations (for example, time taken to open the QR scanner and scan a QR code). 
  • If a successful exchange does not occur, your backend can request an additional token batch for the same single enrollment or authentication session.

 

For any inquiries, do not hesitate to contact us at support@futurae.com.

Comments

0 comments

Article is closed for comments.

Powered by Zendesk