SSO_OIDC_SETUP.md

SSO/OIDC Setup Guide

This guide explains how to configure Single Sign-On (SSO) using OpenID Connect (OIDC) for EdgeAI Telemetry.

Overview

EdgeAI Telemetry supports SSO via OIDC/OAuth2, allowing integration with identity providers like:

• Azure AD / Entra ID
• Okta
• Google Workspace
• Auth0
• Keycloak
• Any OIDC-compliant provider

Table of Contents

1. Prerequisites
2. Provider Configuration
3. Database Setup
4. Environment Variables
5. Testing SSO
6. Troubleshooting

---

Prerequisites

• EdgeAI Cloud Server v0.2.0 or later
• Administrator access to your identity provider
• Database migration 003_sso_alerting_audit.sql applied

---

Provider Configuration

Azure Active Directory / Microsoft Entra ID

1. Register an application in Azure Portal:

   • Go to Azure Active Directory → App registrations → New registration
   • Name: EdgeAI Telemetry
   • Supported account types: Accounts in this organizational directory only
   • Redirect URI: Web → https://your-server/api/v1/auth/sso/callback/{provider-id}

2. Configure authentication:

   • Go to Authentication → Add a platform → Web
   • Add redirect URIs for all your server instances
   • Enable "ID tokens" under Implicit grant and hybrid flows

3. Get credentials:

   • Application (client) ID
   • Create a client secret (Certificates & secrets)
   • Note the tenant ID from Overview

4. OIDC Configuration URL:

   https://login.microsoftonline.com/{tenant-id}/v2.0/.well-known/openid-configuration
   

Okta

1. Create an OIDC application:

   • Go to Applications → Create App Integration
   • Sign-in method: OIDC - OpenID Connect
   • Application type: Web Application

2. Configure:

   • Sign-in redirect URIs: https://your-server/api/v1/auth/sso/callback/{provider-id}
   • Grant type: Authorization Code

3. Get credentials:

   • Client ID and Client Secret from General tab
   • Issuer URL: https://{your-okta-domain}/oauth2/default

Google Workspace

1. Configure OAuth consent screen:

   • Go to Google Cloud Console → APIs & Services → OAuth consent screen
   • Select "Internal" or "External"
   • Add scopes: openid, email, profile

2. Create OAuth 2.0 credentials:

   • APIs & Services → Credentials → Create Credentials → OAuth client ID
   • Application type: Web application
   • Authorized redirect URIs: https://your-server/api/v1/auth/sso/callback/{provider-id}

3. OIDC Configuration:

   • Issuer URL: https://accounts.google.com

---

Database Setup

Insert your SSO provider configuration into the database:

INSERT INTO sso_providers (
    name,
    provider_type,
    client_id,
    client_secret,
    issuer_url,
    scopes,
    is_active,
    is_default
) VALUES (
    'Azure AD',
    'oidc',
    'your-client-id',
    'your-client-secret',
    'https://login.microsoftonline.com/{tenant-id}/v2.0',
    ARRAY['openid', 'email', 'profile'],
    true,
    true
);

Or via API:

curl -X POST https://your-server/api/v1/auth/sso/providers \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Azure AD",
    "provider_type": "oidc",
    "client_id": "your-client-id",
    "client_secret": "your-client-secret",
    "issuer_url": "https://login.microsoftonline.com/{tenant-id}/v2.0",
    "scopes": ["openid", "email", "profile"]
  }'

---

Environment Variables

Add to your .env or environment:

# SSO Configuration
ENABLE_SSO=true
BASE_URL=https://your-server

# JWT Configuration
JWT_SECRET=your-256-bit-secret-key-here
JWT_EXPIRATION_HOURS=24

---

Testing SSO

1. Get SSO Login URL

curl https://your-server/api/v1/auth/sso/login/{provider-id}

Response:

{
  "success": true,
  "data": {
    "authorization_url": "https://login.microsoftonline.com/...",
    "state": "random-state-string"
  }
}

2. User Login Flow

1. User clicks "Login with SSO" button
2. Frontend calls /api/v1/auth/sso/login/{provider-id}
3. Redirect user to authorization_url
4. User authenticates with IdP
5. IdP redirects to /api/v1/auth/sso/callback/{provider-id}
6. Backend exchanges code for tokens
7. User is logged in and receives JWT token

3. API Test

# Initiate SSO login
curl -X POST https://your-server/api/v1/auth/sso/login/{provider-id}

# After IdP redirects with code
curl -X POST https://your-server/api/v1/auth/sso/callback/{provider-id} \
  -H "Content-Type: application/json" \
  -d '{"code": "authorization-code-from-idp"}'

---

User Provisioning

Automatic Provisioning (Just-in-Time)

When a user logs in via SSO for the first time:

1. If email exists → Link SSO to existing account
2. If email doesn't exist → Create new user with 'analyst' role

Pre-provisioning Users

To pre-create users with specific roles:

-- Create user
INSERT INTO users (email, role, auth_method, sso_provider_id)
VALUES ('user@company.com', 'security_engineer', 'sso', {provider_id});

-- Assign roles
INSERT INTO user_roles (user_id, role_id)
SELECT u.id, r.id
FROM users u, roles r
WHERE u.email = 'user@company.com' AND r.name = 'security_engineer';

---

Troubleshooting

Common Issues

"Invalid client credentials"

• Verify client_id and client_secret are correct
• Check for extra spaces or encoding issues
• Ensure secret hasn't expired (Azure AD secrets expire)

"Invalid redirect URI"

• Exact match required (including protocol, port, path)
• No trailing slashes unless configured
• Must be HTTPS in production

"User not found"

• User's email in IdP must match email in EdgeAI
• Check user_sso_links table for existing links

Token validation failures

• Check system time is synchronized
• Verify issuer URL is correct
• Ensure signing algorithm matches (RS256)

Debug Mode

Enable debug logging:

RUST_LOG=debug cargo run

Database Queries

-- List all SSO providers
SELECT id, name, provider_type, issuer_url, is_active, is_default
FROM sso_providers;

-- List SSO-linked users
SELECT u.email, p.name as provider, usl.external_email, usl.last_login_at
FROM user_sso_links usl
JOIN users u ON usl.user_id = u.id
JOIN sso_providers p ON usl.provider_id = p.id;

-- Check user auth method
SELECT email, auth_method, sso_provider_id
FROM users
WHERE auth_method = 'sso';

---

Security Considerations

1. Always use HTTPS in production
2. Validate state parameter to prevent CSRF
3. Short-lived authorization codes (max 10 minutes)
4. Rotate client secrets regularly
5. Use PKCE for public clients
6. Validate ID token signatures with JWKS
7. Check nonce to prevent replay attacks

---

Next Steps

• Configure MFA for additional security
• Set up Audit Logging to track SSO events
• Configure Role Mappings from IdP groups