okta / jwt-verifier
A verifier library for working with Okta JWT's
Installs: 1 974 462
Dependents: 1
Suggesters: 0
Security: 0
Stars: 35
Watchers: 90
Forks: 63
Open Issues: 17
Requires
- php: ^7.4 || ^8.0
- ext-json: *
- bretterer/iso_duration_converter: ^0.1.0
- illuminate/cache: ^8.83.1 || ^9.0
- nesbot/carbon: ^2.0
- php-http/client-common: ^2.3
- php-http/curl-client: ^2.1
- php-http/discovery: ^1.9
- php-http/httplug: ^2.2
- php-http/message: ^1.8
- psr/http-message: ^1.0
Requires (Dev)
- firebase/php-jwt: ^5.2
- guzzlehttp/psr7: ~2.0.0
- mockery/mockery: ^1.5
- php-http/mock-client: ^1.4
- phpunit/phpunit: ^9.0
- squizlabs/php_codesniffer: ^3.5
- symfony/var-dumper: ^5.1
This package is not auto-updated.
Last update: 2023-02-16 20:31:48 UTC
README
NOTICE: We're excited about the acquisition of Auth0 to bring you better support in PHP. This repo will be placed into security patch only mode and we will not be adding any further features. If you are looking for an API that is not supported in this library, please call the API directly. Our documentation for the supported Management APIs are located here: https://developer.okta.com/docs/reference/core-okta-api/. Please reach out to the DevForum for any questions.
Okta JWT Verifier for PHP
As a result of a successful authentication by obtaining an authorization grant from a user or using the Okta API, you will be
provided with a signed JWT (id_token
and/or access_token
). A common use case for these access tokens is to use it
inside of the Bearer authentication header to let your application know who the user is that is making the request. In
order for you to know this use is valid, you will need to know how to validate the token against Okta. This guide gives
you an example of how to do this using Okta's JWT Validation library for PHP.
This code does not work with the default authorization server. You must be using a custom authorization server. Please check if this is the case before using this code.
Release status
This library uses semantic versioning and follows Okta's library version policy.
Version | Status |
---|---|
0.x | ⚠️ Beta Release (Retired) |
1.x | ✔️ Release |
The latest release can always be found on the releases page.
Installation
The Okta JWT Verifier can be installed through composer.
composer require okta/jwt-verifier
This library requires a JWT library. We currently support firebase/php-jwt version 5.2. You will have to install this or create your own adaptor.
composer require firebase/php-jwt ^5.2
To create your own adaptor, just implement the Okta/JwtVerifier/Adaptors/Adaptor
in your own class.
You will also need to install a PSR-7 compliant library. We suggest that you use guzzlehttp/psr7
in your project.
composer require guzzlehttp/psr7
Setting up the Library
To validate a JWT, you will need a few different items:
- Your issuer URL
- The JWT string you want to verify
- Access to your vendor autoload file in your script.
require_once("/vendor/autoload.php"); // This should be replaced with your path to your vendor/autoload.php file $jwtVerifier = (new \Okta\JwtVerifier\JwtVerifierBuilder()) ->setDiscovery(new \Okta\JwtVerifier\Discovery\Oauth) // This is not needed if using oauth. The other option is `new \Okta\JwtVerifier\Discovery\OIDC` ->setAdaptor(new \Okta\JwtVerifier\Adaptors\FirebasePhpJwt) ->setAudience('api://default') ->setClientId('{clientId}') ->setIssuer('https://{yourOktaDomain}.com/oauth2/default') ->build();
Caching
It's strongly suggested to cache the keys to improve performance. You can pass an implementation of \Psr\SimpleCache\CacheInterface
to the Adaptor constructor.
For example, in laravel:
// note: named parameters are only valid for php >= 8.0 ->setAdaptor(new \Okta\JwtVerifier\Adaptors\FirebasePhpJwt(request: null, leeway: 120, cache: app('cache')->store()))
If using symphony, you may need to use an adaptor: https://symfony.com/doc/current/components/cache/psr6_psr16_adapters.html
Validating an Access Token
After you have a $jwtVerifier
from the above section and an access_token
from a successful sign in, or
from a Bearer token
in the authorization header, you will need to make sure that it is still valid.
All you need to do is call the verifyAccessToken
method (where $jwtString
is your access token in string format).
$jwt = $jwtVerifier->verifyAccessToken($jwtString);
This will validate your JWT for the following:
- token expiration time
- the time it was issue at
- that the token issuer matches the expected value passed into the above helper
- that the token audience matches the expected value passed into the above helper
The result from the verify method is a Jwt
object which has a few helper methods for you:
dump($jwt); //Returns instance of \Okta\JwtVerifier\JWT dump($jwt->toJson()); // Returns Claims as JSON Object dump($jwt->getClaims()); // Returns Claims as they come from the JWT Package used dump($jwt->getIssuedAt()); // returns Carbon instance of issued at time dump($jwt->getIssuedAt(false)); // returns timestamp of issued at time dump($jwt->getExpirationTime()); //returns Carbon instance of Expiration Time dump($jwt->getExpirationTime(false)); //returns timestamp of Expiration Time
Validating an Id Token
$jwt = $jwtVerifier->verifyIdToken($jwtString);
This will validate your JWT for the following:
- token expiration time
- the time it was issue at
- that the token issuer matches the expected value passed into the above helper
- that the token audience matches the expected value passed into the above helper
The result from the verify method is a Jwt
object which has a few helper methods for you:
dump($jwt); //Returns instance of \Okta\JwtVerifier\JWT dump($jwt->toJson()); // Returns Claims as JSON Object dump($jwt->getClaims()); // Returns Claims as they come from the JWT Package used dump($jwt->getIssuedAt()); // returns Carbon instance of issued at time dump($jwt->getIssuedAt(false)); // returns timestamp of issued at time dump($jwt->getExpirationTime()); //returns Carbon instance of Expiration Time dump($jwt->getExpirationTime(false)); //returns timestamp of Expiration Time
Need help?
If you run into problems using the SDK, you can
- Ask questions on the Okta Developer Forums
- Post issues here on GitHub
- Working With OAuth 2.0 Tokens
Conclusion
The above are the basic steps for verifying an access token locally. The steps are not tied directly to a framework so
you could plug in the okta/okta-jwt
into the framework of your choice.