Learn how to configure Single Sign-On (SSO) integration with JWT for secure and seamless login in vFairs events.
Overview
JSON Web Token (JWT) is a compact, URL-safe means of representing claims to be transferred between two parties. It is used for authentication and information exchange.
A JWT is composed of three parts:
- Header: Contains metadata about the token, including the type of token and the signing algorithm used.
- Payload: Contains the claims (statements about an entity and additional data), such as user ID, roles, and permissions.
- Signature: A cryptographic signature that verifies the integrity of the token and authenticates the sender. It is created using the header, payload, and a secret key.
Configure your JWT Implementation
To set up Single Sign-On (SSO) for a user using JSON Web Tokens (JWT) with vFairs, follow the steps below:
Prerequisites
- User Management System: Ensure you have a system that can manage user authentication and generate user attributes.
- Secret Key: Navigate to Event Setup >> API tab >> copy APP Key value or ask
your vFairs project manager. This key is used to sign your JWT.
Step # 01: Prepare the JWT Payload
1.1 Define Required Attributes: You must include the following mandatory user attributes in the JWT payload:
-
- first_name: User’s first name (Mandatory)
-
- last_name: User’s last name (Mandatory)
-
- email: User’s email address (Mandatory, used for unique identification)
-
- You can also include additional user profile data as needed, which will be synchronized between your user management system and vFairs.
1.2 Create the JWT Header: Specify the JWT algorithm in the header. Use the following JSON structure: {"typ": "JWT", "alg": "HS256"}
- HS256: This stands for HMAC SHA 256, a secure encryption algorithm developed by the U.S. National Security Agency.
1.3 Construct the JWT Payload: Construct your JWT payload by including the user attributes prepared in point 1. The payload must be formatted as a JSON object.
1.4 Sign the JWT: Implementing JWT requires using a secret key and a hashing algorithm to generate a secure token. Your vFairs project manager will provide the necessary secret key.
Step # 02: Encode the JWT
Base64 Encode the JWT: Once the JWT is constructed, encode it using Base64 encoding.
Step # 03: Redirect User to vFairs
3.1 Prepare the Redirect URL: Redirect the user to the vFairs SSO endpoint using the following URL format:
https://mycompany.vfairs.com/en/sso_login?jwt={base64_encoded_payload}
Ensure the JWT payload is appended as a query string after the jwt= parameter.
3.2 Use HTTPS Protocol: Ensure that the JWT payload is sent to your vFairs Event subdomain using the HTTPS protocol.
Note: Host-mapped subdomains are not supported; ensure you are using the correct subdomain.
3.3 Session Granting: vFairs receives the request and parses the user details from the JWT payload. If the token is valid and the user details are correct, vFairs grants the user a session, allowing access to the event.
Step # 04: Handle the Return URL (Optional)
4.1 Extract the return_to Parameter: When vFairs redirects a user to your login script, it will include a return_to parameter in the URL. This parameter indicates the page to which the user should be redirected after successful authentication.e.g.https://mycompany.com/vfairs/sso_login?return_to=https://mycompany.vfairs.com/en/sso_login
4.2 Submit the JWT: When submitting the JWT token back to vFairs, include the return_to value from the invoked URL in your submission.
Notes:
- Browser-Based Redirects: The entire process relies on browser redirects and the secure transmission of signed messages using JWT. All redirects occur within the browser environment, ensuring that there is no direct connection between vFairs and your internal systems.
- Security: By handling the authentication process on your side, you can keep your authentication scripts securely behind your corporate firewall, reducing the risk of unauthorized access.
Sample Node.js Code
const jwt = require('jsonwebtoken');
// Configuration
const secretKey = 'YOUR_SECRET_KEY'; // Replace with the secret key provided by your vFairs project manager.
const vFairsDomain = 'https://mycompany.vfairs.com/en/sso'; // Replace with your vFairs subdomain.
// Function to create a JWT for SSO
function createJWT(userAttributes) {
// 1. Define JWT header
const header = {
typ: 'JWT',
alg: 'HS256'
};
// 2. Create the JWT payload
const payload = {
email: userAttributes.email, // Required attribute
firstName: userAttributes.firstName || '', // Optional
lastName: userAttributes.lastName || '', // Optional
// Add any other optional attributes here
};
// 3. Sign the JWT with the secret key
const token = jwt.sign(payload, secretKey, { header });
return token;
}
// Function to redirect user to vFairs with the JWT
function redirectToVFairs(userAttributes) {
const jwtToken = createJWT(userAttributes);
// 4. Construct the redirect URL
const redirectURL = `${vFairsDomain}?jwt=${encodeURIComponent(jwtToken)}`;
// 5. Redirect the user (this example just logs the URL)
console.log(`Redirecting to: ${redirectURL}`);
// In an actual web server implementation, you might use:
// res.redirect(redirectURL);
}
// Example user attributes
const userAttributes = {
email: 'user@example.com', // Required
firstName: 'John', // Optional
lastName: 'Doe' // Optional
};
// Redirect the user
redirectToVFairs(userAttributes);