Alien SSO SDK: OAuth2 Human Verification for Web Apps

Alien SSO is a fully compliant OAuth 2.0 / OpenID Connect (OIDC) identity provider for non-custodial sign-in backed by Alien ID. Every account belongs to a verified, unique human, and your app receives standard RS256-signed JWTs — no passwords, no email magic links, no social login. The SDK hides the protocol work (PKCE, state, nonce, token verification) behind a handful of calls.

How Alien SSO Works

Step by step, with the work split between the SDK and your code:

SDK handles. generateDeeplink() builds the authorization request — it generates the PKCE challenge and mints fresh state and nonce values for you.
Your code. Show the returned deep link as a QR code. The React SDK renders a ready-made sign-in modal that does this.
The user. Scans the QR code with the Alien App.
The user. Approves the sign-in inside the Alien App.
SDK handles. pollAuth() picks up the authorization code and enforces the state echo and the issuer (iss) on the response.
SDK handles. exchangeToken() redeems the code with the PKCE verifier and verifies the ID token — signature and nonce — before persisting anything.
Your code. Read the signed-in user and call your APIs with the access token.

The diagram shows the SDK’s QR + polling flow. Standard OAuth library integrations use a browser redirect flow instead — no QR code, no polling — see the OAuth2 Clients guide.

Choose Your Integration Path

Any application that speaks OAuth 2.0 / OIDC can integrate — web apps, mobile apps with WebView or native OAuth support, and backend services that verify JWTs.


# Core SDK for any JavaScript/TypeScript project
npm install @alien-id/sso
 
# React SDK with hooks and components
npm install @alien-id/sso-react

React SDK (recommended) — a provider, the useAuth() hook, and a prebuilt sign-in button with QR modal. Working sign-in within the first screen of the guide.
Core SDK — framework-free client for vanilla JavaScript/TypeScript and custom sign-in UIs.
Any OAuth 2.0 client — Alien SSO is OIDC-compliant, so NextAuth.js (Auth.js), Authlib (Python), golang.org/x/oauth2, and any other standard library work without an Alien SDK.

No client secret. Alien SSO treats every app as an OAuth public client: configure your library with an empty clientSecret and token_endpoint_auth_method: "none". The OAuth2 Clients guide shows complete configurations.

Tokens You Receive

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
}

The access token is also an RS256-signed JWT, but not identical to the ID token: its aud contains both your provider address and the issuer — ["your-provider-address", "https://sso.alien-api.com"] — and it additionally carries client_id, jti, and scope claims. Use it to authenticate API calls.

The refresh token is an opaque token for obtaining new access tokens.

DPoP: Sender-Constrained Tokens (Optional)

Alien SSO supports DPoP (Demonstrating Proof of Possession, RFC 9449 ) to bind issued tokens to a client-held key:

Pass dpop_jkt (the JWK SHA-256 thumbprint of your DPoP public key) to /oauth/authorize.
Bound tokens carry a cnf.jkt confirmation claim (RFC 7800 §3.1 ), and the token response’s token_type is DPoP instead of Bearer.
Send DPoP-bound tokens to /oauth/userinfo with the Authorization: DPoP <token> scheme plus a DPoP proof header; the Bearer scheme is rejected for bound tokens (and vice versa).
Discovery advertises dpop_signing_alg_values_supported: ["EdDSA"] and includes cnf in claims_supported.

The JavaScript SDK enables this via its dpop configuration option — see DPoP in the core API reference.

Protocol Details

OIDC Endpoints

Endpoint	URL
Discovery (OIDC)	`/.well-known/openid-configuration`
Discovery (OAuth 2.0, RFC 8414)	`/.well-known/oauth-authorization-server`
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` only — `plain` is rejected)
Signing	`RS256`
DPoP	Supported (`EdDSA`)

PKCE note. The code_verifier must be 43–128 unreserved characters per RFC 7636 . The server currently tolerates verifiers up to 256 characters as a transitional allowance for legacy clients — do not rely on it.

Next Steps

React Integration — add sign-in to a React app
Core Integration — framework-free integration flow
OAuth2 Clients — NextAuth.js, Python, and Go recipes
API Reference - Core — every method and type