Security

To report a bug or security issue, please send an email to [email protected]. We will reply to your email within 24 hours.
Auth Tokens
Passage uses JSON Web Tokens (JWTs) to prove the identity of users for your applications. A critical part of using Passage is ensuring that the JWTs created on behalf of your users are valid.
What is a JWT?
A JSON Web Token (JWT) (pronounced "jot") is a compact, URL-safe means of representing claims to be transferred between two parties. The claims in a JWT are encoded as a JSON object that is used as the payload and can be digitally signed or integrity protected with a Message Authentication Code (MAC) and/or encrypted. A JWT is represented as a sequence of URL-safe parts separated by period ('.') characters. Each part contains a base64url-encoded value.
The main benefits of JWTs are that they are easy to use and more secure than a shared secret. JWTs can use a private/public keypair for signing, which provides better security in the case of Passage, where users need to be able to retrieve the verification information from Passage. In the case of private/public key pairs, Passage can just share the public key and keep the private key protected.
JWTs can be used for authentication and authorization. A valid JWT containing a userID indicates that the user has successfully authenticated to the application. This token can also be used to perform access checks for that user to grant them access to specific application resources. JWTs are most commonly sent in HTTP headers.
Anatomy of a Passage JWT
An example Passage JWT is shown below:
// A header describing the algorithm and token type:
{
    "alg": "RS256",
    "typ": "JWT"
}.
// The payload/claims:
{
  "exp": 1623725098,
  "iss": "dk8fn3fns93kJD6Vdj1k",
  "sub": "kDqAfJcRExEXccEpEYNI"
}.
// The signature:
WUro5...FxA
Claim
Description
exp
Expiration – the time when the token is no longer valid. The session expiration time is configurable in the Passage Console.
iss
Issuer – the ID of the Passage App that issued the auth token.
sub
Subject – the ID of the Passage User who was issued the auth token.
Verifying a JWT on Your Server
The easiest way to verify a Passage JWT on your web server is using one of the Passage backend libraries. For any language without a Passage backend library, there is likely a popular JWT library you can use. We've compiled a list of popular third-party JWT libraries below:
Language/Framework
Library
Java
​https://github.com/jwtk/jjwt​
Python (Django or Flask)
​https://github.com/jpadilla/pyjwt​
NodeJS
​https://github.com/panva/jose​
PHP
​https://github.com/lcobucci/jwt​
Ruby
​https://github.com/jwt/ruby-jwt​
Scala
​https://github.com/jwt-scala/jwt-scala​
WebAuthn
WebAuthn enables the creation and use of strong public key-based credentials by web applications, for the purpose of authenticating users. Credentials are tied to a specific domain or origin when they are created and can only be used for that specific origin. The credentials are also bound to the device on which they were created. Most commonly, these credentials are based on biometrics information, using Face ID or Windows Hello, for example.
Benefits of WebAuthn
There's ample evidence to support that passwords are the internet's weakest link. Common mitigations to protect users and reduce account takeover (ATO), including two-factor authentication, require work for developers and friction for end-users. WebAuthn is a simple single-step alternative that cannot be brute-forced or phished.
WebAuthn Challenges (and how we help!)
WebAuthn-based authentication can be very complex to implement in practice, as the specification doesn't describe how to handle authentication across multiple devices. For example, you would traditionally login to a website with the same password on both your mobile phone and your laptop. However, with WebAuthn, you would need to register both your mobile phone's biometric device and your laptop's biometric device in order to login from either platform.
This is where we come in. Passage manages all of the complexity of registering new devices to deliver a seamless experience for your users. We've thought through a long list of edge cases and security concerns so you don't have to.
Currently, not all browsers support WebAuthn in the same way. Passage can seamlessly adjust to different user agents with no work on your part, and fall back to a different form of passwordless authentication in the event that a user's browser does not support WebAuthn at all.

⚡️ Advanced - Previous

Platform Compatibility

Last modified 10mo ago

Copy link

Outline

Auth Tokens

What is a JWT?

Anatomy of a Passage JWT

Verifying a JWT on Your Server

WebAuthn

Benefits of WebAuthn

WebAuthn Challenges (and how we help!)