Skip to content

Commit 8a00db8

Browse files
antosubashantosubash
committed
docs: enhance introduction and authentication documentation
- Updated the introduction to provide a clearer overview of ABP React and its features. - Expanded the authentication section to detail the OpenID Connect flow and session management. - Added middleware documentation, outlining tenant resolution and session handling processes. - Included best practices for security and performance in middleware usage. - Improved structure and clarity throughout the documentation for better user guidance.
1 parent 49fb289 commit 8a00db8

7 files changed

Lines changed: 986 additions & 40 deletions

File tree

‎docs/docs/components/ui-components.md‎

Lines changed: 179 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,179 @@
1+
---
2+
sidebar_position: 1
3+
---
4+
5+
# UI Components
6+
7+
## Overview
8+
9+
ABP React provides a comprehensive set of UI components built on top of Radix UI and styled with Tailwind CSS. These components are designed to be accessible, customizable, and consistent with the ABP design system.
10+
11+
## Core Components
12+
13+
### Custom Table
14+
15+
A flexible table component with sorting, filtering, and pagination:
16+
17+
```typescript
18+
import { CustomTable } from '@/components/ui/CustomTable'
19+
20+
// Usage
21+
<CustomTable
22+
columns={columns}
23+
data={data}
24+
pagination={pagination}
25+
onPaginationChange={handlePaginationChange}
26+
/>
27+
```
28+
29+
### Search Component
30+
31+
A search input with debouncing and clear functionality:
32+
33+
```typescript
34+
import { Search } from '@/components/ui/Search'
35+
36+
// Usage
37+
<Search
38+
placeholder="Search..."
39+
onSearch={handleSearch}
40+
debounceTime={300}
41+
/>
42+
```
43+
44+
### Error Component
45+
46+
A standardized error display component:
47+
48+
```typescript
49+
import Error from '@/components/ui/Error'
50+
51+
// Usage
52+
<Error
53+
message="An error occurred"
54+
retry={handleRetry}
55+
/>
56+
```
57+
58+
### Loader Component
59+
60+
A loading indicator component:
61+
62+
```typescript
63+
import Loader from '@/components/ui/Loader'
64+
65+
// Usage
66+
<Loader />
67+
```
68+
69+
## Form Components
70+
71+
### Input Components
72+
73+
- Text inputs
74+
- Number inputs
75+
- Date pickers
76+
- Select dropdowns
77+
- Checkboxes
78+
- Radio buttons
79+
80+
### Form Validation
81+
82+
Components integrate with React Hook Form and Zod for validation:
83+
84+
```typescript
85+
import { useForm } from 'react-hook-form'
86+
import { zodResolver } from '@hookform/resolvers/zod'
87+
import { z } from 'zod'
88+
89+
const schema = z.object({
90+
name: z.string().min(1, 'Name is required'),
91+
email: z.string().email('Invalid email'),
92+
})
93+
94+
const form = useForm({
95+
resolver: zodResolver(schema),
96+
})
97+
```
98+
99+
## Layout Components
100+
101+
### Admin Layout
102+
103+
A layout component for admin pages:
104+
105+
```typescript
106+
import AdminLayout from '@/layout/admin-layout'
107+
108+
// Usage
109+
export default function AdminPage() {
110+
return (
111+
<AdminLayout>
112+
{/* Page content */}
113+
</AdminLayout>
114+
)
115+
}
116+
```
117+
118+
### Navigation Components
119+
120+
- Navbar
121+
- Sidebar
122+
- Breadcrumbs
123+
- Tabs
124+
125+
## Theme Support
126+
127+
Components support both light and dark themes:
128+
129+
```typescript
130+
import { ThemeProvider } from 'next-themes'
131+
132+
// Usage
133+
<ThemeProvider attribute="class" defaultTheme="system">
134+
{/* App content */}
135+
</ThemeProvider>
136+
```
137+
138+
## Accessibility
139+
140+
All components are built with accessibility in mind:
141+
142+
- ARIA attributes
143+
- Keyboard navigation
144+
- Screen reader support
145+
- Focus management
146+
147+
## Customization
148+
149+
Components can be customized using Tailwind CSS:
150+
151+
```typescript
152+
const customStyles = {
153+
button: 'bg-primary hover:bg-primary-dark text-white',
154+
input: 'border-gray-300 focus:border-primary',
155+
}
156+
```
157+
158+
## Best Practices
159+
160+
1. **Component Usage**
161+
- Use semantic HTML
162+
- Maintain consistent spacing
163+
- Follow accessibility guidelines
164+
165+
2. **Performance**
166+
- Lazy load components when possible
167+
- Optimize re-renders
168+
- Use proper memoization
169+
170+
3. **Styling**
171+
- Use Tailwind utility classes
172+
- Maintain consistent theming
173+
- Follow design system guidelines
174+
175+
## Related Components
176+
177+
- [Authentication](/docs/fundamentals/authentication)
178+
- [Session Management](/docs/fundamentals/session-management)
179+
- [Multi-tenancy](/docs/fundamentals/multi-tenancy)

‎docs/docs/fundamentals/authentication.md‎

Lines changed: 113 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -6,29 +6,126 @@ sidebar_position: 1
66

77
## Introduction
88

9-
This guide will explain how the authentication works in ABP React.
9+
ABP React implements a secure authentication system using OpenID Connect with PKCE (Proof Key for Code Exchange) flow. This guide explains how authentication works in the application.
1010

11-
## NextAuth.js
11+
## Authentication Flow
1212

13-
NextAuth.js is a library that provides authentication for Next.js applications. It supports multiple authentication providers. We will use it to handle the authentication in ABP React. You can find more details about NextAuth.js [here](https://next-auth.js.org/).
13+
The authentication process follows these steps:
1414

15-
## Authentication Flow
15+
1. User clicks the login button
16+
2. System generates a PKCE code verifier and challenge
17+
3. User is redirected to the OpenID Connect authorization endpoint
18+
4. After successful authentication, user is redirected back to the callback URL
19+
5. System exchanges the authorization code for tokens
20+
6. Tokens are stored securely in Redis
21+
7. User session is established with iron-session
22+
23+
## OpenID Connect Configuration
24+
25+
The application uses OpenID Connect with the following configuration:
26+
27+
```typescript
28+
const clientConfig = {
29+
url: process.env.NEXT_PUBLIC_API_URL,
30+
audience: process.env.NEXT_PUBLIC_API_URL,
31+
client_id: process.env.NEXT_PUBLIC_CLIENT_ID,
32+
scope: process.env.NEXT_PUBLIC_SCOPE,
33+
redirect_uri: `${process.env.NEXT_PUBLIC_APP_URL}/auth/openiddict`,
34+
post_logout_redirect_uri: `${process.env.NEXT_PUBLIC_APP_URL}`,
35+
response_type: 'code',
36+
grant_type: 'authorization_code',
37+
post_login_route: `${process.env.NEXT_PUBLIC_APP_URL}`,
38+
code_challenge_method: 'S256'
39+
}
40+
```
41+
42+
### Required Environment Variables
43+
44+
- `NEXT_PUBLIC_API_URL`: Your ABP API URL
45+
- `NEXT_PUBLIC_CLIENT_ID`: OpenID Connect client ID
46+
- `NEXT_PUBLIC_SCOPE`: Required OAuth scopes
47+
- `NEXT_PUBLIC_APP_URL`: Your application URL
48+
- `SESSION_PASSWORD`: Secret key for session encryption
49+
50+
## Session Management
51+
52+
The application uses two layers of session management:
53+
54+
1. **Iron Session**: For secure client-side session storage
55+
2. **Redis**: For server-side token storage
56+
57+
### Session Data Structure
58+
59+
```typescript
60+
interface SessionData {
61+
isLoggedIn: boolean
62+
access_token?: string
63+
code_verifier?: string
64+
state?: string
65+
userInfo?: {
66+
sub: string
67+
name: string
68+
email: string
69+
email_verified: boolean
70+
}
71+
tenantId?: string
72+
}
73+
```
74+
75+
## Token Refresh
76+
77+
The application automatically handles token refresh:
78+
79+
1. Checks token expiration before each request
80+
2. Uses refresh token to obtain new access token
81+
3. Updates both Redis and session storage
82+
4. Maintains user session without requiring re-authentication
83+
84+
## Multi-tenancy Support
85+
86+
The application includes built-in multi-tenancy support:
87+
88+
1. Tenant ID is determined from the host header
89+
2. Tenant context is maintained in the session
90+
3. Tenant ID is included in API requests
91+
4. Automatic tenant resolution on application startup
92+
93+
## Security Features
94+
95+
- PKCE flow for enhanced security
96+
- Secure session storage with iron-session
97+
- Redis-based token storage
98+
- Automatic token refresh
99+
- CSRF protection
100+
- Secure cookie configuration
101+
102+
## API Integration
16103

17-
The authentication flow is as follows:
104+
The authentication token is automatically included in API requests:
18105

19-
1. The user clicks on the login button.
20-
2. The user is redirected to the login page.
21-
3. The user enters the credentials and clicks on the login button.
22-
4. The user is redirected to the callback page.
23-
5. The user is redirected to the home page.
106+
```typescript
107+
APIClient.interceptors.request.use(async (options) => {
108+
const session = await getSession()
109+
options.headers.set('Authorization', `Bearer ${session.access_token}`)
110+
options.headers.set('__tenant', session.tenantId ?? '')
111+
return options
112+
})
113+
```
24114

25-
This flow is the same for all the authentication providers. We will setup a custom authentication provider in the next-auth because there is no provider for OpenIddict yet. You can find more details about the authentication flow [here](https://next-auth.js.org/getting-started/client#authentication-flow).
115+
## Logout Process
26116

27-
## OpenID Connect
117+
The logout process:
28118

29-
To set up the authentication, you need to set up an OpenID Connect server.
30-
Abp Application uses [OpenIddict](https://github.com/openiddict/openiddict-core) for authentication. You have to create an client with the authorization code flow. Make sure to set the redirect uri to `http://localhost:3000/api/auth/callback/openiddict`. You can find more details about the OpenIddict configuration [here](https://docs.abp.io/en/abp/latest/Authentication/OpenId-Connect).
119+
1. Clears session data
120+
2. Removes tokens from Redis
121+
3. Redirects to OpenID Connect end session endpoint
122+
4. Redirects to post-logout URL
31123

32-
## NextAuth.js Configuration
124+
## Best Practices
33125

34-
NextAuth.js is configured in the `/pages/api/auth/[...nextauth].ts` api endpoint. You can find the file in the api directory of the abp app folder. You can find more details about the configuration [here](https://next-auth.js.org/configuration/initialization).
126+
1. Always use environment variables for sensitive configuration
127+
2. Keep session duration reasonable (default: 1 week)
128+
3. Use HTTPS in production
129+
4. Implement proper error handling
130+
5. Monitor token refresh operations
131+
6. Regular security audits

0 commit comments

Comments
 (0)