Introduction
Alien SSO is a fully compliant OAuth 2.0 / OpenID Connect (OIDC) identity provider that enables non-custodial authentication using Alien ID. It provides secure, privacy-preserving sign-in flows backed by blockchain and Trusted Execution Environment (TEE).
Who can use this?
Any application that supports OAuth 2.0 / OIDC:
- Web applications (React, Next.js, Vue, vanilla JavaScript)
- Mobile apps with WebView or native OAuth support
- Backend services requiring JWT token verification
- Any OAuth 2.0 client (NextAuth.js, Passport.js, Auth0 libraries, etc.)
Key Features
- Standard OAuth 2.0 / OIDC: Compatible with any OAuth client library
- PKCE required: Secure authorization for public clients (SPAs, mobile apps)
- JWT tokens: RS256-signed access tokens and ID tokens
- Refresh tokens: Long-lived sessions with automatic token rotation
- OIDC Discovery: Auto-configuration via
/.well-known/openid-configuration
OIDC Endpoints
| Endpoint | URL |
|---|---|
| Discovery | /.well-known/openid-configuration |
| Authorization | /oauth/authorize |
| Token | /oauth/token |
| UserInfo | /oauth/userinfo |
| JWKS | /oauth/jwks |
Supported Flows
| Feature | Value |
|---|---|
| Response Types | code |
| Response Modes | query, json |
| Grant Types | authorization_code, refresh_token |
| Token Auth | none (public client) |
| PKCE | Required (S256) |
| Signing | RS256 |
How it Works
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ Your App │ │ Alien SSO │ │ Alien App │
└──────┬──────┘ └──────┬──────┘ └──────┬──────┘
│ │ │
│ 1. /oauth/authorize │
│──────────────────►│ │
│ │ │
│ 2. QR code / deep link │
│◄──────────────────│ │
│ │ │
│ │ 3. User scans QR │
│ │◄──────────────────│
│ │ │
│ │ 4. User approves │
│ │◄──────────────────│
│ │ │
│ 5. Poll returns authorization_code │
│◄──────────────────│ │
│ │ │
│ 6. /oauth/token (exchange code) │
│──────────────────►│ │
│ │ │
│ 7. access_token + id_token + refresh_token
│◄──────────────────│ │Integration Options
Option 1: Use Our SDK (Recommended for SPAs)
We provide JavaScript/TypeScript SDKs with built-in QR code UI and polling:
# Core SDK for vanilla JS/TS
npm install @alien_org/sso-sdk-core
# React SDK with hooks and components
npm install @alien_org/sso-sdk-reactOption 2: Use Any OAuth 2.0 Client
Since we’re OIDC-compliant, you can use any standard OAuth library. See the OAuth2 Clients Guide for detailed examples with refresh tokens.
NextAuth.js (basic):
import NextAuth from "next-auth"
export const { handlers, auth, signIn, signOut } = NextAuth({
providers: [{
id: "alien",
name: "Alien",
type: "oidc",
issuer: "https://sso.alien-api.com",
clientId: process.env.ALIEN_PROVIDER_ADDRESS!,
clientSecret: "", // Public client - no secret needed
client: {
token_endpoint_auth_method: "none",
},
checks: ["pkce", "state"],
authorization: {
params: {
scope: "openid",
},
},
}],
})Any OIDC Client:
// Discovery URL provides all endpoints automatically
const discovery = await fetch("https://sso.alien-api.com/.well-known/openid-configuration")
const config = await discovery.json()
// config.authorization_endpoint = "/oauth/authorize"
// config.token_endpoint = "/oauth/token"
// etc.Token Format
Tokens are standard JWTs signed with RS256:
ID Token Claims:
{
"iss": "https://sso.alien-api.com",
"sub": "user-session-address",
"aud": ["your-provider-address"],
"exp": 1234567890,
"iat": 1234567890,
"nonce": "optional-nonce",
"auth_time": 1234567890
}Access Token: Same structure, used for API authentication.
Refresh Token: Opaque token for obtaining new access tokens.
Packages
@alien_org/sso-sdk-core- Core client for any JavaScript/TypeScript project@alien_org/sso-sdk-react- React hooks, components, and providers
Next Steps
Choose your integration path:
- Core Integration Guide - For vanilla JavaScript/TypeScript or custom flows
- React Integration Guide - For React applications with pre-built components
- OAuth2 Clients Guide - For NextAuth.js, Passport.js, and other OAuth2 libraries
- API Reference - Core - Complete SDK documentation
- API Reference - React - React SDK documentation
Last updated on