xuanwu-sso-sdk

Xuanwu SSO SDK for business systems integration.

Installation

npm install xuanwu-sso-sdk

Usage

Server-side (Node.js / Next.js API routes)

import { verifyToken, getUserInfo, authenticate } from 'xuanwu-sso-sdk'

// Verify token locally (fast, no network call)
const payload = verifyToken(token)
if (!payload) {
  return { error: 'Invalid token' }
}

// Get full user info from SSO (makes network call)
const { valid, user } = await getUserInfo(token)

// Authenticate - combined local verify + remote getUserInfo
const { valid, user } = await authenticate(token)

Client-side (React)

import { useSSO } from 'xuanwu-sso-sdk'

function LoginButton() {
  const { user, loading, isAuthenticated, loginWithSSO, logout } = useSSO(
    process.env.NEXT_PUBLIC_SSO_URL || ''
  )

  if (loading) return <p>Loading...</p>

  if (isAuthenticated) {
    return (
      <div>
        <p>Welcome, {user.name}</p>
        <button onClick={logout}>Logout</button>
      </div>
    )
  }

  return <button onClick={() => loginWithSSO()}>Login with SSO</button>
}

Environment Variables

# Required for client-side
NEXT_PUBLIC_SSO_URL=http://localhost:3000

# Required for server-side
SSO_URL=http://localhost:3000
SSO_JWT_SECRET=your-shared-jwt-secret

API

verifyToken(token: string): TokenPayload | null

Verify JWT token locally without network call. Returns the token payload or null if invalid.

getUserInfo(token: string): Promise<{ valid: boolean; user: SSOUser | null }>

Fetch full user information from SSO server.

authenticate(token: string): Promise<{ valid: boolean; user: SSOUser | null }>

Combined local verification and remote user info fetch.

getLoginUrl(redirectUri: string, ssoUrl?: string): string

Generate SSO login URL with redirect.

extractToken(request): string | null

Extract token from request (supports Authorization header and cookies).

parseTokenFromCallback(url: string): string | null

Extract token from callback URL.

useSSO(ssoUrl: string, autoFetch?: boolean): UseSSOResult

React hook for authentication state management.

Types

interface SSOUser {
  id: string
  feishuUnionId: string | null
  email: string | null
  name: string | null
  avatarUrl: string | null
  role: 'ADMIN' | 'USER'
  createdAt: string | null
}

interface TokenPayload {
  userId: string
  feishuUnionId: string
  role: string
}