SPL Token Exchange

Owned by Aiyan Jiang
Last updated: May 26, 2020
2 min read

work in progress subject to change

Endpoint Protection

The method by which secure endpoints are protected.

The planned method of authenticating HTTP requests from the Safe Places web app is to use a JSON Web Token (JWT).

The rationale behind the decision is due to the token’s ability to retain potentially sensitive information (JWT claims) in transit while maintaining its data integrity via key-signing.

Structure

Header

{ "alg": "HS256", "typ": "JWT" }

Payload

{ "sub": "<username>", "role": "<user_role">, "context": "<hashed_cookie_context">, "iat": "<issue_date">, "exp": "<expiration_date"> }

Variable

Description

Variable

Description

<username>

The username of the authorized user.

<user_role>

The role of the user.

<hashed_cookie_context>

The hashed context of the session. This will be compared to a sent cookie.

See the “Potential Vulnerabilities” section for more details.

<issue_date>

(Built-in to JWT) The date the token was issued.

Note that the date is the number of seconds since Jan 1 1970. This is the equivalent of the Javascript Date.now() * 1000.

<expiration_date>

The date the token expires.

Token Attainment

The method by which the token will be securely obtained by the Safe Places web app.

Scope

  • The Safe Places backend will not be handling the management of the user pool.

Token attainment will largely depend on the health authority. To accommodate common methods of identity management, the Safe Places backend will enable compatibility with Lightweight Directory Access Protocol (LDAP) and/or Active Directory (AD).

  1. SPL Web App sends the username and password to SPL Backend.

  2. SPL Backend uses DN resolution based on the sent username.

  3. LDAP Server responds with the distinguished name (DN) of the user.

  4. SPL Backend runs the bind command to validate the DN and password.

  5. LDAP Server responds with either success or failure.

  6. If successful, SPL Backend issues a JSON Web Token with appropriate permissions to the client.

Potential Vulnerabilities

Token Sidejacking

An attacker may steal the token from the authorized user and use it for nefarious purposes. To mitigate this attack, we will employ token contextualization.

  1. We generate a random string during the authentication phase and send it to the client as a cookie.

    1. The cookie must have the flags HttpOnly, Secure, and SameSite.

  2. We store a SHA256 hash of the random string in the token as context.

During token validation, we compare the token context with the sent cookie. If they are different, then reject the request.

Access Code Exchange

The method by which access tokens for consent are generated and exchanged.

The planned method for generating an access code to be communicated to the member of the public (MoP) is generating a fixed-length numeric code.

Requirements

  • The numeric code must be generated with a cryptographically secure random number generator.

  • The code must be short enough and unambiguous so that it can be communicated verbally over the telephone.

  • The code must be long enough so that an attacker cannot brute-force the code.

    • This problem can be remediated by rate-limiting the access code endpoint.

Structure

Numeric digits allow us log2(10) = 3.32 bits of entropy per character. RFC 4086 recommends 29 bits of entropy for a password dependent on online authentication.

To meet that, we would need roughly 8 digits to have a decently-secured access code. Through key-stretching via simple HTTP rate-limiting, while considering accessibility, we can likely reduce the requirement to 6 digits.

An example of an access code would be as follows:

123759