Single Sign-On (SSO) with JWT (RS256) in Akinon Commerce

This guide describes how to implement Single Sign-On (SSO) between your Identity Provider (IdP) and Akinon Commerce (Service Provider - SP) using JSON Web Tokens (JWT) signed with the RS256 algorithm.

In a typical SSO scenario, a user logs in to an external authentication platform that manages a global user account. The user’s credentials are verified on this external system, and upon successful authentication, access to Akinon Commerce is granted via an OAuth-based integration.

This approach ensures that:

• User identity is managed centrally.

• The same account can be used across multiple services.

• Akinon Commerce sessions are created without requiring the user to re-enter their credentials.

By leveraging JWT claims and public/private key cryptography, this method enables secure and seamless user authentication across platforms without requiring repeated logins.

Key Components

Identity Provider (IdP)

The external authentication system that:

• Authenticates users on its own platform.

• Issues JWTs upon successful authentication.

• Signs JWTs using a private RSA key (RS256 algorithm).

• Shares the corresponding public_key with Akinon Commerce for token verification.

Service Provider (SP) — Akinon Commerce

Akinon receives the JWT from the IdP, performs necessary validations using the public_key, and:

• Manages the authenticated user session.

• Creates or updates the user profile based on token data.

Security Overview with RS256

The RS256 algorithm is an asymmetric encryption scheme using a public/private key pair:

• JWT Signing: JWTs are signed by the IdP using its private key.

• JWT Verification: Akinon Commerce verifies the token using the public_key provided by the IdP.

This ensures:

• Token authenticity (cannot be forged by third parties).

• Safe identity exchange between the IdP and Akinon Commerce.

JWT Payload & Claims

The JWT must contain both standard and custom claims to represent user data and ensure validation.

Standard Claims

Claim	Description
sub	Subject — The unique user identifier assigned by the IdP.
aud	Audience — Indicates that the JWT is intended for Akinon Commerce, as specified by the IdP.
exp	Expiration Time — The timestamp (Unix format) after which the JWT becomes invalid.
iat	Issued At — The timestamp (Unix format) indicating when the JWT was created.
jti	JWT ID — A unique identifier for this specific JWT instance.

Custom User Claims (Required by Akinon)

Claim	Description
email	User’s email address
first_name	User’s first name
last_name	User’s last name
phone	Phone number in international format
email_allowed	Whether the user accepts emails (Boolean)
sms_allowed	Whether the user accepts SMS (Boolean)
call_allowed	Whether the user accepts calls (Boolean)
gender	Gender of the user (nullable)
date_of_birth	Date of birth in YYYY-MM-DD format

Sample JWT Payload

{
  "sub": "UserID",
  "aud": "client_id",
  "exp": 1814944520,
  "iat": 1714944520,
  "jti": "unique-jwt-id",
  "email": "[email protected]",
  "first_name": "John",
  "last_name": "Doe",
  "phone": "[phone]",
  "email_allowed": true,
  "sms_allowed": false,
  "call_allowed": true,
  "gender": null,
  "date_of_birth": "1990-01-01"
}

JWT Transmission Flow

1. Token Issuance by IdP

Once the user successfully authenticates, the IdP generates a JWT and signs it with its private RSA key.

2. Transmission to Akinon Commerce

The IdP sends the signed JWT via a secure HTTP POST request.

Endpoint Information:

Method	POST
URL	https://uuid.lb.akinoncloud.com/jwt_sso/login/callback/
Content-Type	application/json

Example Request

POST /jwt_sso/login/callback/ HTTP/1.1
Host: uuid.lb.akinoncloud.com
Content-Type: application/json

{
  "token": "ENCODED_JWT_HERE"
}

Example Successful Response

HTTP/1.1 200 OK
Content-Type: application/json
Set-Cookie: csrftoken=...; expires=...; Path=/;
Set-Cookie: sessionid=...; expires=...; HttpOnly;

{}

Cookies like csrftoken and sessionid must be retained and sent with subsequent requests to maintain the user session.

Session & User Management in Akinon

Once Akinon Commerce receives the token, it follows these steps:

1

JWT Validation

• Checks the token's signature using the public_key.

• Verifies the aud claim matches Akinon Commerce's expected client ID.

• Validates exp, iat, and jti to ensure token integrity and freshness.

2

User Profile Handling

• If the user (sub) does not exist, a new user record is created.

• If the user already exists, the profile is updated with the latest claim data (e.g., email_allowed, phone, etc.).

3

Session Creation

• A secure user session is initiated.

• Any pre-authentication session data is merged into the new session.

Security and Data Protection

Transport: All communication between IdP and Akinon Commerce occurs over HTTPS.

Token Lifetime: It is recommended that JWTs have short expiration periods (e.g., 5–15 minutes) to enhance security.