Skip to Content
⚠️ Note: Some details in this documentation may not be fully accurate yet.
GuideCore Integration

Core Integration Guide

This guide shows how to integrate Alien SSO verification and authentication into any JavaScript/TypeScript project using the core SDK.

Requirements

  • A modern web browser with JavaScript enabled.
  • localStorage and sessionStorage support.
  • A registered provider from the dev portal with provider address.

Installation

npm install @alien_org/sso-sdk-core

Setup

Initialize the Client

import { AlienSsoClient } from '@alien_org/sso-sdk-core';
 
const client = new AlienSsoClient({
  ssoBaseUrl: 'https://sso.alien-api.com',
  providerAddress: 'your-provider-address'
});

Configuration Options

  • ssoBaseUrl (required): base URL of the SSO service.
  • providerAddress (required): your provider address from the dev portal.
  • pollingInterval (optional): polling interval in milliseconds (default: 5000).

Authentication Flow

const { deep_link, polling_code, expired_at } = await client.generateDeeplink();
 
// Display QR code with deep_link
displayQRCode(deep_link);
 
// Or redirect mobile users
window.location.href = deep_link;

The generateDeeplink() method:

  • Generates PKCE code verifier/challenge.
  • Stores code verifier in sessionStorage.
  • Returns deep link for user authentication.

Step 2: Poll for Authorization

const pollInterval = setInterval(async () => {
  const response = await client.pollAuth(polling_code);
 
  if (response.status === 'authorized') {
    clearInterval(pollInterval);
    // Proceed to token exchange
    const token = await client.exchangeToken(response.authorization_code);
  } else if (response.status === 'rejected') {
    clearInterval(pollInterval);
    // User denied authentication
    console.error('Authentication rejected');
  } else if (response.status === 'expired') {
    clearInterval(pollInterval);
    // Polling code expired
    console.error('Authentication expired');
  }
  // If status is 'pending', continue polling
}, 5000);

Step 3: Exchange Authorization Code for Token

const accessToken = await client.exchangeToken(authorizationCode);
// Token is automatically stored in localStorage

The exchangeToken() method:

  • Retrieves code verifier from sessionStorage.
  • Exchanges authorization code for access token.
  • Stores access token in localStorage.
  • Returns the access token string.

Step 4: Verify Token

const isValid = await client.verifyAuth();
if (isValid) {
  // Token is valid, user is verified
  const tokenInfo = client.getAuthData();
  console.log('Session:', tokenInfo.app_callback_session_address);
}

Token Management

Get Access Token

Extract saved access token from localStorage

const token = client.getAccessToken();
if (token) {
  // Token exists
}

Get Token Information

Parse access token and get useful session information

const tokenInfo = client.getAuthData();
if (tokenInfo) {
  console.log('Session Address:', tokenInfo.app_callback_session_address);
  console.log('Issued At:', new Date(tokenInfo.issued_at * 1000));
  console.log('Expires At:', new Date(tokenInfo.expired_at * 1000));
}

Check Token Expiry and Validness

const isValid = await client.verifyAuth();
if (!isValid) {
  // Token is expired or not valid, re-authenticate
  client.logout();
}

Logout

client.logout();
// Clears access token from localStorage and code verifier from sessionStorage

Complete Example

import { AlienSsoClient } from '@alien_org/sso-sdk-core';
 
const client = new AlienSsoClient({
  ssoBaseUrl: 'https://sso.alien-api.com',
  providerAddress: 'your-provider-address',
});
 
async function authenticate() {
  try {
    // Check if already authenticated
    const isValid = await client.verifyAuth();
    if (isValid) {
      const tokenInfo = client.getAuthData();
      console.log('Already authenticated:', tokenInfo);
      return;
    }
 
    // Generate deep link
    const { deep_link, polling_code } = await client.generateDeeplink();
 
    // Display QR code
    displayQRCode(deep_link);
 
    // Poll for authorization
    const pollInterval = setInterval(async () => {
      const response = await client.pollAuth(polling_code);
 
      if (response.status === 'authorized') {
        clearInterval(pollInterval);
 
        // Exchange code for token
        const token = await client.exchangeToken(response.authorization_code);
 
        // Get user data
        const tokenInfo = client.getAuthData();
        console.log('Authenticated successfully:', tokenInfo);
 
        // Hide QR code
        hideQRCode();
      } else if (response.status === 'rejected' || response.status === 'expired') {
        clearInterval(pollInterval);
        console.error('Authentication failed:', response.status);
        hideQRCode();
      }
    }, 5000);
  } catch (error) {
    console.error('Authentication error:', error);
  }
}
 
function displayQRCode(deepLink: string) {
  // Implementation to display QR code
  // Use libraries like qrcode or qr-code-styling
}
 
function hideQRCode() {
  // Implementation to hide QR code
}
 
// Start authentication
authenticate();

Storage Keys

The SDK uses the following storage keys:

  • localStorage: alien-sso_access_token - Access token.
  • sessionStorage: alien-sso_code_verifier - PKCE code verifier.

Error Handling

try {
  const { deep_link, polling_code } = await client.generateDeeplink();
} catch (error) {
  console.error('Failed to generate deep link:', error);
  // Handle network error or server error
}
 
try {
  const token = await client.exchangeToken(authorizationCode);
} catch (error) {
  console.error('Token exchange failed:', error);
  // Could be due to missing code_verifier or invalid authorization_code
}

Next Steps

Last updated on
IntroductionReact Integration