Skip to content

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.

The default endpoint is /passwordless_auth. It accepts these request parameters:

ParameterDescription
token or jwtA compact JWT. If both are set, Para uses token. The JWT can be a custom user JWT or a short-lived app proof.
appidThe 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.
redirectSet to false to disable redirects and return a Para JWT as plain text. Redirects are enabled by default.
httpOnlyCookieSet to false to disable the HttpOnly cookie flag. The default is true. This parameter applies when redirects are enabled.
sameSiteCookieThe 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.

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:

ClaimUse
identifierA stable, unique user identifier, such as custom:1234.
emailThe user’s email address.
nameThe user’s display name.
appidThe full Para app ID, such as app:myapp. You can leave this out if you pass appid in the request.
groupsOptional group names as a string. New users get the users group if this claim is missing or blank.
pictureOptional 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.

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-application.conf
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.

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("email", "[email protected]")
.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=false
Content-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.

  1. The user signs in to your service.
  2. Your service verifies the user’s identity and signs a short-lived user JWT.
  3. The user’s browser or your backend sends the JWT to /passwordless_auth.
  4. Para validates the JWT, then finds or creates the user.
  5. Para sets an authentication cookie and redirects the user, or returns a Para JWT when redirect=false.

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 as app:myapp.
  • iat - the time when the proof was created.
  • exp - the expiration time. The time from iat to exp must 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.

You can also send a Para-issued ID token to the passwordless filter after a social login. For example, use this configuration:

para-application.conf
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"
  1. The user signs in with Google. Google redirects to Para’s /google_auth endpoint. Add this callback URL to your Google settings.
  2. Para verifies the social login and redirects to the signin_success URL with a short-lived ID token.
  3. The passwordless filter validates the ID token, sets a Para authentication cookie, and redirects the user to returnto.