# **Chapter 12: Signin, Session Identity & Permission Resolution Flow**
This chapter explains **how authentication, session identity, and permissions actually work** in SartajPHP.
It connects:
- Signin App
- Session lifecycle
- Permission checks
- PageEvents
- Optional `PermisApp` behavior
Understanding this chapter is critical before building **secure, real-world applications**.
---
## 12.1 Authentication Is an Application Responsibility
In SartajPHP:
- There is **no global auth middleware**
- There is **no automatic login enforcement**
- There is **no hidden session magic**
Authentication is handled by:
- A dedicated **Signin Application**
- Explicit API calls
- Clear developer intent
This keeps SartajPHP:
- Predictable
- Flexible
- Transparent
---
## 12.2 The Role of the Signin App
The Signin Gate is responsible for:
- Validating credentials
- Loading user record
- Initializing session identity
- Assigning profile information
- Making user context available to other Apps
Once Signin completes successfully:
- The user is considered authenticated
- Other Apps can safely query identity
---
## 12.3 User Identity in SartajPHP Sessions
After successful login, SartajPHP stores **identity data**, not raw credentials.
Typical session values include:
- User record ID (`userid`)
- Parent user ID (`parentid`)
- Profile ID
- Company ID (`spcmpid`)
- Login state flag
These values are **read-only** during request processing.
Apps do not modify session identity directly.
---
## 12.4 How Apps Access Logged-in User Information
Applications retrieve user context using the API:
```php
SphpBase::page()->getAuthenticate();
````
This call:
* Verifies login state
* Stops execution if user is not logged in
* Redirects or blocks based on configuration
For Apps extending `PermisApp`, this check is often **automatic**.
---
## 12.5 Authentication vs Authorization (Critical Difference)
SartajPHP strictly separates:
### Authentication
> “Who are you?”
Handled by:
* Signin App
* Session identity
### Authorization
> “What are you allowed to do?”
Handled by:
* Permissions
* Profiles
* Explicit permission checks
This separation prevents:
* Accidental privilege escalation
* Mixed logic
* Security bugs
---
## 12.6 Permission Resolution Flow
When a permission check occurs:
1. AppGate is identified
2. Current PageEvent is resolved
3. User profile is loaded from session
4. Permission string is evaluated
5. Access is allowed or denied
This process is:
* Deterministic
* Explicit
* Fast (cached per request)
---
## 12.7 Permission Check API
The canonical permission check method:
```php
$this->page->getAuthenticatePerm("view");
```
This means:
* User must be logged in
* User must have permission for:
```
<AppGate>-view
```
If permission fails:
* PageEvent stops immediately
* No database operation executes
* No FrontFile renders
---
## 12.8 How PermisGate Uses Authentication
If an Gate extends `PermisApp`:
* Authentication is enforced automatically
* User identity fields (`userid`, `parentid`, `spcmpid`) are injected
* CRUD operations are permission-aware by default
This reduces boilerplate while keeping control in the App.
---
Got it 👍 — here is a **clean rewrite of Section 12.9 only**, fully aligned with how **SartajPHP actually works**, correcting the earlier lifecycle/security ordering and clearly separating **Security Layer vs Gate Layer**.
You can directly replace **12.9** with this.
---
## 12.9 Security Layer vs Gate Layer
In SartajPHP, **security is NOT part of the Gate lifecycle itself**.
It is a **separate layer** that executes **before Gate logic is allowed to run**.
Understanding this separation is very important.
---
### 12.9.1 Request Translation (Framework Layer)
When a browser sends a request:
1. Browser URL is translated into:
* **AppGate**
* **Event**
* **Event Parameter**
2. SartajPHP resolves the AppGate to the corresponding `Gate.php` file.
3. The Gate class is loaded into memory.
At this stage:
* No Gate code is executed
* No security is checked yet
---
### 12.9.2 Gate Lifecycle Resolution (Gate Layer)
After resolving the App:
4. SartajPHP prepares to execute the **Gate Lifecycle Events**
* `onstart`
* `onfrontinit`
* `onfrontprocess`
* `onready`
* `onrun`
* `onrender`
However…
---
### 12.9.3 Security Check Happens First (Security Layer)
Before **any Gate logic is allowed to continue**, SartajPHP performs **security validation at the top of `onstart`**.
This means:
* Security checks are evaluated **before PageEvents**
* If security fails, execution **stops immediately**
* No FrontFile renders
* No database operation runs
Security is **opt-in**, not automatic.
---
### 12.9.4 Role-Based Authentication
To require a specific role, developers explicitly declare it:
```php
$this->getAuthenticate("ADMIN");
```
This is equivalent to:
```php
$this->page->Authenticate("ADMIN");
```
What this does:
* Checks the user role set by `setSession()` in `uusigninGate.php`
* Verifies whether the logged-in user is `ADMIN`
* Blocks access if role does not match
If no authentication method is declared:
* The Gate is **public**
* Anyone can access it
(e.g. `IndexGate.php` or website home page)
---
### 12.9.5 PageEvents Do NOT Check Security Automatically
Important rule:
> **PageEvents never enforce security by default**
That means:
* `page_new`
* `page_insert`
* `page_update`
* `page_delete`
* Custom events
…will all execute **unless security is explicitly defined**.
Security must always be declared using:
* `getAuthenticate()`
* `getAuthenticatePerm()`
---
### 12.9.6 Session Security (`getSesSecurity`)
```php
$this->getSesSecurity();
```
This check:
* Prevents access with **expired or invalid session IDs**
* Blocks replayed or invalid URLs
It is:
* Rarely used
* Optional
* Mostly required in high-security systems
---
### 12.9.7 Permission + Role Authentication
For role **and** permission checks together:
```php
$this->page->getAuthenticatePerm("view");
```
This performs:
* Role validation (GUEST / MEMBER / ADMIN)
* Permission validation (`AppGate-view`)
You can authorize multiple roles or permissions:
```php
$this->page->getAuthenticatePerm("ADMIN,MEMBER");
$this->page->getAuthenticatePerm("view,add");
```
Comma-separated values allow flexible access control.
---
### 12.9.8 Key Design Principle
SartajPHP never assumes security.
* Developers decide **who can access**
* Developers decide **what is protected**
* Developers can mix:
* Public Apps
* Role-based Apps
* Permission-based Apps
* Hybrid Apps
This design gives **full freedom**, not restrictions.
---
### 12.9.9 Summary
* Security layer is separate from Gate logic
* URL → AppGate → Gate resolution happens first
* Security is checked at the top of `onstart`
* PageEvents never auto-check security
* Roles come from `uusigninGate.php`
* Permissions are optional and explicit
* Nothing is enforced unless the developer says so
---
## 12.10 Login-Aware FrontFile Behavior
FrontFiles do **not** check authentication.
Instead:
* Apps decide what FrontFile to render
* Apps decide whether rendering is allowed
* Components may be conditionally visible
This keeps FrontFiles:
* Clean
* UI-focused
* Security-agnostic
---
## 12.11 Logout Flow
Logout is handled by:
* Clearing session identity
* Destroying login state
* Redirecting to Signin App
After logout:
* All Apps requiring authentication fail immediately
* No permission checks pass
* User context is unavailable
---
## 12.12 Multi-Company Identity (`spcmpid`)
For large projects:
* `spcmpid` is loaded during login
* Stored in session
* Used by PermisGate to filter records
This enables:
* Multi-tenant architecture
* Shared codebase
* Isolated data per company
Small projects may ignore this field safely.
---
## 12.13 Custom Authentication Systems
SartajPHP allows you to:
* Replace Signin App
* Extend it
* Create multiple login systems
* Integrate third-party auth
As long as:
* Session identity is set correctly
* API expectations are respected
There is **no lock-in**.
---
## 12.14 Common Mistakes to Avoid
❌ Checking permissions in FrontFiles
❌ Running SQL before permission checks
❌ Mixing login logic into Apps
❌ Hardcoding session values
❌ Assuming PermisGate is mandatory
---
## 12.15 Summary
* Signin Gate handles authentication
* Session holds identity, not logic
* Permissions are resolved per AppGate + Event
* PermisGate automates common patterns
* Developers retain full control
---
## 12.16 What Comes Next
In **Chapter 13**, we will cover:
* Profile & Permission management Apps
* Permission assignment UI
* Dynamic permission filtering
* Why users cannot assign permissions they don’t have
* Real-world permission workflows
---