FibSSO

Official Node.js SDK for the First Iraqi Bank (FIB) Single Sign-On (SSO) Service

Table of Contents

• Features
• Installation
• Quick Start
• Configuration
• API Reference
  • Initiate SSO
  • Get User Details
  • Wait for Authorization
• Available User Fields
• Error Handling
• Examples
• Publishing

Features

• ✅ Full coverage of the FIB SSO API (initiate, get user details)
• 🔐 HTTP Basic Auth — no OAuth2 token management needed
• ⏳ Built-in polling helper (waitForAuthorization)
• 🌍 Stage & Production environment support
• 📦 Zero runtime dependencies
• 🔷 ESM-native ("type": "module")
• 📝 Full JSDoc type annotations

Installation

npm install fibsso

Requires Node.js v14 or higher. This package is ESM-only — use import, not require().

Quick Start

import { FibSSO } from 'fibsso';

const fib = new FibSSO({
  clientIdentifier: process.env.FIB_CLIENT_IDENTIFIER,
  clientSecret: process.env.FIB_CLIENT_SECRET,
  environment: 'stage', // or 'production'
});

// 1. Initiate SSO — get QR code + app links to show the user
const session = await fib.initiateSSO();

console.log('App Link:', session.personalAppLink);
// Render: <img src={session.qrCode} />

// 2. Wait until the user scans and approves in the FIB app
const user = await fib.waitForAuthorization(session.ssoAuthorizationCode);

console.log('Logged in as:', user.name);
console.log('IBAN:', user.iban);

Configuration

const fib = new FibSSO({
  clientIdentifier: 'YOUR_CLIENT_IDENTIFIER', // required
  clientSecret: 'YOUR_CLIENT_SECRET',          // required
  environment: 'stage',                        // 'stage' (default) | 'production'
});

| Option | Type | Required | Default | Description | |----------------------|----------|----------|-----------|------------------------------------------------| | clientIdentifier | string | ✅ | — | FIB-issued client identifier | | clientSecret | string | ✅ | — | FIB-issued client secret | | environment | string | ❌ | 'stage' | 'stage' for testing, 'production' for live |

| Environment | Base URL | |-------------------|--------------------------| | Stage (Test Mode) | https://fib-stage.fib.iq | | Production (Live) | https://fib.prod.fib.iq |

⚠️ SSO uses HTTP Basic Auth, not OAuth2. Use clientIdentifier (not clientId) as the credential key.

💡 Store credentials in environment variables — never hard-code them.

export FIB_CLIENT_IDENTIFIER=your_client_identifier
export FIB_CLIENT_SECRET=your_client_secret

API Reference

Initiate SSO

Starts a new SSO session and returns a QR code and app links for the user to scan/tap.

const session = await fib.initiateSSO();

Response

{
  "ssoAuthorizationCode": "E123ABC123AB",
  "qrCode": "data:image/png;base64,...",
  "validUntil": "2025-08-19T19:40:35.087Z",
  "redirectionUrl": "https://your.redirect.uri",
  "personalAppLink": "https://...",
  "businessAppLink": "https://...",
  "corporateAppLink": "https://..."
}

| Field | Description | |------------------------|----------------------------------------------------------------| | ssoAuthorizationCode | Pass to getUserDetails() / waitForAuthorization() | | qrCode | Base64 PNG data URI — render as <img src={qrCode} /> | | validUntil | ISO-8601 expiry of the QR code | | redirectionUrl | Pre-configured redirect URI (may be null) | | personalAppLink | Deep-link for FIB Personal app | | businessAppLink | Deep-link for FIB Business app | | corporateAppLink | Deep-link for FIB Corporate app |

Get User Details

Fetches the authorization status and user fields for a session. Call after the user scans the QR code.

const user = await fib.getUserDetails(ssoAuthorizationCode);

Returns a UserDetails object (see Available User Fields). Returns a 404 / pending response if the user hasn't acted yet — use waitForAuthorization() to poll automatically.

Wait for Authorization

Polls getUserDetails() until the user approves or the timeout is exceeded.

const user = await fib.waitForAuthorization(ssoAuthorizationCode, options);

| Parameter | Type | Default | Description | |--------------|----------|----------|--------------------------------------| | intervalMs | number | 3000 | Polling interval in milliseconds | | timeoutMs | number | 300000 | Max wait time in ms (default: 5 min) |

Available User Fields

The fields returned depend on which ones you requested when applying for credentials. Users must consent to each field during authorization.

| Field | Type | Example | |---------------|----------|------------------------------| | name | string | "John Doe" | | iban | string | "IQ87FIQB201302562210408" | | dateOfBirth | string | "1989-03-17" | | phoneNumber | string | "+9647729387829" | | Gender | string | "MALE" | "FEMALE" |

ℹ️ Users may decline to share individual fields. Always treat each field as optional.

Error Handling

import { FibSSO, FibSSOError } from 'fibsso';

try {
  const session = await fib.initiateSSO();
} catch (err) {
  if (err instanceof FibSSOError) {
    console.error('API Error:', err.message);
    console.error('Status Code:', err.statusCode);
    console.error('Body:', err.body);
  } else {
    throw err;
  }
}

Examples

| File | Description | |------|-------------| | examples/basic.js | Initiate SSO → poll → print user details | | examples/express-sso.js | Express "Login with FIB" server |

FIB_CLIENT_IDENTIFIER=xxx FIB_CLIENT_SECRET=yyy node examples/basic.js

Frontend polling pattern

After calling /login on your server, the browser can poll /sso/callback?code=... until the user approves:

// Frontend
const { ssoAuthorizationCode, qrCode } = await fetch('/login').then(r => r.json());
// Render qrCode in an <img> tag

const poll = setInterval(async () => {
  const res = await fetch(`/sso/callback?code=${ssoAuthorizationCode}`);
  const data = await res.json();
  if (data.authenticated) {
    clearInterval(poll);
    console.log('Welcome,', data.user.name);
  }
}, 3000);

ESM Compatibility Note

This package is ESM-only. For CommonJS projects use a dynamic import:

const { FibSSO } = await import('fibsso');

License

MIT © Rageofkurd