zoreal-oauth2 0.1.3 → 0.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 316d86bac36a690c10fdfefbf5b5f1ebbadce45e56e69d0d0074d641ff9e1f07
-  data.tar.gz: c47f42263f881132a9281b70402654bb4f07bfa9b7963544a712e4f4ee8c8246
+  metadata.gz: 7179440f857aa507bde5dd88b3c5ebf1f714fd73e8ecc3b3c136a6b47f2cc69e
+  data.tar.gz: 24f5ad9f699eda4f6b92c99226ce572cd9e015356ec8e11747726ac55d6005c1
 SHA512:
-  metadata.gz: c2341f70010a3769490afe488816d3a223b243693c1bdf70ffbfd1f7d0ce81443ba55c32126bb3f9629232530ae3590d3c85ab0a5f3820c0cc48b4a78fb67c61
-  data.tar.gz: 10447f93e400fb9154fe8e59a46655640ed7f995c39c54b23fb23ebbbbf134c650ad278dc2e1ed4904de39afec1873cd3b0f284a4a98e7dce843981fd478339f
+  metadata.gz: 145f11a19c406f246ae6258aa7e402a8888882009c3f51d0e694e889aedd6611df04734ab398ff8c6fe51f3940e7b017c78e64bace0072a7cd52dcade5922054
+  data.tar.gz: 067e2b2041d54ba943db77313b14821896574414c784a1c629e1726ce966d1b7b76a78a37e3d1a4a249600b93ed1b66ea3c471ad0983ea0304909b9d77795c21

data/README.md

@@ -67,6 +67,115 @@ if user.nil?
 end
 ```
 
+## Assurance levels — `acr`, and requiring a liveness check
+
+### What `acr` is
+
+`acr` is an OpenID Connect standard claim — *Authentication Context Class
+Reference*. It is a single string in the ID token that says **how strongly this
+particular login was authenticated**. Every ZOREAL login carries one, and it is
+the difference between "someone who once enrolled this identity is behind this
+request" and "a live human, verified to be the right one, is behind this request
+right now".
+
+It answers a question the `sub` cannot. `sub` tells you *who* (a stable, pairwise
+identifier for this person at your site). `acr` tells you *how sure ZOREAL is that
+the person is really there for this login*. A stolen, unlocked phone can still
+produce a `sub`; it cannot produce a fresh `zoreal.live`.
+
+### The three levels
+
+Ordered weakest to strongest. Each is what actually happened, never what was
+requested — a login that could only reach a weaker level says so honestly rather
+than claiming the level you asked for.
+
+| `acr` | What the holder did | `amr` | What it proves | What it does **not** prove |
+|---|---|---|---|---|
+| `zoreal.session` | Nothing — a returning holder at a site they have used before, resumed silently from an existing ZOREAL session, no phone interaction | `[]` | Continuity: the same browser/session ZOREAL already knew | That the holder is present, or even awake |
+| `zoreal.device` | Approved the login on their enrolled phone: a signature from a key in the phone's secure element, released by a local biometric or passcode unlock | `["hwk","user"]` | Possession of the enrolled device **and** a local unlock on it | That a live face was captured for *this* login — an unlocked phone in the wrong hands still signs |
+| `zoreal.live` | All of the above **plus** a fresh face capture this login: a flash-plus-zoom video scored for presentation attacks and screen replay (moire), matched 1:1 against the government document read at enrolment | `["hwk","face","user"]` | A live, real, unique human, verified to be the enrolled person, **at the moment of this login** | — (this is the strongest level) |
+
+`amr` (*Authentication Methods References*) is the companion claim listing the
+factors used: `hwk` a hardware key, `user` a user-presence/unlock gesture, `face`
+a face biometric. `zoreal.live` is exactly `zoreal.device` with `face` added,
+because a live login is a device approval with a capture on top.
+
+The **default is `zoreal.device`**, never `zoreal.session`: a login that asks for
+nothing still requires the enrolled phone and a local unlock. Silence has to be
+explicitly asked for (`prompt=none`), and it succeeds only for a returning holder
+at a site whose consent they have already given.
+
+### When to require which
+
+- **`zoreal.session`** — you never *require* this; it is what a returning holder
+  gets for a low-stakes convenience re-auth when they ask for the silent path.
+- **`zoreal.device`** (the default) — a forum, a community, a normal account
+  login. Possession of the enrolled phone plus a local unlock is a high bar
+  already; most sites want exactly this and should pass no `acr` at all.
+- **`zoreal.live`** — a bank onboarding, a high-value transaction, an age-gated
+  purchase, a first login, a "confirm it is really you" step before a sensitive
+  action. Anywhere a *fresh, unforgeable proof of the live, right human* is worth
+  the few seconds a face capture costs.
+
+### Requesting versus verifying — the one rule that matters
+
+Requesting a level and verifying it are **two separate steps, and only the second
+is security**:
+
+1. **Request** it on the wire, in the frontend, with the SDK's
+   `acr_values: 'zoreal.live'`. This is what makes the holder's ZOREAL ID app run
+   the face capture before it will approve. It is **advisory** — it shapes what
+   the holder is asked to do, nothing more. A browser is attacker-controlled; a
+   value that only travels through it proves nothing.
+2. **Verify** it here, at token exchange, by passing `acr:`. The signed `acr`
+   claim in the ID token — minted by ZOREAL, not by the browser — is the proof.
+
+```ruby
+login = ZOREAL_OAUTH.authenticate(
+  code: params[:code], code_verifier: params[:code_verifier],
+  nonce: params[:nonce],
+  acr: 'zoreal.live'    # raises VerificationError unless the signed token says so
+)
+
+login.acr                            # "zoreal.live" — what actually happened
+login.live?                          # convenience: acr == "zoreal.live"
+login.satisfies_acr?('zoreal.device')# true (live is stronger than device)
+```
+
+**An RP that requests `zoreal.live` on the wire but never passes `acr:` here has
+checked nothing** — it has only asked the holder nicely and then trusted a value
+it never validated.
+
+### How the check behaves
+
+Verification satisfies **upward**: `zoreal.session < zoreal.device <
+zoreal.live`, so a requirement of `zoreal.device` accepts a `zoreal.live` token
+(the holder gave you *more* assurance than you demanded). A token whose `acr` is
+below the requirement, missing entirely, or outside the vocabulary is refused
+with `VerificationError`. An unknown *required* value — a typo like
+`'zoreal.liveness'` — raises `ConfigurationError` instead, because that is a bug
+in your code, not a bad token, and failing every login silently is worse than
+saying so.
+
+If you prefer to branch rather than raise, omit `acr:` and inspect the result:
+
+```ruby
+login = ZOREAL_OAUTH.authenticate(code:, code_verifier:, nonce:)
+unless login.satisfies_acr?('zoreal.live')
+  # step the user up, or refuse the sensitive action
+end
+```
+
+### `acr` versus the assurance block
+
+Do not confuse `acr` with `login.assurance`. `acr` grades *this login event*.
+The **assurance block** (`login.assurance`) describes the *identity behind it* —
+how the person was verified at enrolment (`uniqueness` basis, `verified_on`
+month, whether chip liveness was proven, the `trust_tier`, the device's
+`key_protection`). One is about now; the other is about who they are. A high-value
+flow usually wants both: `acr: 'zoreal.live'` for presence, and the assurance
+block for the strength of the underlying identity proofing.
+
 ## Client authentication: all four registered methods
 
 | `token_endpoint_auth_method` | Configuration | What travels |

data/lib/zoreal/oauth2/client.rb

@@ -30,6 +30,10 @@ module Zoreal
       JWKS_CACHE_KEY = 'zoreal_oauth2_jwks'.freeze
 
       AUTH_METHODS = %w[none client_secret_basic private_key_jwt tls_client_auth].freeze
+      # The assurance vocabulary, weakest to strongest. Verification accepts
+      # equal or stronger: an RP requiring zoreal.device is satisfied by a
+      # zoreal.live token, never the reverse.
+      ACR_ORDER = { 'zoreal.session' => 0, 'zoreal.device' => 1, 'zoreal.live' => 2 }.freeze
       # The provider rejects an assertion whose exp is more than 60 seconds
       # out, so that is the lifetime, not a choice.
       ASSERTION_LIFETIME = 60
@@ -80,12 +84,19 @@ module Zoreal
 
       # The whole login, in order: exchange the code (with the PKCE verifier
       # the browser SDK handed over), verify the ID token against the JWKS,
-      # check the nonce when the caller has it. Returns a Login; personal data
-      # is NOT fetched here, because the ID token never carries it and not
-      # every caller wants it — Login#userinfo fetches on first use.
-      def authenticate(code:, code_verifier:, nonce: nil)
+      # check the nonce when the caller has it, and — when the caller passes
+      # acr: — refuse a token whose assurance is below it. Returns a Login;
+      # personal data is NOT fetched here, because the ID token never carries
+      # it and not every caller wants it — Login#userinfo fetches on first use.
+      #
+      # REQUESTING an assurance on the wire (the SDK's acr_values) is
+      # advisory; the signed acr claim is the proof, and this parameter is
+      # where a relying party that asked for a liveness check verifies it
+      # actually happened. An RP that requires zoreal.live and never passes
+      # acr: here has checked nothing.
+      def authenticate(code:, code_verifier:, nonce: nil, acr: nil)
         tokens = exchange(code: code, code_verifier: code_verifier)
-        claims = verify_id_token(tokens['id_token'], nonce: nonce)
+        claims = verify_id_token(tokens['id_token'], nonce: nonce, acr: acr)
         Login.new(client: self, claims: claims,
                   id_token: tokens['id_token'],
                   access_token: tokens['access_token'],
@@ -116,12 +127,12 @@ module Zoreal
         body
       end
 
-      # ES256 against the provider's JWKS, plus iss, aud, exp and — when the
-      # caller passes the nonce the SDK generated — the nonce binding. Returns
-      # the claims. There is no RS256 fallback on purpose: ZOREAL signs
-      # nothing with RSA, and accepting a second algorithm is how algorithm
-      # confusion starts.
-      def verify_id_token(id_token, nonce: nil)
+      # ES256 against the provider's JWKS, plus iss, aud, exp, the nonce
+      # binding when the caller has the nonce, and the assurance floor when
+      # the caller passes acr:. Returns the claims. There is no RS256
+      # fallback on purpose: ZOREAL signs nothing with RSA, and accepting a
+      # second algorithm is how algorithm confusion starts.
+      def verify_id_token(id_token, nonce: nil, acr: nil)
         claims, = JWT.decode(
           id_token, nil, true,
           algorithms: ['ES256'],
@@ -135,6 +146,7 @@ module Zoreal
         if !nil_or_empty?(nonce) && claims['nonce'] != nonce
           raise VerificationError, 'the ID token nonce is not the one this login started with'
         end
+        verify_acr!(claims, acr) unless nil_or_empty?(acr)
 
         claims
       rescue JWT::DecodeError => e
@@ -162,6 +174,20 @@ module Zoreal
 
       private
 
+      # Equal or stronger satisfies; anything else — weaker, missing, or a
+      # value outside the vocabulary — is refused. An unknown REQUIREMENT is a
+      # caller bug and says so plainly rather than failing every login.
+      def verify_acr!(claims, required)
+        required_rank = ACR_ORDER[required]
+        raise ConfigurationError, "unknown required acr #{required}; supported: #{ACR_ORDER.keys.join(', ')}" if required_rank.nil?
+
+        actual_rank = ACR_ORDER[claims['acr']]
+        return if actual_rank && actual_rank >= required_rank
+
+        raise VerificationError,
+              "the ID token says acr #{claims['acr'].inspect}, below the required #{required}"
+      end
+
       def jwks
         cached = @cache.read(JWKS_CACHE_KEY)
         return cached if cached

data/lib/zoreal/oauth2/login.rb

@@ -31,6 +31,21 @@ module Zoreal
         claims['acr']
       end
 
+      # A fresh liveness capture backed this login. The convenience spelling
+      # of acr == 'zoreal.live'; for enforcement, pass acr: to authenticate
+      # and let verification refuse the token instead of checking after.
+      def live?
+        acr == 'zoreal.live'
+      end
+
+      # Equal or stronger satisfies, on the client's ordering
+      # (session < device < live). Unknown values satisfy nothing.
+      def satisfies_acr?(required)
+        actual = Client::ACR_ORDER[acr]
+        wanted = Client::ACR_ORDER[required]
+        !actual.nil? && !wanted.nil? && actual >= wanted
+      end
+
       def amr
         claims['amr']
       end

data/lib/zoreal/oauth2/version.rb

@@ -1,5 +1,5 @@
 module Zoreal
   module OAuth2
-    VERSION = '0.1.3'.freeze
+    VERSION = '0.1.4'.freeze
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: zoreal-oauth2
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.1.4
 platform: ruby
 authors:
 - ZOREAL