Skip to content

Commit 28b699a

Browse files
brazilianscriptguybrazilianscriptguy
authored
Update README.md
Signed-off-by: LUIZ HAMILTON ROBERTO DA SILVA <[email protected]>
1 parent ed937ae commit 28b699a

1 file changed

Lines changed: 102 additions & 80 deletions

File tree

  • SysAdmin-Tools/ActiveDirectory-SSO-Integrations/PHP-API

‎SysAdmin-Tools/ActiveDirectory-SSO-Integrations/PHP-API/README.md‎

Lines changed: 102 additions & 80 deletions
Original file line numberDiff line numberDiff line change
@@ -1,56 +1,85 @@
11
# 🔹 PHP-API: Active Directory SSO Integration
22

33
![PHP](https://img.shields.io/badge/PHP-8.0+-777BB4?style=for-the-badge&logo=php&logoColor=white)
4-
![LDAP](https://img.shields.io/badge/Auth-LDAP%20%7C%20AD-0A66C2?style=for-the-badge)
5-
![SSO](https://img.shields.io/badge/SSO-Active%20Directory-2E7D32?style=for-the-badge)
6-
![Security](https://img.shields.io/badge/Security-Enterprise--Grade-4CAF50?style=for-the-badge)
4+
![LDAP](https://img.shields.io/badge/LDAP-Active%20Directory-0A66C2?style=for-the-badge&logo=microsoft)
5+
![SSO](https://img.shields.io/badge/SSO-Global%20Catalog-4CAF50?style=for-the-badge)
6+
![Platform](https://img.shields.io/badge/Platform-Apache%20%7C%20Nginx-D22128?style=for-the-badge)
7+
![Security](https://img.shields.io/badge/Security-Least%20Privilege-2E7D32?style=for-the-badge)
78

8-
## 📌 Overview
9+
## 📝 Overview
910

10-
The **PHP-API** module implements **LDAP-based Single Sign-On (SSO)** with **Active Directory**, designed to operate across an **entire AD forest** using the **Global Catalog (GC)**.
11+
The **PHP-API** module provides a **lightweight, secure, and enterprise-aligned LDAP Single Sign-On (SSO)** implementation for **Active Directory** environments, designed to operate **forest-wide** using the **Global Catalog (GC)**.
1112

12-
It provides a **lightweight, auditable, and secure authentication layer** for both **legacy and modern PHP applications**, following the same security and design principles used across the **Windows-SysAdmin-ProSuite**.
13+
This integration follows the same **design principles, security posture, and documentation standards** adopted across the **Windows‑SysAdmin‑ProSuite**, ensuring predictable behavior, auditable authentication flows, and compatibility with legacy or modern PHP deployments.
1314

14-
This integration is ideal for environments where:
15-
- IIS/Apache-based applications still rely on PHP
16-
- Forest-wide authentication is required
17-
- Minimal privileges and predictable behavior are mandatory
15+
The solution supports both:
16+
- **Transparent SSO** (via `REMOTE_USER`, when available), and
17+
- **Credential-based fallback authentication**, maintaining usability without weakening security controls.
18+
19+
---
20+
21+
## ✅ Key Features
22+
23+
- 🔐 **Forest‑Wide Authentication**
24+
- Uses **Global Catalog (port 3268)** for multi-domain AD forests
25+
- No hard dependency on a single domain controller
26+
27+
- 🧩 **Dual Authentication Model**
28+
- Automatic SSO via web server integration (`REMOTE_USER`)
29+
- Secure manual login fallback (`login.php`)
30+
31+
- 🛡️ **Security‑First Design**
32+
- Service account with **read-only permissions**
33+
- Explicit blocking of **inetOrgPerson** objects
34+
- No credential persistence in source code
35+
36+
- 📜 **Auditable and Deterministic Flow**
37+
- Centralized LDAP logic
38+
- Clear authentication boundaries
39+
- Predictable session lifecycle
40+
41+
- 🧱 **Enterprise Compatibility**
42+
- Works with Apache or Nginx
43+
- Compatible with legacy PHP apps and modern PHP 8+ stacks
1844

1945
---
2046

2147
## 📁 Folder Structure
2248

2349
```text
2450
ActiveDirectory-SSO-Integrations/
25-
│
26-
├── PHP-API/
27-
│ ├── public/
28-
│ │ ├── index.php # Entry point with SSO auto-detection
29-
│ │ ├── login.php # Manual login fallback
30-
│ │ ├── dashboard.php # Protected resource
31-
│ │ └── logout.php # Session termination
32-
│ │
33-
│ ├── config/
34-
│ │ ├── env.php # Loads environment variables
35-
│ │ └── ldap.php # LDAP bind and authentication logic
36-
│ │
37-
│ ├── .env.example # Environment template
38-
│ ├── composer.json # Dependency definitions
39-
│ └── README.md # Module documentation
51+
└── PHP-API/
52+
├── public/
53+
│ ├── index.php # Entry point with SSO detection
54+
│ ├── login.php # Manual authentication fallback
55+
│ ├── dashboard.php # Protected application area
56+
│ └── logout.php # Session termination
57+
│
58+
├── config/
59+
│ ├── env.php # Loads environment variables
60+
│ └── ldap.php # Central LDAP authentication logic
61+
│
62+
├── .env.example # LDAP credential template
63+
├── composer.json # Dependency definitions
64+
└── README.md # Module documentation
4065
```
4166

4267
---
4368

4469
## 🛠️ Prerequisites
4570

46-
- **PHP 8.0 or later**
47-
- **Active Directory** with **Global Catalog enabled**
48-
- **Apache or Nginx** with PHP support
49-
- **Composer** (dependency manager)
50-
- PHP extensions:
51-
- `ldap`
52-
- `mbstring`
53-
- `openssl`
71+
### 1) ⚙️ Platform Requirements
72+
- **PHP 8.0+**
73+
- **Apache or Nginx** with PHP enabled
74+
- **OpenLDAP / Active Directory** with Global Catalog enabled
75+
76+
### 2) 📦 Dependencies
77+
- **Composer**
78+
- `vlucas/phpdotenv` (for secure environment variable handling)
79+
80+
### 3) 🔑 Directory Access
81+
- Dedicated **AD service account**
82+
- Read-only LDAP permissions (bind + search)
5483

5584
---
5685

@@ -65,90 +94,83 @@ LDAP_USERNAME=ad-sso-authentication@scriptguy
6594
LDAP_PASSWORD=YourSecurePassword
6695
```
6796

68-
The configuration is loaded at runtime via `vlucas/phpdotenv`.
97+
The file is loaded at runtime by `config/env.php` using `phpdotenv`.
6998

70-
> 🔐 **Best Practice**:
71-
> The LDAP bind account must be **read-only**, non-interactive, and excluded from application logon.
99+
> 🔒 **Best Practice**
100+
> Never commit `.env` files. Store secrets in environment variables or a secure vault.
72101

73102
---
74103

75104
## 🚀 How to Run
76105

77106
1. **Clone the repository**
78-
```bash
79-
git clone https://github.com/brazilianscriptguy/Windows-SysAdmin-ProSuite.git
80-
cd Windows-SysAdmin-ProSuite/SysAdmin-Tools/ActiveDirectory-SSO-Integrations/PHP-API
81-
```
107+
```bash
108+
git clone https://github.com/brazilianscriptguy/Windows-SysAdmin-ProSuite.git
109+
cd Windows-SysAdmin-ProSuite/SysAdmin-Tools/ActiveDirectory-SSO-Integrations/PHP-API
110+
```
82111

83-
2. **Create environment file**
84-
```bash
85-
cp .env.example .env
86-
```
112+
2. **Prepare environment configuration**
113+
```bash
114+
cp .env.example .env
115+
```
87116

88117
3. **Install dependencies**
89-
```bash
90-
composer install
91-
```
118+
```bash
119+
composer install
120+
```
92121

93122
4. **Start development server**
94-
```bash
95-
php -S localhost:8000 -t public
96-
```
123+
```bash
124+
php -S localhost:8000 -t public
125+
```
97126

98-
Access the application at:
99-
`http://localhost:8000`
127+
5. Access:
128+
```
129+
http://localhost:8000
130+
```
100131

101132
---
102133

103-
## 🔐 LDAP Authentication Design
134+
## 🔐 Authentication Flow
104135

105-
- Forest-wide authentication via **Global Catalog (TCP 3268)**
106-
- Explicit block of **service / inetOrgPerson accounts**
107-
- No password caching
108-
- No elevated directory permissions required
109-
- All validation handled server-side
110-
111-
---
112-
113-
## 🔄 Authentication Flow
114-
115-
1. User accesses `index.php`
116-
2. If `$_SERVER['REMOTE_USER']` exists → automatic SSO
117-
3. Otherwise → fallback to `login.php`
118-
4. Credentials validated against AD
119-
5. Authorized users redirected to `dashboard.php`
120-
6. Sessions destroyed via `logout.php`
136+
1. Client accesses `index.php`
137+
2. If `$_SERVER['REMOTE_USER']` exists:
138+
- User is trusted and validated against AD
139+
3. If not:
140+
- User is redirected to `login.php`
141+
4. Credentials are validated via **LDAP bind**
142+
5. Session is created and user is redirected to `dashboard.php`
143+
6. `logout.php` destroys session securely
121144

122145
---
123146

124147
## 🔒 Security Notes
125148

126-
- No credentials stored in code or logs
127-
- Environment-based secret management
128-
- Compatible with reverse proxies and IIS rewrite rules
129-
- Safe for intranet and DMZ deployments
149+
- ✔ Uses **Global Catalog** for consistent forest visibility
150+
- ✔ No password storage in source code
151+
- ✔ inetOrgPerson objects are rejected
152+
- ✔ Account enable/disable logic delegated to AD
153+
- ✔ Compatible with reverse proxies and SSO frontends
130154

131155
---
132156

133157
## 📜 License
134158

135-
[![MIT License](https://img.shields.io/badge/License-MIT-blue?style=for-the-badge)](https://github.com/brazilianscriptguy/Windows-SysAdmin-ProSuite/blob/main/.github/LICENSE.txt)
159+
![MIT License](https://img.shields.io/badge/License-MIT-blue?style=for-the-badge)
136160

137161
---
138162

139163
## 🤝 Contributing
140164

141-
[![Contributions Welcome](https://img.shields.io/badge/Contributions-Welcome-brightgreen?style=for-the-badge)](https://github.com/brazilianscriptguy/Windows-SysAdmin-ProSuite/blob/main/.github/CONTRIBUTING.md)
165+
![Contributions Welcome](https://img.shields.io/badge/Contributions-Welcome-brightgreen?style=for-the-badge)
142166

143167
---
144168

145169
## 📩 Support
146170

147-
[![Email](https://img.shields.io/badge/[email protected]?style=for-the-badge&logo=gmail)](mailto:[email protected])
148-
[![GitHub Issues](https://img.shields.io/badge/GitHub%20Issues-Report%20Here-blue?style=for-the-badge&logo=github)](https://github.com/brazilianscriptguy/Windows-SysAdmin-ProSuite/blob/main/.github/BUG_REPORT.md)
171+
![Email](https://img.shields.io/badge/[email protected]?style=for-the-badge&logo=gmail)
172+
![GitHub Issues](https://img.shields.io/badge/GitHub%20Issues-Report%20Here-blue?style=for-the-badge&logo=github)
149173

150174
---
151175

152-
<p align="center">🌐 <strong>Enterprise‑grade AD SSO for PHP applications</strong> 🔒</p>
153-
154-
© 2026 Luiz Hamilton Silva. All rights reserved.
176+
© 2026 Luiz Hamilton Silva — @brazilianscriptguy

0 commit comments

Comments
 (0)