Skip to content

Commit c857741

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

1 file changed

Lines changed: 129 additions & 95 deletions

File tree

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

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

Lines changed: 129 additions & 95 deletions
Original file line numberDiff line numberDiff line change
@@ -1,59 +1,99 @@
11
# 🔹 SpringBoot-API: Active Directory SSO Integration
22

3-
## 📌 Overview
3+
![Java](https://img.shields.io/badge/Java-17+-ED8B00?style=for-the-badge&logo=java&logoColor=white)
4+
![Spring](https://img.shields.io/badge/Spring%20Boot-3.x-6DB33F?style=for-the-badge&logo=springboot&logoColor=white)
5+
![LDAP](https://img.shields.io/badge/Auth-LDAP%20SSO-4CAF50?style=for-the-badge)
6+
![ActiveDirectory](https://img.shields.io/badge/Directory-Active%20Directory-0078D4?style=for-the-badge)
7+
![Enterprise](https://img.shields.io/badge/Grade-Enterprise-blueviolet?style=for-the-badge)
48

5-
The **SpringBoot-API** module provides a **Java-based REST API** that enables **LDAP-based Single Sign-On (SSO) authentication** with **Active Directory**.
6-
It is built using **Spring Boot** and integrates seamlessly with LDAP for secure and scalable enterprise authentication.
9+
## 📝 Overview
10+
11+
The **SpringBoot-API** module delivers an **enterprise-ready Java REST API** that implements **LDAP-based Single Sign-On (SSO)** authentication against **Microsoft Active Directory**.
12+
13+
It follows the same **architecture, security posture, configuration model, and documentation standards** used across the **ActiveDirectory-SSO-Integrations** suite, ensuring predictable behavior, auditability, and ease of integration in corporate environments.
14+
15+
This implementation is suitable for:
16+
- Enterprise backends
17+
- Microservices
18+
- Internal portals
19+
- Cross-domain / forest-wide authentication via **Global Catalog (GC)**
720

821
---
922

10-
## 📁 Folder Structure
23+
## ✅ Key Features
1124

12-
```
13-
ActiveDirectory-SSO-Integrations/
14-
│
15-
├── 📂 SpringBoot-API/
16-
│ ├── 📜 pom.xml # Maven build and dependency config
17-
│ ├── 📂 src/
18-
│ │ ├── 📂 main/
19-
│ │ │ ├── 📂 java/com/example/springbootsso/
20-
│ │ │ │ ├── 📜 SpringBootSsoApplication.java # Main application launcher
21-
│ │ │ │ ├── 📂 config/
22-
│ │ │ │ │ ├── 📜 SecurityConfig.java # Spring Security config
23-
│ │ │ │ │ ├── 📜 LdapConfig.java # LDAP setup
24-
│ │ │ │ ├── 📂 controllers/
25-
│ │ │ │ │ ├── 📜 AuthController.java # Login/auth endpoints
26-
│ │ │ │ │ ├── 📜 UserController.java # User info endpoints
27-
│ │ │ │ ├── 📂 services/
28-
│ │ │ │ │ ├── 📜 LdapService.java # LDAP auth logic
29-
│ │ │ │ ├── 📂 models/
30-
│ │ │ │ │ ├── 📜 UserModel.java # User schema model
31-
│ │ │ │ ├── 📂 middleware/
32-
│ │ │ │ │ ├── 📜 LdapAuthMiddleware.java # Custom LDAP enforcement
33-
│ │ │ ├── 📂 resources/
34-
│ │ │ │ ├── 📜 application.yml # Base config
35-
│ │ │ │ ├── 📜 application-dev.yml # Dev-specific settings
36-
│ │ │ │ ├── 📜 application-prod.yml # Prod-specific settings
37-
│ ├── 📂 test/java/com/example/springbootsso/
38-
│ │ ├── 📜 SpringBootSsoApplicationTests.java # Unit tests
39-
│ ├── 📖 README.md # Documentation
40-
```
25+
- 🔐 **LDAP / AD Authentication**
26+
- Native Spring Security + LDAP integration
27+
- Forest-wide authentication via **Global Catalog (3268)**
28+
29+
- 🧩 **Modular & Profile-Based Configuration**
30+
- `application.yml`, `application-dev.yml`, `application-prod.yml`
31+
- Environment-variable driven secrets
32+
33+
- 🏢 **Enterprise Security Design**
34+
- Least-privilege service account
35+
- No hardcoded credentials
36+
- Separation of config, auth, and controllers
37+
38+
- 🔄 **RESTful Endpoints**
39+
- Authentication
40+
- User identity lookup
41+
- Ready for JWT or downstream SSO chaining
4142

4243
---
4344

4445
## 🛠️ Prerequisites
4546

47+
### 1️⃣ Java Platform
4648
- **JDK 17+**
47-
- **Apache Maven**
48-
- **Active Directory (GC enabled)**
49-
- **LDAP service credentials**
50-
- **Postman or cURL** (for API testing)
49+
- Recommended distributions: Temurin, Oracle JDK, OpenJDK
50+
51+
### 2️⃣ Build Tool
52+
- **Apache Maven 3.9+**
53+
54+
### 3️⃣ Directory Services
55+
- Microsoft **Active Directory**
56+
- **Global Catalog enabled**
57+
- LDAP service account with **read-only permissions**
58+
59+
### 4️⃣ Testing Tools
60+
- Postman or cURL
61+
62+
---
63+
64+
## 📁 Project Structure
65+
66+
```
67+
SpringBoot-API/
68+
├── pom.xml
69+
├── src/
70+
│ ├── main/
71+
│ │ ├── java/com/example/springbootsso/
72+
│ │ │ ├── SpringBootSsoApplication.java
73+
│ │ │ ├── config/
74+
│ │ │ │ ├── SecurityConfig.java
75+
│ │ │ │ └── LdapConfig.java
76+
│ │ │ ├── controllers/
77+
│ │ │ │ ├── AuthController.java
78+
│ │ │ │ └── UserController.java
79+
│ │ │ ├── services/
80+
│ │ │ │ └── LdapService.java
81+
│ │ │ └── models/
82+
│ │ │ └── UserModel.java
83+
│ │ └── resources/
84+
│ │ ├── application.yml
85+
│ │ ├── application-dev.yml
86+
│ │ └── application-prod.yml
87+
│ └── test/
88+
│ └── SpringBootSsoApplicationTests.java
89+
└── README.md
90+
```
5191

5292
---
5393

5494
## ⚙️ Configuration
5595

56-
Edit `application.yml` with your domain-wide LDAP parameters:
96+
Configure LDAP and AD parameters in `application.yml`:
5797

5898
```yaml
5999
spring:
@@ -64,91 +104,85 @@ spring:
64104
password: ${LDAP_PASSWORD}
65105
user-search-filter: (sAMAccountName={0})
66106
group-search-base: dc=headq,dc=scriptguy
67-
group-search-filter: (member={0})
68107

69108
server:
70109
port: 8080
71110
```
72111
112+
> 🔐 **Security note:**
113+
> Always inject `LDAP_PASSWORD` via environment variables or secret managers.
114+
73115
---
74116

75-
## 🚀 How to Run
117+
## 🚀 Running the Application
76118

77-
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/SpringBoot-API
81-
```
119+
### 1️⃣ Set Environment Variable
82120

83-
2. **Set LDAP credentials as environment variable:**
84-
```bash
85-
export LDAP_PASSWORD='your-secure-password'
86-
```
121+
```bash
122+
export LDAP_PASSWORD='your-secure-password'
123+
```
124+
125+
### 2️⃣ Build the Project
87126

88-
3. **Build and launch:**
89-
```bash
90-
mvn clean package
91-
java -jar target/SpringBootSSO-1.0.0.jar
92-
```
127+
```bash
128+
mvn clean package
129+
```
130+
131+
### 3️⃣ Start the API
132+
133+
```bash
134+
java -jar target/SpringBootSSO-1.0.0.jar
135+
```
136+
137+
The API will be available at:
138+
`http://localhost:8080`
93139

94140
---
95141

96142
## 🔄 API Endpoints
97143

98-
### 1️⃣ Authenticate User
99-
100-
- **POST:** `/api/auth/login`
101-
- **Payload:**
102-
```json
103-
{
104-
"username": "john.doe",
105-
"password": "SuperSecretPassword"
106-
}
107-
```
108-
- **Response:**
109-
```json
110-
{
111-
"message": "Authentication successful"
112-
}
113-
```
114-
115-
### 2️⃣ Get User Details
116-
117-
- **GET:** `/api/user/{username}`
118-
- **Example:**
119-
```bash
120-
curl -X GET http://localhost:8080/api/user/john.doe
121-
```
122-
- **Sample Output:**
123-
```json
124-
{
125-
"username": "john.doe",
126-
"displayName": "John Doe",
127-
"email": "[email protected]",
128-
"department": "IT",
129-
"role": "User"
130-
}
131-
```
144+
### 🔑 Authenticate User
145+
146+
**POST** `/api/auth/login`
147+
148+
```json
149+
{
150+
"username": "john.doe",
151+
"password": "SuperSecretPassword"
152+
}
153+
```
154+
155+
### 👤 Retrieve User Details
156+
157+
**GET** `/api/user/{username}`
158+
159+
```bash
160+
curl http://localhost:8080/api/user/john.doe
161+
```
132162

133163
---
134164

135-
## 📜 License
165+
## 🔒 Security & Best Practices
136166

137-
[![MIT License](https://img.shields.io/badge/License-MIT-blue.svg?style=for-the-badge)](https://github.com/brazilianscriptguy/Windows-SysAdmin-ProSuite/blob/main/.github/LICENSE.txt)
167+
- Use **dedicated LDAP service accounts**
168+
- Never grant Domain Admin privileges
169+
- Prefer **Global Catalog** for multi-domain forests
170+
- Externalize secrets (Vault, Azure Key Vault, Kubernetes Secrets)
171+
- Add TLS (`ldaps://`) in production environments
138172

139173
---
140174

141-
## 🤝 Contributing
175+
## 📜 License
142176

143-
[![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)
177+
[![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)
144178

145179
---
146180

147181
## 📩 Support
148182

149-
[![Email Badge](https://img.shields.io/badge/[email protected]?style=for-the-badge&logo=gmail)](mailto:[email protected])
150-
[![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)
183+
[![Email](https://img.shields.io/badge/[email protected]?style=for-the-badge&logo=gmail)](mailto:[email protected])
184+
[![GitHub Issues](https://img.shields.io/badge/GitHub-Issues-blue?style=for-the-badge&logo=github)](https://github.com/brazilianscriptguy/Windows-SysAdmin-ProSuite/blob/main/.github/BUG_REPORT.md)
151185

152186
---
153187

154-
<p align="center">💼 <strong>Powerful AD SSO in Enterprise Java Applications</strong> 🔐</p>
188+

0 commit comments

Comments
 (0)