| 1 | package Catalyst::Plugin::OAuth2::ResourceServer::Server; | ||||||||||||||||||||||||||||||||
| 2 | 5 | ▶ | use v5.36; | ||||||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||
| 3 | 5 | ▶ | use Moo; | ||||||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||
| 4 | 5 | ▶ | use Carp (); | ||||||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||
| 5 | 5 | ▶ | use Try::Tiny; | ||||||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||
| 6 | 5 | ▶ | use Crypt::JWT qw/decode_jwt/; | ||||||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||
| 7 | 5 | ▶ | use Catalyst::Plugin::OAuth2::ResourceServer::Error; | ||||||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||
| 8 | |||||||||||||||||||||||||||||||||
| 9 | 5 | our $VERSION = '0.003'; | |||||||||||||||||||||||||||||||
| 10 | |||||||||||||||||||||||||||||||||
| 11 | 5 | has signing_key => ( is => 'ro', required => 1 ); | |||||||||||||||||||||||||||||||
| 12 | 5 | has resource => ( is => 'ro', required => 1 ); | |||||||||||||||||||||||||||||||
| 13 | 5 | has issuer => ( is => 'ro', required => 1 ); | |||||||||||||||||||||||||||||||
| 14 | 5 | has jwt_alg => ( is => 'ro', default => 'HS256' ); | |||||||||||||||||||||||||||||||
| 15 | 5 | has leeway => ( is => 'ro', default => 0 ); | |||||||||||||||||||||||||||||||
| 16 | |||||||||||||||||||||||||||||||||
| 17 | 5 | ▶ | use namespace::clean; | ||||||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||
| 18 | 5 | ▶ | use MooX::StrictConstructor; | ||||||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||
| 19 | |||||||||||||||||||||||||||||||||
| 20 | 38 | ▶ | sub BUILD ( $self, $args ) { | ||||||||||||||||||||||||||||||
|
Subroutine
BUILD: called CC=4 SCAR=13.9
Pod
undocumented
| |||||||||||||||||||||||||||||||||
| 21 | Carp::croak 'resource must be a non-empty scalar or arrayref' | ||||||||||||||||||||||||||||||||
| 22 | 38 | ▶ | unless @{ $self->_resource_list }; | ||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||
| 23 | 37 | state %ALLOWED_ALG = map { $_ => 1 } qw/HS256 HS384 HS512/; | |||||||||||||||||||||||||||||||
| 24 | Carp::croak 'jwt_alg must be one of HS256, HS384, HS512' | ||||||||||||||||||||||||||||||||
| 25 | 37 | ▶ | unless $ALLOWED_ALG{ $self->jwt_alg }; | ||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||
| 26 | 36 | state %MIN_KEY_BYTES = ( HS256 => 32, HS384 => 48, HS512 => 64 ); | |||||||||||||||||||||||||||||||
| 27 | Carp::croak sprintf( | ||||||||||||||||||||||||||||||||
| 28 | 'signing_key must be at least %d bytes for %s', | ||||||||||||||||||||||||||||||||
| 29 | $MIN_KEY_BYTES{ $self->jwt_alg }, $self->jwt_alg ) | ||||||||||||||||||||||||||||||||
| 30 | 36 | ▶ | if length( $self->signing_key ) < $MIN_KEY_BYTES{ $self->jwt_alg }; | ||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||
| 31 | } | ||||||||||||||||||||||||||||||||
| 32 | |||||||||||||||||||||||||||||||||
| 33 | # resource may be a scalar or arrayref; normalise to a list. | ||||||||||||||||||||||||||||||||
| 34 | 58 | ▶ | sub _resource_list ( $self ) { | ||||||||||||||||||||||||||||||
|
Subroutine
_resource_list: called CC=4 SCAR=15.2
| |||||||||||||||||||||||||||||||||
| 35 | 58 | my $r = $self->resource; | |||||||||||||||||||||||||||||||
| 36 | 58 | ▶ | return ref $r eq 'ARRAY' ? [ @$r ] : defined $r && length $r ? [$r] : []; | ||||||||||||||||||||||||||||||
|
Branch: 2 branches
Condition33%1/3
defined $r and length $r
MC/DC0%0/2
defined $r and length $r
defined $r
length $r
Truth table33%1/3
A and B
A= defined $rB= length $r
| |||||||||||||||||||||||||||||||||
| 37 | } | ||||||||||||||||||||||||||||||||
| 38 | |||||||||||||||||||||||||||||||||
| 39 | 17 | ▶ | sub _invalid ( $self, $desc ) { | ||||||||||||||||||||||||||||||
|
Subroutine
_invalid: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||
| 40 | 17 | Catalyst::Plugin::OAuth2::ResourceServer::Error->throw( | |||||||||||||||||||||||||||||||
| 41 | error => 'invalid_token', | ||||||||||||||||||||||||||||||||
| 42 | error_description => $desc, | ||||||||||||||||||||||||||||||||
| 43 | http_status => 401, | ||||||||||||||||||||||||||||||||
| 44 | ); | ||||||||||||||||||||||||||||||||
| 45 | } | ||||||||||||||||||||||||||||||||
| 46 | |||||||||||||||||||||||||||||||||
| 47 | # Verify a bearer JWT: signature + alg allowlist + exp/nbf/iat (with leeway) + | ||||||||||||||||||||||||||||||||
| 48 | # iss, then an explicit aud-membership check against our own resource(s). | ||||||||||||||||||||||||||||||||
| 49 | # Returns the claims, or throws a 401 invalid_token (reason never leaked). | ||||||||||||||||||||||||||||||||
| 50 | # | ||||||||||||||||||||||||||||||||
| 51 | # Crypt::JWT verify_* semantics (see its POD): 1 = claim REQUIRED and valid, | ||||||||||||||||||||||||||||||||
| 52 | # undef = "validate only if present". exp is required (a token with no expiry | ||||||||||||||||||||||||||||||||
| 53 | # is never acceptable here). nbf and iat are optional per RFC 7519 4.1.5/4.1.6 | ||||||||||||||||||||||||||||||||
| 54 | # and the companion AuthorizationServer mints no nbf at all, so both are | ||||||||||||||||||||||||||||||||
| 55 | # validate-if-present: requiring them would reject legitimate tokens. Note | ||||||||||||||||||||||||||||||||
| 56 | # verify_iat is asymmetric in Crypt::JWT -- omitting the key entirely disables | ||||||||||||||||||||||||||||||||
| 57 | # the iat check completely, so it must be passed explicitly as undef. | ||||||||||||||||||||||||||||||||
| 58 | 35 | ▶ | sub verify_token ( $self, $jwt ) { | ||||||||||||||||||||||||||||||
|
Subroutine
verify_token: called CC=5 SCAR=16.1
Pod
documented
| |||||||||||||||||||||||||||||||||
| 59 | 35 | ▶ | my $claims = try { | ||||||||||||||||||||||||||||||
|
Subroutine
__ANON__: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||
| 60 | 35 | decode_jwt( | |||||||||||||||||||||||||||||||
| 61 | token => $jwt, | ||||||||||||||||||||||||||||||||
| 62 | key => $self->signing_key, | ||||||||||||||||||||||||||||||||
| 63 | accepted_alg => [ $self->jwt_alg ], | ||||||||||||||||||||||||||||||||
| 64 | verify_exp => 1, | ||||||||||||||||||||||||||||||||
| 65 | verify_nbf => undef, | ||||||||||||||||||||||||||||||||
| 66 | verify_iat => undef, | ||||||||||||||||||||||||||||||||
| 67 | leeway => $self->leeway, | ||||||||||||||||||||||||||||||||
| 68 | verify_iss => $self->issuer, | ||||||||||||||||||||||||||||||||
| 69 | ); | ||||||||||||||||||||||||||||||||
| 70 | } | ||||||||||||||||||||||||||||||||
| 71 | 15 | ▶ | catch { | ||||||||||||||||||||||||||||||
|
Subroutine
__ANON__: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||
| 72 | 15 | $self->_invalid('token verification failed'); | |||||||||||||||||||||||||||||||
| 73 | 35 | }; | |||||||||||||||||||||||||||||||
| 74 | |||||||||||||||||||||||||||||||||
| 75 | 20 | ▶ | $self->_invalid('token payload is not a claims object') | ||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||
| 76 | unless ref $claims eq 'HASH'; | ||||||||||||||||||||||||||||||||
| 77 | |||||||||||||||||||||||||||||||||
| 78 | my @aud = | ||||||||||||||||||||||||||||||||
| 79 | 1 | ▶ | ref $claims->{aud} eq 'ARRAY' ? @{ $claims->{aud} } | ||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||
| 80 | : defined $claims->{aud} ? ( $claims->{aud} ) | ||||||||||||||||||||||||||||||||
| 81 | 20 | ▶ | : (); | ||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||
| 82 | 20 | my %ok = map { $_ => 1 } @{ $self->_resource_list }; | |||||||||||||||||||||||||||||||
| 83 | $self->_invalid('audience mismatch') | ||||||||||||||||||||||||||||||||
| 84 | 20 | ▶ | unless grep { $ok{$_} } @aud; | ||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||
| 85 | |||||||||||||||||||||||||||||||||
| 86 | 18 | return $claims; | |||||||||||||||||||||||||||||||
| 87 | } | ||||||||||||||||||||||||||||||||
| 88 | |||||||||||||||||||||||||||||||||
| 89 | =head1 NAME | ||||||||||||||||||||||||||||||||
| 90 | |||||||||||||||||||||||||||||||||
| 91 | Catalyst::Plugin::OAuth2::ResourceServer::Server - bearer-JWT verification | ||||||||||||||||||||||||||||||||
| 92 | engine for the ResourceServer plugin | ||||||||||||||||||||||||||||||||
| 93 | |||||||||||||||||||||||||||||||||
| 94 | =head1 DESCRIPTION | ||||||||||||||||||||||||||||||||
| 95 | |||||||||||||||||||||||||||||||||
| 96 | Pure-logic engine (a Moo object) that holds the verification parameters and | ||||||||||||||||||||||||||||||||
| 97 | performs bearer-JWT validation independently of Catalyst. Attributes: | ||||||||||||||||||||||||||||||||
| 98 | C<signing_key> (required), C<resource> (required: scalar or arrayref), | ||||||||||||||||||||||||||||||||
| 99 | C<issuer> (required), C<jwt_alg> (default C<HS256>), C<leeway> (default 0). | ||||||||||||||||||||||||||||||||
| 100 | |||||||||||||||||||||||||||||||||
| 101 | The engine is constructed per request by the Catalyst seam | ||||||||||||||||||||||||||||||||
| 102 | (L<Catalyst::Plugin::OAuth2::ResourceServer>) from the app config, so there is | ||||||||||||||||||||||||||||||||
| 103 | no persistent state between requests. | ||||||||||||||||||||||||||||||||
| 104 | |||||||||||||||||||||||||||||||||
| 105 | =head1 METHODS | ||||||||||||||||||||||||||||||||
| 106 | |||||||||||||||||||||||||||||||||
| 107 | =head2 verify_token( $jwt ) | ||||||||||||||||||||||||||||||||
| 108 | |||||||||||||||||||||||||||||||||
| 109 | my $claims = $engine->verify_token($bearer_token_string); | ||||||||||||||||||||||||||||||||
| 110 | |||||||||||||||||||||||||||||||||
| 111 | Verifies a bearer JWT string. Steps performed: | ||||||||||||||||||||||||||||||||
| 112 | |||||||||||||||||||||||||||||||||
| 113 | =over 4 | ||||||||||||||||||||||||||||||||
| 114 | |||||||||||||||||||||||||||||||||
| 115 | =item * Signature verification using C<signing_key> and the HS-alg allowlist | ||||||||||||||||||||||||||||||||
| 116 | (C<HS256>, C<HS384>, C<HS512> only: C<alg=none> and asymmetric algorithms | ||||||||||||||||||||||||||||||||
| 117 | are always rejected). | ||||||||||||||||||||||||||||||||
| 118 | |||||||||||||||||||||||||||||||||
| 119 | =item * Expiry (C<exp>) check with optional C<leeway> seconds of clock-skew | ||||||||||||||||||||||||||||||||
| 120 | tolerance. C<exp> is B<required>: a token carrying no expiry is rejected. | ||||||||||||||||||||||||||||||||
| 121 | |||||||||||||||||||||||||||||||||
| 122 | =item * Not-before (C<nbf>) and issued-at (C<iat>) checks, also honouring | ||||||||||||||||||||||||||||||||
| 123 | C<leeway>. Both claims are optional (RFC 7519 4.1.5 and 4.1.6), so they are | ||||||||||||||||||||||||||||||||
| 124 | validated only when present: a token whose C<nbf> is in the future, or whose | ||||||||||||||||||||||||||||||||
| 125 | C<iat> is in the future, is rejected, but a token omitting either verifies | ||||||||||||||||||||||||||||||||
| 126 | normally. This matches what | ||||||||||||||||||||||||||||||||
| 127 | L<Catalyst::Plugin::OAuth2::AuthorizationServer> mints, which stamps C<iss>, | ||||||||||||||||||||||||||||||||
| 128 | C<aud>, C<iat> and C<exp> but no C<nbf>. | ||||||||||||||||||||||||||||||||
| 129 | |||||||||||||||||||||||||||||||||
| 130 | =item * Issuer (C<iss>) match against the configured C<issuer>. The match is | ||||||||||||||||||||||||||||||||
| 131 | an exact string comparison, not a substring or prefix match: an C<iss> of | ||||||||||||||||||||||||||||||||
| 132 | C<https://as.exampleEVIL> does not satisfy a configured issuer of | ||||||||||||||||||||||||||||||||
| 133 | C<https://as.example>. | ||||||||||||||||||||||||||||||||
| 134 | |||||||||||||||||||||||||||||||||
| 135 | =item * Payload type guard: the decoded payload must be a claims hashref. | ||||||||||||||||||||||||||||||||
| 136 | |||||||||||||||||||||||||||||||||
| 137 | =item * Audience (C<aud>) membership check: at least one C<aud> value must | ||||||||||||||||||||||||||||||||
| 138 | match one of the configured C<resource> identifiers. | ||||||||||||||||||||||||||||||||
| 139 | |||||||||||||||||||||||||||||||||
| 140 | =back | ||||||||||||||||||||||||||||||||
| 141 | |||||||||||||||||||||||||||||||||
| 142 | Returns the claims hashref on success. Throws a 401 | ||||||||||||||||||||||||||||||||
| 143 | L<Catalyst::Plugin::OAuth2::ResourceServer::Error> with C<error = | ||||||||||||||||||||||||||||||||
| 144 | 'invalid_token'> on any failure; the error description is never forwarded to | ||||||||||||||||||||||||||||||||
| 145 | clients. | ||||||||||||||||||||||||||||||||
| 146 | |||||||||||||||||||||||||||||||||
| 147 | =cut | ||||||||||||||||||||||||||||||||
| 148 | |||||||||||||||||||||||||||||||||
| 149 | 5 | 1; | |||||||||||||||||||||||||||||||