Skip to content

Commit 4831a2e

Browse files
LasimLasim
authored
Merge pull request #170 from deploystackio/feat/new-docs
Feat/new docs
2 parents 0eeab70 + 712b8a6 commit 4831a2e

29 files changed

Lines changed: 7891 additions & 958 deletions

‎docs/deploystack/auth.mdx‎

Lines changed: 232 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,232 @@
1+
---
2+
title: Authentication Methods
3+
description: Available authentication methods in DeployStack, including email registration and GitHub OAuth, with configuration instructions for administrators.
4+
---
5+
6+
# Authentication Methods
7+
8+
DeployStack supports multiple authentication methods to provide flexibility for different user preferences and organizational requirements. This document outlines the available authentication options and how to configure them.
9+
10+
## Available Authentication Methods
11+
12+
### Email Registration & Login
13+
14+
Email-based authentication is the primary authentication method in DeployStack. Users can register with their email address and password, and subsequently log in using these credentials.
15+
16+
**Features:**
17+
- Secure password hashing using Argon2
18+
- Email verification (when email sending is enabled)
19+
- Password reset functionality
20+
- Profile management
21+
22+
**User Experience:**
23+
1. Users register with email, password, and optional personal information
24+
2. Email verification may be required (depending on configuration)
25+
3. Users can log in using email or username
26+
4. Password reset available via email (when email sending is enabled)
27+
28+
### GitHub OAuth
29+
30+
GitHub OAuth provides a convenient way for users to authenticate using their existing GitHub accounts. This method is particularly useful for development teams and organizations already using GitHub.
31+
32+
**Features:**
33+
- Single sign-on with GitHub
34+
- Automatic email verification (GitHub emails are considered verified)
35+
- Profile information imported from GitHub
36+
- Secure OAuth 2.0 flow
37+
38+
**User Experience:**
39+
1. Users click "Login with GitHub" button
40+
2. Redirected to GitHub for authorization
41+
3. Upon approval, automatically logged into DeployStack
42+
4. Profile information (name, email) imported from GitHub
43+
44+
## Authentication Configuration
45+
46+
### Global Authentication Settings
47+
48+
Administrators can control authentication behavior through global settings:
49+
50+
| Setting | Description | Default |
51+
|---------|-------------|---------|
52+
| **Enable Login** | Master switch for all authentication methods | `true` |
53+
| **Enable Email Registration** | Allow new users to register via email | `true` |
54+
| **GitHub OAuth Enabled** | Enable GitHub OAuth authentication | `false` |
55+
56+
### Email Authentication Configuration
57+
58+
Email authentication is always available but requires SMTP configuration for full functionality:
59+
60+
**Required for Full Functionality:**
61+
- SMTP server configuration (for email verification and password reset)
62+
- Email sending enabled in global settings
63+
64+
**Configuration Steps:**
65+
1. Navigate to **Global Settings** → **SMTP Mail Settings**
66+
2. Configure SMTP server details:
67+
- Host (e.g., `smtp.gmail.com`)
68+
- Port (e.g., `587`)
69+
- Username and Password
70+
- Security settings
71+
3. Enable email sending in **Global Settings** → **Global Configuration**
72+
73+
### GitHub OAuth Configuration
74+
75+
GitHub OAuth requires setup both in GitHub and DeployStack:
76+
77+
**GitHub Setup:**
78+
1. Go to GitHub → Settings → Developer settings → OAuth Apps
79+
2. Create a new OAuth App with:
80+
- **Application name**: Your DeployStack instance name
81+
- **Homepage URL**: Your DeployStack frontend URL
82+
- **Authorization callback URL**: `https://your-domain.com/api/auth/github/callback`
83+
3. Note the **Client ID** and **Client Secret**
84+
85+
**DeployStack Configuration:**
86+
1. Navigate to **Global Settings** → **GitHub OAuth Configuration**
87+
2. Configure the following settings:
88+
- **Client ID**: From your GitHub OAuth App
89+
- **Client Secret**: From your GitHub OAuth App (encrypted)
90+
- **Enabled**: Set to `true` to activate GitHub OAuth
91+
- **Callback URL**: Must match the URL configured in GitHub
92+
- **Scope**: OAuth permissions (default: `user:email`)
93+
94+
**Configuration Example:**
95+
```
96+
Client ID: abc123def456
97+
Client Secret: [encrypted]
98+
Enabled: true
99+
Callback URL: https://your-deploystack.com/api/auth/github/callback
100+
Scope: user:email
101+
```
102+
103+
## User Roles and First User
104+
105+
### First User (Global Administrator)
106+
107+
The first user registered in DeployStack automatically becomes the **Global Administrator** with full system access. This ensures there's always at least one administrator who can manage the system.
108+
109+
**Important Notes:**
110+
- The first user **must** be created via email registration
111+
- GitHub OAuth cannot be used to create the first user
112+
- This prevents accidental creation of admin accounts via OAuth
113+
114+
### Subsequent Users
115+
116+
All users registered after the first user receive the **Global User** role by default, regardless of authentication method used.
117+
118+
**Role Assignment:**
119+
- **Email Registration**: `global_user` role
120+
- **GitHub OAuth**: `global_user` role
121+
- **Role Changes**: Only global administrators can modify user roles
122+
123+
## Security Considerations
124+
125+
### Email Authentication Security
126+
127+
- Passwords are hashed using Argon2 with secure parameters
128+
- Email verification prevents unauthorized account creation
129+
- Password reset tokens are time-limited and single-use
130+
- Session management handled by Lucia v3
131+
132+
### GitHub OAuth Security
133+
134+
- OAuth 2.0 standard with state parameter for CSRF protection
135+
- GitHub emails are considered verified
136+
- Secure token exchange and validation
137+
- No GitHub credentials stored in DeployStack
138+
139+
### Account Linking
140+
141+
When a user with an existing email account uses GitHub OAuth with the same email address:
142+
- The GitHub account is automatically linked to the existing account
143+
- User can subsequently use either authentication method
144+
- No duplicate accounts are created
145+
146+
## Troubleshooting
147+
148+
### Email Authentication Issues
149+
150+
**Email verification not working:**
151+
- Check SMTP configuration in Global Settings
152+
- Verify email sending is enabled
153+
- Check server logs for email delivery errors
154+
155+
**Password reset not working:**
156+
- Ensure SMTP is configured and email sending is enabled
157+
- Verify the reset link hasn't expired (tokens are time-limited)
158+
159+
### GitHub OAuth Issues
160+
161+
**"GitHub OAuth is not enabled" error:**
162+
- Check that GitHub OAuth is enabled in Global Settings
163+
- Verify Client ID and Client Secret are configured
164+
- Ensure callback URL matches GitHub OAuth App configuration
165+
166+
**"GitHub email not available" error:**
167+
- User's GitHub email must be public and verified
168+
- Check GitHub account email settings
169+
- Ensure OAuth scope includes `user:email`
170+
171+
**First user creation blocked:**
172+
- This is expected behavior - first user must use email registration
173+
- Use email registration to create the initial administrator account
174+
175+
### General Authentication Issues
176+
177+
**Login disabled:**
178+
- Check that "Enable Login" is set to `true` in Global Settings
179+
- Verify database is properly configured and accessible
180+
181+
**Registration disabled:**
182+
- Check that "Enable Email Registration" is set to `true` for email signup
183+
- Verify GitHub OAuth is enabled and configured for GitHub login
184+
185+
## API Endpoints
186+
187+
For developers and integrations, DeployStack provides REST API endpoints for authentication:
188+
189+
### Email Authentication
190+
- `POST /api/auth/email/register` - User registration
191+
- `POST /api/auth/email/login` - User login
192+
- `POST /api/auth/email/forgot-password` - Password reset request
193+
- `POST /api/auth/email/reset-password` - Password reset confirmation
194+
195+
### GitHub OAuth
196+
- `GET /api/auth/github/login` - Initiate GitHub OAuth flow
197+
- `GET /api/auth/github/callback` - OAuth callback handler
198+
- `GET /api/auth/github/status` - Check if GitHub OAuth is enabled
199+
200+
### General Authentication
201+
- `POST /api/auth/logout` - User logout
202+
- `GET /api/users/me` - Get current user profile
203+
- `PUT /api/auth/profile/update` - Update user profile
204+
205+
## Best Practices
206+
207+
### For Administrators
208+
209+
1. **Always configure the first user via email** to ensure proper admin access
210+
2. **Set up SMTP early** to enable email verification and password reset
211+
3. **Use strong OAuth secrets** and keep them secure
212+
4. **Regularly review user accounts** and roles
213+
5. **Monitor authentication logs** for security issues
214+
215+
### For Users
216+
217+
1. **Use strong passwords** for email authentication
218+
2. **Verify your email address** when using email registration
219+
3. **Keep GitHub account secure** when using OAuth
220+
4. **Use the same email address** across authentication methods for account linking
221+
222+
### For Organizations
223+
224+
1. **Choose authentication methods** that align with your security policies
225+
2. **Consider GitHub OAuth** for development teams already using GitHub
226+
3. **Implement proper access controls** through user roles
227+
4. **Document authentication procedures** for your team
228+
5. **Plan for account recovery** scenarios
229+
230+
---
231+
232+
For technical implementation details, see the [Backend Authentication Documentation](/deploystack/development/backend/api) and [Global Settings Management](/deploystack/global-settings).

0 commit comments

Comments
 (0)