Custom authentication
Para supports custom authentication through the PasswordlessAuthFilter. A trusted service can verify a user’s identity,
then send a signed JWT to Para. Para can then authenticate or create the user without a Para password.
Only send a token after your service has verified the user’s identity. Para creates new users as active, without email verification, when it accepts a valid user JWT.
Endpoint and parameters
Section titled “Endpoint and parameters”The default endpoint is /passwordless_auth. It accepts these request parameters:
| Parameter | Description |
|---|---|
token or jwt | A compact JWT. If both are set, Para uses token. The JWT can be a custom user JWT or a short-lived app proof. |
appid | The app identifier, such as myapp. You can omit it when the JWT has an appid claim. In a JWT claim, use the full Para app ID, such as app:myapp. |
redirect | Set to false to disable redirects and return a Para JWT as plain text. Redirects are enabled by default. |
httpOnlyCookie | Set to false to disable the HttpOnly cookie flag. The default is true. This parameter applies when redirects are enabled. |
sameSiteCookie | The cookie’s SameSite value. The default is Strict. This parameter applies when redirects are enabled. |
When redirects are enabled, Para sets an authentication cookie and redirects the user. The cookie name comes from the app’s
auth_cookie setting. If this setting is not present, Para uses <app identifier>-auth, for example myapp-auth. The
cookie age comes from the app’s session_timeout setting, or from the app’s token validity time if no timeout is set.
The success redirect uses the app setting returnto, or the global setting para.security.returnto. The failure redirect
uses the app setting signin_failure, or the global setting para.security.signin_failure. When redirects are enabled,
both URLs must be absolute.
This filter uses returnto as its success destination; it does not use signin_success for that redirect. Other sign-in
filters can use signin_success to send a user to /passwordless_auth.
Set redirect=false when your backend needs to read the Para JWT directly. On success, Para returns a text/plain
response with a newly generated Para JWT. This is not the input JWT. If the request uses an app proof, Para returns an app
JWT, not a user JWT.
User authentication with a custom JWT
Section titled “User authentication with a custom JWT”The custom user JWT must be signed with the app’s app_secret_key. Para checks its signature and its time claims. The
JWT must have an exp claim. Para also checks nbf when it is present. Include iat and use a short validity period,
such as 10 minutes.
Para reads these claims from a user JWT:
| Claim | Use |
|---|---|
identifier | A stable, unique user identifier, such as custom:1234. |
email | The user’s email address. |
name | The user’s display name. |
appid | The full Para app ID, such as app:myapp. You can leave this out if you pass appid in the request. |
groups | Optional group names as a string. New users get the users group if this claim is missing or blank. |
picture | Optional URL for the user’s picture. |
Para uses the identity claims to find or create a user. It can update the user’s name, email, picture, and groups from the
claims. Use the same stable identifier for the same user each time.
Configure the signing secret
Section titled “Configure the signing secret”Use the same app_secret_key in Para and in the service that signs the JWT. For the root app, set para.app_secret_key:
para.app_secret_key = "secretsecretsecretsecretsecret12"For a child app, set app_secret_key in the app’s settings:
{ "id": "app:myapp", "settings": { "app_secret_key": "secretsecretsecretsecretsecret12" }}If you do not set app_secret_key, Para uses the app’s own secret. For an existing Para user, the filter also accepts a
Para-issued user token signed with the app secret and that user’s token secret. This supports Para’s own ID-token flow.
The key below is an example only. It is not a safe production secret. Use a random secret with at least 32 bytes, store it only on trusted servers, and do not put it in browser code.
Generate a custom User JWT in Java
Section titled “Generate a custom User JWT in Java”This example uses Nimbus JOSE+JWT. Add com.nimbusds:nimbus-jose-jwt to your backend if it does not already include it.
import com.nimbusds.jose.JOSEException;import com.nimbusds.jose.JWSAlgorithm;import com.nimbusds.jose.JWSHeader;import com.nimbusds.jose.crypto.MACSigner;import com.nimbusds.jwt.JWTClaimsSet;import com.nimbusds.jwt.SignedJWT;import java.util.Date;
public class PasswordlessJwtExample { public static String createUserToken() throws JOSEException { // Use the same value as app_secret_key in Para. String secret = "secretsecretsecretsecretsecret12"; Date now = new Date();
JWTClaimsSet claims = new JWTClaimsSet.Builder() .claim("appid", "app:myapp") .claim("identifier", "custom:1234") .claim("name", "Ada Lovelace") .claim("groups", "users") .claim("picture", "https://example.com/ada.png") .issueTime(now) .notBeforeTime(now) .expirationTime(new Date(now.getTime() + 10 * 60 * 1000L)) .build();
SignedJWT jwt = new SignedJWT(new JWSHeader(JWSAlgorithm.HS256), claims); jwt.sign(new MACSigner(secret)); return jwt.serialize(); }}Send the compact JWT to Para over HTTPS. For example, use a form-encoded POST request:
POST https://para-host/passwordless_auth?appid=myapp&redirect=falseContent-Type: application/x-www-form-urlencoded
token=<compact-JWT>The successful response body contains the Para JWT. You can send that JWT in a later request to /v1/_me to check the
current user. Do not log access tokens or expose them to third-party sites.
Authentication flow
Section titled “Authentication flow”- The user signs in to your service.
- Your service verifies the user’s identity and signs a short-lived user JWT.
- The user’s browser or your backend sends the JWT to
/passwordless_auth. - Para validates the JWT, then finds or creates the user.
- Para sets an authentication cookie and redirects the user, or returns a Para JWT when
redirect=false.
Short-lived app proof
Section titled “Short-lived app proof”The filter also accepts a short-lived JWT that authenticates the app itself. This is an app proof, not a user JWT. Sign it
with the Para app secret (App.getSecret()), not the custom app_secret_key, and include these claims:
appid- the full Para app ID, such asapp:myapp.iat- the time when the proof was created.exp- the expiration time. The time fromiattoexpmust be no more than 30 seconds.
The proof must have a valid signature and must not be expired. It can also contain returnto and signin_failure claims
to override the app’s redirect settings. Use this flow only for app-level authentication. Do not use it to authenticate a
user.
Use with social login
Section titled “Use with social login”You can also send a Para-issued ID token to the passwordless filter after a social login. For example, use this configuration:
para.gp_app_id = "google app id"para.gp_secret = "google app secret"para.security.returnto = "http://localhost:8080/dashboard"para.security.signin_success = "http://localhost:8080/passwordless_auth?jwt=id&httpOnlyCookie=true&sameSiteCookie=Lax"para.security.signin_failure = "http://localhost:8080/signin?error=true"- The user signs in with Google. Google redirects to Para’s
/google_authendpoint. Add this callback URL to your Google settings. - Para verifies the social login and redirects to the
signin_successURL with a short-lived ID token. - The passwordless filter validates the ID token, sets a Para authentication cookie, and redirects the user to
returnto.