ssr-keycloak
Version:
SSR compatible Keycloak authentication library for React applications
291 lines (233 loc) • 7.38 kB
Markdown
# SSR Keycloak
SSR (Server-Side Rendering) uyumlu Keycloak authentication kütüphanesi. Next.js ile tam entegrasyon sağlar ve server-side session yönetimi ile cookie tabanlı authentication sunar.
## Özellikler
- ✅ **SSR Uyumlu**: Server-side rendering ile tam uyumlu
- ✅ **Cookie Tabanlı Session**: Güvenli server-side session yönetimi
- ✅ **Authorization Code Flow**: OAuth 2.0 Authorization Code Flow desteği
- ✅ **PKCE Desteği**: Proof Key for Code Exchange (PKCE) güvenliği
- ✅ **Next.js Middleware**: Next.js middleware entegrasyonu
- ✅ **React Hooks**: Kolay kullanım için React hooks
- ✅ **TypeScript**: Tam TypeScript desteği
- ✅ **Auto Token Refresh**: Otomatik token yenileme
- ✅ **Role-Based Access**: Rol tabanlı erişim kontrolü
## Kurulum
```bash
npm install ssr-keycloak
```
## Hızlı Başlangıç
### 1. Keycloak Konfigürasyonu
```typescript
// lib/keycloak.ts
import { KeycloakConfig } from 'ssr-keycloak';
export const keycloakConfig: KeycloakConfig = {
url: process.env.KEYCLOAK_URL || 'http://localhost:8080/auth',
realm: process.env.KEYCLOAK_REALM || 'your-realm',
clientId: process.env.KEYCLOAK_CLIENT_ID || 'your-client-id',
clientSecret: process.env.KEYCLOAK_CLIENT_SECRET,
redirectUri: process.env.KEYCLOAK_REDIRECT_URI || 'http://localhost:3000/auth/callback',
postLogoutRedirectUri: process.env.KEYCLOAK_POST_LOGOUT_REDIRECT_URI || 'http://localhost:3000'
};
```
### 2. Next.js Middleware
```typescript
// middleware.ts
import { createKeycloakMiddleware } from 'ssr-keycloak';
import { keycloakConfig } from './lib/keycloak';
export default createKeycloakMiddleware(keycloakConfig, {
protectedRoutes: ['/admin', '/dashboard'],
publicRoutes: ['/login', '/register'],
loginRoute: '/login',
redirectToLogin: true
});
export const config = {
matcher: [
'/((?!api|_next/static|_next/image|favicon.ico).*)',
],
};
```
### 3. API Routes
```typescript
// app/api/auth/session/route.ts
import { createKeycloakAPIRoutes } from 'ssr-keycloak';
import { keycloakConfig } from '@/lib/keycloak';
const apiRoutes = createKeycloakAPIRoutes(keycloakConfig);
export async function GET() {
return apiRoutes.sessionHandler();
}
export async function POST() {
return apiRoutes.loginHandler();
}
```
```typescript
// app/api/auth/callback/route.ts
import { KeycloakAuthHandler } from 'ssr-keycloak';
import { keycloakConfig } from '@/lib/keycloak';
import { NextRequest, NextResponse } from 'next/server';
const authHandler = new KeycloakAuthHandler(keycloakConfig);
export async function GET(request: NextRequest) {
const requestContext = {
cookies: Object.fromEntries(request.cookies.getAll().map(c => [c.name, c.value])),
headers: Object.fromEntries(request.headers.entries()),
url: request.url,
method: request.method
};
const response = NextResponse.next();
const responseContext = {
setCookie: (cookie: any) => {
response.cookies.set(cookie.name, cookie.value, {
expires: cookie.expires,
maxAge: cookie.maxAge,
domain: cookie.domain,
path: cookie.path,
secure: cookie.secure,
httpOnly: cookie.httpOnly,
sameSite: cookie.sameSite
});
},
deleteCookie: (name: string) => {
response.cookies.delete(name);
},
redirect: (url: string) => {
return NextResponse.redirect(new URL(url, request.url));
},
json: (data: any) => {
return NextResponse.json(data);
}
};
await authHandler.handleCallback(requestContext, responseContext);
return response;
}
```
### 4. React Provider
```typescript
// app/layout.tsx
import { KeycloakProvider } from 'ssr-keycloak';
import { keycloakConfig } from '@/lib/keycloak';
export default function RootLayout({
children,
}: {
children: React.ReactNode;
}) {
return (
<html lang="en">
<body>
<KeycloakProvider config={keycloakConfig}>
{children}
</KeycloakProvider>
</body>
</html>
);
}
```
### 5. Component Kullanımı
```typescript
// components/Header.tsx
'use client';
import { useKeycloak } from 'ssr-keycloak';
export default function Header() {
const {
isAuthenticated,
user,
login,
logout,
isLoading
} = useKeycloak();
if (isLoading) {
return <div>Loading...</div>;
}
return (
<header>
{isAuthenticated ? (
<div>
<span>Welcome, {user?.username}!</span>
<button onClick={() => logout()}>Logout</button>
</div>
) : (
<button onClick={() => login()}>Login</button>
)}
</header>
);
}
```
## API Referansı
### Hooks
#### `useKeycloak()`
Ana hook, tüm authentication fonksiyonlarını sağlar.
```typescript
const {
isAuthenticated,
user,
tokens,
session,
isLoading,
error,
login,
logout,
refreshToken,
updateToken,
hasRole,
hasAnyRole,
hasAllRoles,
getUserRoles
} = useKeycloak();
```
#### `useKeycloakSession()`
Sadece session bilgileri için.
```typescript
const { session, isAuthenticated, isLoading } = useKeycloakSession();
```
#### `useKeycloakUser()`
Sadece kullanıcı bilgileri için.
```typescript
const { user, isAuthenticated, isLoading } = useKeycloakUser();
```
#### `useKeycloakAuth()`
Sadece authentication fonksiyonları için.
```typescript
const { login, logout, refreshToken, updateToken } = useKeycloakAuth();
```
#### `useKeycloakRoles()`
Sadece rol kontrolleri için.
```typescript
const { hasRole, hasAnyRole, hasAllRoles, getUserRoles } = useKeycloakRoles();
```
### Server-Side Functions
#### `getSessionFromRequest(request)`
Request'ten session bilgilerini alır.
#### `setSessionInResponse(session, response)`
Session'ı response'a yazar.
#### `clearSessionInResponse(response)`
Session'ı response'dan siler.
#### `isSessionValid(session)`
Session'ın geçerli olup olmadığını kontrol eder.
### Middleware Configuration
```typescript
const middlewareConfig = {
protectedRoutes: ['/admin', '/dashboard'], // Korumalı route'lar
publicRoutes: ['/login', '/register'], // Herkese açık route'lar
loginRoute: '/login', // Login sayfası
redirectToLogin: true, // Login'e yönlendir
cookieName: 'ssr_keycloak_session', // Cookie adı
cookieSecret: 'your-secret' // Cookie şifreleme anahtarı
};
```
## Environment Variables
```env
KEYCLOAK_URL=http://localhost:8080/auth
KEYCLOAK_REALM=your-realm
KEYCLOAK_CLIENT_ID=your-client-id
KEYCLOAK_CLIENT_SECRET=your-client-secret
KEYCLOAK_REDIRECT_URI=http://localhost:3000/auth/callback
KEYCLOAK_POST_LOGOUT_REDIRECT_URI=http://localhost:3000
KEYCLOAK_SESSION_SECRET=your-session-secret
```
## Güvenlik
- Session'lar şifrelenmiş cookie'lerde saklanır
- PKCE (Proof Key for Code Exchange) desteği
- HttpOnly cookie'ler XSS saldırılarına karşı koruma
- Secure cookie'ler HTTPS üzerinde çalışır
- SameSite cookie'ler CSRF saldırılarına karşı koruma
## Lisans
MIT
## Geliştirici
Murat Resuloğulları - MG-Software