Customer Portal SSO via JWT

Modified on Tue, 17 Dec at 8:52 AM

Configuring JWT Single Sign-On (SSO) with Benji Pays

To enable Single Sign-On (SSO) using JSON Web Tokens (JWT) in Benji Pays, follow the steps outlined below. This guide will ensure your integration meets the requirements for secure authentication.

Step 1: Set Up the SSO Configuration in Benji Pays

Log in to Benji Pays.
Navigate to Settings » Customer Portal Settings » SSO Configuration.
Click on Add Configuration.
Select JWT as the SSO type.

Complete the Form

Description: Provide a descriptive name for this SSO configuration.
Remote Login URL: Enter the URL where users will be sent to log in on your system (e.g., https://your-sso-provider.com/login).
Login Redirect URL: This URL is automatically generated. It points to the callback endpoint on Benji Pays (e.g., https://yourportaldomain.com/callbackjwt).
ISS (Issuer): This value will act as the iss claim in your JWT payload.
Login Button Text: Customize the button text that users will see for SSO login.

Once the form is complete, click Save.

Obtain Key Configuration Details

After saving, the form will display the following critical information that you'll need to configure your JWT:

AUDIENCE: The expected audience (aud) for the JWT.
ISSUER (ISS): The value to include in the iss claim.
CLIENTID: Your unique client identifier.
CLIENTSECRET: Your shared secret for signing JWTs.

Step 2: Generate the JWT

Your system will generate a JWT containing the required claims and send it as part of the authentication process.

JWT Requirements

Header:
```
{
  "alg": "HS256",
  "typ": "JWT"
}
  
```
Payload:
The payload must include the following claims:
- iss (Issuer): Use the value provided in the ISS field from your SSO configuration.
- aud (Audience): Use the value provided in the AUDIENCE field.
- exp (Expiration Time): The token must expire no more than 5 minutes from the time of issuance.
- iat (Issued At): The time the token was issued. The token must not have been issued more than 30 seconds in the past when Benji Pays receives it.
- email: The email address of the user.
- sub: this is the unique id for your user that will not change and is unique and does not match theiremail address.
- client_id: The unique Client ID provided in your SSO configuration.

Example Payload:

{
  "iss": "paxxxxxps-jwt-dxxxxxx4",
  "aud": "AUDIENCE",
  "exp": 1700000000,
  "iat": 1699999400,
  "email": "[email protected]",
  "client_id": "provided-client-id"
}

Signature:
The JWT must be signed using the CLIENTSECRET with the HS256 algorithm.

Step 3: Submit the JWT

Once the JWT is generated, it must be submitted via a POST request to the /callbackjwt endpoint.

Form Submission

Form Method: POST
Action: https://yourportaldomain.com/callbackjwt
Hidden Form Field:
- Name: token
- Value: The JWT string.

Example Form:

<!DOCTYPE html>
<html>
<head>
  <title>SSO Login</title>
</head>
<body>
  <form action="https://yourportaldomain.com/callbackjwt" method="POST">
    <input type="hidden" name="token" value="YOUR_JWT_HERE">
    <button type="submit">Login with ACME Co.</button>
  </form>
</body>
</html>

Step 4: Authentication Flow

Users click the SSO login button in the customer portal.
They are redirected to your system’s login page via the Remote Login URL.
After successful login on your system, your system generates a JWT and submits it to the /callbackjwt endpoint via the hidden form field.
Benji Pays validates the JWT and logs the user into the customer portal.

Security Notes

Ensure the JWT includes all required claims, and the exp claim is no more than 5 minutes in the future.
Use HTTPS for all communication to secure data in transit.
Store the CLIENTSECRET securely and never expose it publicly.

By following these steps, you can successfully configure and use JWT SSO with Benji Pays to provide a seamless authentication experience for your users.