Class: XeroKiwi::OAuth::IDToken

Inherits:
Object
  • Object
show all
Defined in:
lib/xero_kiwi/oauth/id_token.rb

Overview

Verifies an OIDC id_token (JWT) returned by Xero. Validates the signature against Xero’s JWKS and checks the standard OIDC claims (iss, aud, exp). Optionally verifies the nonce claim if you sent one in the authorisation request.

Two ways to use this:

# 1. Via an OAuth instance — uses the instance's JWKS cache, so
#    repeated verifications don't refetch Xero's signing keys.
verified = oauth.verify_id_token(token.id_token)

# 2. Standalone class method — fetches JWKS fresh on each call.
#    Fine for one-off verification.
verified = XeroKiwi::OAuth::IDToken.verify(id_token, client_id: "abc123")

verified.subject       # OIDC `sub` claim
verified.email         # if `email` scope was granted
verified.given_name    # if `profile` scope was granted
verified.expires_at    # Time
verified.claims        # full claims hash

Constant Summary collapse

ISSUER = 
"https://identity.xero.com"
ALGORITHMS = 
%w[RS256].freeze

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(claims) ⇒ IDToken

Returns a new instance of IDToken.



89
90
91
 
# File 'lib/xero_kiwi/oauth/id_token.rb', line 89

def initialize(claims)
  @claims = claims
end

Instance Attribute Details

#claims ⇒ Object (readonly)

Returns the value of attribute claims.



35
36
37
 
# File 'lib/xero_kiwi/oauth/id_token.rb', line 35

def claims
  @claims
end

Class Method Details

.verify(id_token, client_id:, nonce: nil, jwks: nil) ⇒ Object 



37
38
39
40
41
42
43
44
45
46
47
 
# File 'lib/xero_kiwi/oauth/id_token.rb', line 37

def self.verify(id_token, client_id:, nonce: nil, jwks: nil)
  raise ArgumentError, "id_token is required"  if id_token.nil?  || id_token.empty?
  raise ArgumentError, "client_id is required" if client_id.nil? || client_id.empty?

  decoded = decode(id_token, client_id, jwks)
  claims  = decoded.first
  verify_nonce!(claims, nonce) if nonce
  new(claims)
rescue JWT::DecodeError => e
  raise IDTokenError, "ID token verification failed: #{e.message}"
end

Instance Method Details

#email ⇒ Object 



94
 
# File 'lib/xero_kiwi/oauth/id_token.rb', line 94

def email       = claims["email"]

#expires_at ⇒ Object 



99
 
# File 'lib/xero_kiwi/oauth/id_token.rb', line 99

def expires_at  = claims["exp"] && Time.at(claims["exp"]).utc

#family_name ⇒ Object 



96
 
# File 'lib/xero_kiwi/oauth/id_token.rb', line 96

def family_name = claims["family_name"]

#given_name ⇒ Object 



95
 
# File 'lib/xero_kiwi/oauth/id_token.rb', line 95

def given_name  = claims["given_name"]

#issued_at ⇒ Object 



98
 
# File 'lib/xero_kiwi/oauth/id_token.rb', line 98

def issued_at   = claims["iat"] && Time.at(claims["iat"]).utc

#nonce ⇒ Object 



97
 
# File 'lib/xero_kiwi/oauth/id_token.rb', line 97

def nonce       = claims["nonce"]

#subject ⇒ Object 



93
 
# File 'lib/xero_kiwi/oauth/id_token.rb', line 93

def subject     = claims["sub"]