Working with IDT - department-of-veterans-affairs/caseflow GitHub Wiki

API Overview

See this section of the Caseflow APIs wiki page.

Authentication

Instead of continuously using a Rails session cookie set by the SSO login flow, IDT first ties a user session to a bearer token, then uses the bearer token to authenticate subsequent API calls:

  1. IDT calls GET /idt/api/v1/token to generate a one-time key and token pair. Caseflow stores this mapping in Redis.
  2. User logs in to Caseflow via web browser.
  3. User calls GET /idt/auth?one_time_key=OTK while logged in. Caseflow discards the one-time key and stores the mapping between the token and the user's CSS ID in Redis.
  4. IDT authenticates subsequent calls with the token.

Working with IDT authentication in Rails

Looking up a user for a token

Idt::Token.associated_css_id("a-long-128-byte-string")

Looking up a token for a user

cli = Idt::Token.client
keys = cli.keys("#{Idt::Token::VALID_TOKENS_KEY}*")
token = keys.find { |k| cli.get(k) == user.css_id }

If token ends up being nil, that means the user has not successfully authenticated to IDT yet.

Calculating token age and expiration

To determine when a token will expire:

Time.zone.now + cli.ttl(token).seconds

This also reveals when the token was activated, assuming the TTL value has not changed in the code.

Time.zone.now + cli.ttl(token).seconds - Idt::Token::TOKEN_VALIDITY_IN_SECONDS.seconds

Pre-loading tokens for users

Sometimes it is helpful to manually assign preset IDT tokens to user accounts. For example, when doing integration testing against IDT in UAT or demo environments, the usual authentication process is cumbersome and can be bypassed.

def activate(token, css_id)
  cli = Idt::Token.client
  key = Idt::Token::VALID_TOKENS_KEY + token
  cli.set(key, css_id)
  cli.expire(key, Idt::Token::TOKEN_VALIDITY_IN_SECONDS)
end

# example call:
activate("12345", "BVAAABSHIRE")

# and to verify:
Idt::Token.associated_css_id("12345")