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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.akinon.com/technical-guides/commerce/single-sign-on-sso-with-jwt-rs256-in-akinon-commerce.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.