Goals of our design
1) Once a user signs in using a credential, we want them to be able to stay signed in indefinitely. This holds true even if the client returns outside of any time window we might anticipate. To reauthenticate, we've been issuing a token for the purpose of re-acquiring a session when the user loses it.
2) We don't want the reauthentication token stored in plaintext on the server, since it is effectively a password.
3) The reauthentication token can be lost in transit back to the client, along with the session being returned. When this happens the client is in a "failed reauthentication" state and these improvements are primarily designed to ensure the client can recover from this state.
4) We want to invalidate the existing session when issuing a new session. However in practice, this means that we want to invalidate any existing session token(s) once a new session token has been successfully used by the client to authenticate (that's the only session token we know the client has received).
When a reauthentication request succeeds, but the client fails to get back the session, we create a new reauth token and store the old token in Redis. While the client can recover by resending the old reauth token, and they will get the session, the session we send back does not include the new reauth token (we don't have it due to #2 above). We just return the old token in the session. As a result, at some point, that user will still have to authenticate when the cached reauthentication token expires from cache.
The proposed design would fix this.
Signing in
...
- sessionToken ↝ userId
- userId ↝ (sessionToken) the set of valid session tokens is only this token when user signs in
- userId ↝ session
...
Goals of our design
1) Once a user signs in using a credential, we want them to be able to stay signed in indefinitely. This holds true even if the client returns outside of any time window we might anticipate. To reauthenticate, we've been issuing a token for the purpose of re-acquiring a session when the user loses it.
2) We don't want the reauthentication token stored in plaintext on the server, since it is effectively a password.
3) The reauthentication token can be lost in transit back to the client, along with the session being returned. When this happens the client is in a "failed reauthentication" state and these improvements are primarily designed to ensure the client can recover from this state.
4) We want to invalidate the existing session when issuing a new session. However in practice, this means that we want to invalidate any existing session token(s) once a new session token has been successfully used by the client to authenticate (that's the only session token we know the client has received).
When a reauthentication request succeeds, but the client fails to get back the session, we create a new reauth token and store the old token in Redis. While the client can recover by resending the old reauth token, and they will get the session, the session we send back does not include the new reauth token (we don't have it due to #2 above). We just return the old token in the session. As a result, at some point, that user will still have to authenticate when the cached reauthentication token expires from cache.
The proposed design would fix this.
Signing in
- User signs in
- We create a new session, session token, reauthToken
- We store the following Redis mappings:
- sessionToken ↝ userId
- userId ↝ (sessionToken) the set of valid session tokens is only this token when user signs in
- userId ↝ session
- return the session with the sessionToken and reauthToken in the session
Alternative sign in options that address concurrent sign ins
Concurrent sign ins should be rarer because they involve human intervention (enter credentials, click on a link), but could still theoretically happen. One approach to dealing with this would be to issue a new token with each successful sign in, following this logic:
- issue new session token on each sign in
- on access
- sessionToken ↝ userId
- userId ↝ session
- is token in session tokens set?
- NO: not authenticated
- YES: is there more than one token in session?
- NO: return session
- YES: replace set with a set consisting only of this token, write session to cache, return session
- is token in session tokens set?
Note that with this approach, we can later allow multiple clients to authenticate simultaneously by not stripping out other session tokens. Each token has an expiry due to the first sessionToken ↝ userId lookup, independent of the session expiry.
Another alternative would be to try the userId↝ session lookup and if a session already exists, return the session token in the session, for some grace period we can record in the session or in the cache (due to network issues though, "concurrency" issues could spread out over time in unexpected ways).
Authenticating a request
- User makes request with a sessionToken
- Retrieve the userId with the sessionToken (if this fails return 404)
- Retrieve the valid sessionToken set with the userId (if this fails return 404)
- Verify the sessionToken is in the set (if this fails return 404)
- Update the set to include only this sessionToken (if the set only includes this token do nothing)
- Retrieve the session with the userId
- return the session with this session token and whatever reauthentication token is in the session
...
- User reauthenticates with the reauthentication token
- We retrieve the N most recent records by their creation date, hash the token by the algorithm in each record, and compare to the hashed records looking for a match. A match is an authentication success
- We create a new session, sessionToken, reauthToken
- Persist a new record in the secrets table for the new reauthToken
- We store the following Redis mappings:
- sessionToken ↝ userId
- userId ↝ (sessionToken) add this session token to the set, do not recreate it
- userId ↝ session
- return the session with the sessionToken and reauthToken in the session
Thus, the tokens are rotated by successful reauthentication attempts, not by an expiration time.
To force rotation of the session token, we regenerate it with each reauthentication attempt. (If we copied it over, you could reauthenticate every day just before the session expired, keeping the token indefinitely, which isn't secure). We can issue multiple session tokens and we need to accept any of them, but once the client uses a session token, that is the only token that we will accept. That's the one the client has definitely received.
Sign Out
- userId ↝ () empty the set of valid tokens
- Delete the userId ↝ session mapping
- Delete the reauth secret records for this user in the secrets table
Reauthentication
When the session token is expired, the client can send a reauth token via the reauth API. We retrieve the N most recent records for that user by their creation date (probably N=2 but could be N=3 if this is more robust), hash the token by the algorithm in each record, and compare to the hashed records looking for a match. (Do this intelligently: cache the hash by algorithm and reuse it since the algorithm is unlikely to change between reauthentications.) If there's a match, we treat this like a sign in: we generate a new session token and persist a new reauth token, and return a new session with these new tokens. If the reauthentication fails, even on return, the previous token continues to work, because we're comparing against older records as well.
...