> ## Documentation Index
> Fetch the complete documentation index at: https://docs.m1amdocs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Standard User Authentication

Storefront Gateway employs a stateless API for user authentication, using access tokens to handle user sessions. This method boosts security by ensuring that sensitive user data is not stored on the server, thereby minimizing the risk of data breaches. Access tokens are designed to be short-lived and can be easily revoked, adding an extra layer of protection.

Cookies are used exclusively for communication between the Identity Provider (IDP) and the OpenID Connect microservice (oidc-ms), ensuring secure and efficient management of authentication processes.

Supported Methods

*

* Client Credentials Flow

I would not use POST session/start in the document.

The whole document must be re-written to explain how to use OIDC and why we don't let customers to use cookies

This topic outlines the basics of Storefront Gateway's user authentication (more commonly called user sign-in or user login).

The typical user authentication use case follows a standard flow:

1. An user provides their authentication identifier (or authN ID) and password to the client.
2. The client passes that data in a `POST session/start` API request. This API invokes the Authenticate User Process.
3. (**Conditional**) The user passes additional security protocols (e.g., MFA, reCAPTCHA), if any.
4. Storefront Gateway validates the user's credentials and opens a user session.
5. A JSESSIONID token and Remember-me token are returned in the API response.
6. The user's browser stores both tokens as browser cookies.

On the surface, authentication looks like a simple REST API call that consumes the user's credentials. In a "happy path" flow, this is true from the user's perspective. However, the Authenticate User Process also supports optional security protocols, such as [Multi-factor Authentication](c_MFA) and [reCAPTCHA](reCAPTCHA) to ensure safe and seamless user authentication.

## User Session Cookies

Once a user successfully authenticates with Storefront Gateway, the browser stores a JSESSIONID token and an optional remember-me token (called the `mint-sso-token`) returned in the API call.

**JESSIONID** cookies are generally short-lived (between minutes and hours) and do not persist between browser windows, devices, or other session demarcation points.

**Remember-me** tokens, conversely, are long-lived tokens (between hours, days, and even months) that are used to transparently recreate a user's session without the need for the user to authenticate again.

Remember-me tokens are optional. If a remember-me token is provided alongside a JSESSIONID, the remember-me token always takes precedence. In other words, if an expired JSESSIONID is provided alongside a valid remember-me token to any REST API, then that API uses the remember-me token to create a new user session and return a new JSESSIONID to the browser. Similarly, if a valid JSESSIONID is provided but does not match the session identifier in a provided remember-me token, then the current session is destroyed and a new session is created in its place with a new JSESSIONID returned that matches the remember-me token.

In any instance that a remember-me token is used to construct a new session, the system invalidates that particular remember-me token and issues a new one. This is a security measure to prevent cookie theft attacks from obtaining reusable authentication tokens.

## Storefront Gateway Process API

An user authenticates into Storefront Gateway by way of the `POST /session/start` API (also known as the Session Start API). This API invokes the Authenticate User Process that consumes the user's credentials, verifies who they are, and opens a user session.

```
**REQUEST - URL**
POST http://~your.url/rest/{version}/session/start
```

```
**REQUEST - body**
{ 
   "authnIdentifier": "jane_smith@email.com", 
   "credential": "pL3a$eLetM3!n" 
}
```

| `authnIdentifier` | An user's registered email address, mobile number, or alias |
| - | - |
| `credential` | An user's password |

```
**RESPONSE - body**
{
   "processId": "eec918ff-5db4-4fee-a601-5ff76a099c8e",
   "lastStep": true,
   "runtimeId": 229,
   "userId": 12345,
   "userAuthenticated:" true
}
```

| `processId` | The unique identifier for this instance of the Authenticate User Process. |
| - | - |
| `lastStep` | Boolean that indicates whether or not this was the last step in the Process. Most Storefront Gateway Processes are multi-step (multi request and response) workflows. The Authenticate User Process is one of the exceptions to this rule, but it still returns this boolean to indicate that the Process itself is complete. |
| `runtimeId` | Identifier of the ULM Runtime entity currently associated to the ULM User entity. Upon user creation or authentication, Storefront Gateway looks for a JRUNTIMEID cookie in the user's browser or application. If no cookie is found, Storefront Gateway creates a Runtime Entity with a unique ID and associates it to the user during the login phase. Storefront Gateway will generate and pass a corresponding JRUNTIMEID cookie for clients to store and return with subsequent requests. |
| `userId` | The unique identifier of the current user. The client application can retain this ID for other REST API calls. |
| `userAuthenticated` | Boolean that indicates if the user was authenticated into Storefront Gateway. |
| The steps above outline the most basic, straightforward "happy path" of this Process. It can also take different "paths" and incorporate alternate steps; this depends on a combination of system settings, user input, and whether or not additional authentication protocols (e.g., [MFA](c_MFA), [reCAPTCHA](reCAPTCHA)) are enabled. Consult the Authenticate User Process topic for a full comprehensive overview of this Process, including multiple user scenarios with step-by-step API walkthroughs. | |

Once the user is authenticated, Storefront Gateway User details can be obtained via the `GET /user` API.

The user can close their session with the `POST /session/end` API (with no payload). This invalidates both the current session (identified by the JSESSIONID cookie) and any issued remember-me tokens. will not invalidate any other sessions the user may have.

**Note:** Access to any protected REST API requires, at a bare minimum, a valid JSESSIONID token.

**Parent topic:**[User Authentication](c_userAuthentication)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.