# 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.

## <mark style="color:red;">Key Components</mark>

#### 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.

## <mark style="color:red;">Security Overview with RS256</mark>

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.

## <mark style="color:red;">JWT Payload & Claims</mark>

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

### <mark style="color:red;">Standard Claims</mark>

<table><thead><tr><th width="134.1328125">Claim</th><th>Description</th></tr></thead><tbody><tr><td><code>sub</code></td><td><strong>Subject —</strong> The unique user identifier assigned by the IdP.</td></tr><tr><td><code>aud</code></td><td><strong>Audience —</strong> Indicates that the JWT is intended for Akinon Commerce, as specified by the IdP.</td></tr><tr><td><code>exp</code></td><td><strong>Expiration Time —</strong> The timestamp (Unix format) after which the JWT becomes invalid.</td></tr><tr><td><code>iat</code></td><td><strong>Issued At —</strong> The timestamp (Unix format) indicating when the JWT was created.</td></tr><tr><td><code>jti</code></td><td><strong>JWT ID —</strong> A unique identifier for this specific JWT instance.</td></tr></tbody></table>

### <mark style="color:red;">Custom User Claims (Required by Akinon)</mark>

<table><thead><tr><th width="149.34765625">Claim</th><th>Description</th></tr></thead><tbody><tr><td><code>email</code></td><td>User’s email address</td></tr><tr><td><code>first_name</code></td><td>User’s first name</td></tr><tr><td><code>last_name</code></td><td>User’s last name</td></tr><tr><td><code>phone</code></td><td>Phone number in international format</td></tr><tr><td><code>email_allowed</code></td><td>Whether the user accepts emails (Boolean)</td></tr><tr><td><code>sms_allowed</code></td><td>Whether the user accepts SMS (Boolean)</td></tr><tr><td><code>call_allowed</code></td><td>Whether the user accepts calls (Boolean)</td></tr><tr><td><code>gender</code></td><td>Gender of the user (nullable)</td></tr><tr><td><code>date_of_birth</code></td><td>Date of birth in <code>YYYY-MM-DD</code> format</td></tr></tbody></table>

#### Sample JWT Payload

```json
{
  "sub": "UserID",
  "aud": "client_id",
  "exp": 1814944520,
  "iat": 1714944520,
  "jti": "unique-jwt-id",
  "email": "user@example.com",
  "first_name": "John",
  "last_name": "Doe",
  "phone": "+1234567890",
  "email_allowed": true,
  "sms_allowed": false,
  "call_allowed": true,
  "gender": null,
  "date_of_birth": "1990-01-01"
}
```

## <mark style="color:red;">JWT Transmission Flow</mark>

#### 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:

<table><thead><tr><th width="161.1171875">Method</th><th>POST</th></tr></thead><tbody><tr><td>URL</td><td><code>https://uuid.lb.akinoncloud.com/jwt_sso/login/callback/</code></td></tr><tr><td>Content-Type</td><td><code>application/json</code></td></tr></tbody></table>

#### Example Request

```http
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
HTTP/1.1 200 OK
Content-Type: application/json
Set-Cookie: csrftoken=...; expires=...; Path=/;
Set-Cookie: sessionid=...; expires=...; HttpOnly;

{}
```

{% hint style="warning" %}
Cookies like `csrftoken` and `sessionid` must be retained and sent with subsequent requests to maintain the user session.
{% endhint %}

## <mark style="color:red;">Session & User Management in Akinon</mark>

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

{% stepper %}
{% step %}
**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.
  {% endstep %}

{% step %}
**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.).
  {% endstep %}

{% step %}
**Session Creation**

* A secure user session is initiated.
* Any pre-authentication session data is merged into the new session.
  {% endstep %}
  {% endstepper %}

## <mark style="color:red;">Security and Data Protection</mark>

**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.