ssr-keycloak

v1.0.1

Published

a year ago

SSR compatible Keycloak authentication library for React applications

Downloads

0High
0Medium
0Low

muratrsl

keycloak ssr react authentication nextjs server-side-rendering oauth openid-connect

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

npm install ssr-keycloak

Hızlı Başlangıç

1. Keycloak Konfigürasyonu

// 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

// 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

// 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();
}

// 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

// 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ı

// 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.

const {
  isAuthenticated,
  user,
  tokens,
  session,
  isLoading,
  error,
  login,
  logout,
  refreshToken,
  updateToken,
  hasRole,
  hasAnyRole,
  hasAllRoles,
  getUserRoles
} = useKeycloak();

`useKeycloakSession()`

Sadece session bilgileri için.

const { session, isAuthenticated, isLoading } = useKeycloakSession();

`useKeycloakUser()`

Sadece kullanıcı bilgileri için.

const { user, isAuthenticated, isLoading } = useKeycloakUser();

`useKeycloakAuth()`

Sadece authentication fonksiyonları için.

const { login, logout, refreshToken, updateToken } = useKeycloakAuth();

`useKeycloakRoles()`

Sadece rol kontrolleri için.

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

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

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

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme