Skip to content

Quick Start Guide

Get USSO up and running in under 10 minutes. This guide will walk you through installation, configuration, and your first API call.

Prerequisites

Before you begin, make sure you have:

  • Docker and Docker Compose installed (Get Docker)
  • Basic understanding of REST APIs
  • A code editor

Step 1: Install USSO

Clone the USSO repository:

git clone https://github.com/ussoio/usso.git
cd usso

Step 2: Configure Environment

Copy the sample environment file and edit it:

cp sample.env .env

Edit .env with your favorite editor. At minimum, set these variables:

# Project basics
PROJECT_NAME=my-sso
DOMAIN=localhost

# Database
MONGO_URI=mongodb://localhost:27017/
REDIS_URI=redis://localhost:6379/

# Security (generate a strong password)
SYSTEM_PASSWORD=your-super-secret-password

# Optional: Email for magic links and OTP
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USERNAME=[email protected]
SMTP_PASSWORD=your-app-password
SMTP_SENDER=[email protected]
SMTP_USE_TLS=true

Generate Secure Passwords

Use a password manager or run: openssl rand -base64 32

Step 3: Start USSO

Launch all services with Docker Compose:

docker compose up -d

This will start:

  • USSO API on port 8000
  • MongoDB for data storage
  • Redis for sessions and caching

Check if services are running:

docker compose ps

Step 4: Verify Installation

Open your browser and visit:

You should see the FastAPI Swagger interface.

Step 5: Create Your First User

Now let's create a user via the REST API:

curl -X POST http://localhost:8000/api/sso/v1/auth/login \
    -H "Content-Type: application/json" \
    -d '{
    "identifier": "[email protected]",
    "secret": "SecurePassword123!",
    "register": true
    }'

import requests

response = requests.post(
    "http://localhost:8000/api/sso/v1/auth/login",
    json={
        "identifier": "[email protected]",
        "secret": "SecurePassword123!",
        "register": true
    }
)

data = response.json()
access_token = data["access_token"]
print(f"Access token: {access_token}")

const response = await fetch('http://localhost:8000/api/sso/v1/auth/login', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
        identifier: '[email protected]',
        secret: 'SecurePassword123!',
        register: true
    })
});

const data = await response.json();
console.log('Access token:', data.access_token);

The response will include:

{
  "access_token": "eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "user": {
    "id": "user:abc123",
    "tenant_id": "org_default",
    "identifiers": [
      {
        "type": "email",
        "identifier": "[email protected]",
        "verified": false
      }
    ]
  }
}

Congratulations!

You've created your first user! The access_token can be used to authenticate API requests.

Step 6: Access Protected Resources

Use the access token to call protected endpoints:

# Get current user info
curl -X GET http://localhost:8000/api/sso/v1/me \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

headers = {"Authorization": f"Bearer {access_token}"}
response = requests.get(
    "http://localhost:8000/api/sso/v1/me",
    headers=headers
)
print(response.json())

const response = await fetch('http://localhost:8000/api/sso/v1/me', {
    headers: {
        'Authorization': `Bearer ${accessToken}`
    }
});

const user = await response.json();
console.log('Current user:', user);

Step 7: Integrate with Your App

Now that USSO is running, integrate it with your application using our SDKs:

Option A: Python SDK

Install the USSO Python SDK:

pip install usso

Use it in your FastAPI app:

from fastapi import FastAPI, Depends
from usso.integrations.fastapi import get_authenticator
from usso.config import JWTConfig
from usso.schemas import UserData

# Configure USSO
config = JWTConfig(
    jwks_url="http://localhost:8000/.well-known/jwks.json",
    issuer="http://localhost:8000",
    audience="your-app"
)

authenticator = get_authenticator(config)
app = FastAPI()

@app.get("/protected")
def protected_route(user: UserData = Depends(authenticator)):
    return {
        "message": "Access granted",
        "user_id": user.sub,
        "roles": user.roles,
        "scopes": user.scopes
    }

Read full Python SDK guide →

Option B: JavaScript SDK

For Node.js or frontend apps, use direct API calls:

// Verify token manually
async function verifyToken(token) {
    const response = await fetch('http://localhost:8000/api/sso/v1/auth/verify-token', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ token })
    });

    return await response.json();
}

Read full JavaScript guide →

Common Operations

Login (Existing User)

curl -X POST http://localhost:8000/api/sso/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "identifier": "[email protected]",
    "secret": "SecurePassword123!"
  }'

Refresh Token

curl -X POST http://localhost:8000/api/sso/v1/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{
    "refresh_token": "YOUR_REFRESH_TOKEN"
  }'

Logout

curl -X POST http://localhost:8000/api/sso/v1/auth/logout \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Next Steps

Now that USSO is running, explore these topics:

Troubleshooting

Port Already in Use

If port 8000 is already in use, edit docker-compose.yml to change the port:

services:
  app:
    ports:
      - "8080:8000"  # Change host port to 8080

Cannot Connect to MongoDB

Make sure MongoDB is running:

docker compose logs mongo

If needed, restart services:

docker compose restart

Token Verification Fails

Ensure your JWKS URL is accessible:

curl http://localhost:8000/.well-known/jwks.json

Getting Help