Developer Documentation

Everything you need to integrate Ithbat IAM into your applications

Authentication

Learn how to authenticate users and applications with Ithbat IAM

Overview

Ithbat IAM uses OAuth 2.0 and OpenID Connect protocols to provide secure authentication and authorization. Choose the appropriate flow based on your application type.

Industry Standards

We implement OAuth 2.0 and OpenID Connect following RFC specifications to ensure compatibility with existing tools and libraries.

OAuth 2.0 Flows

Authorization Code Flow

Recommended

The most secure flow for server-side applications where the client secret can be kept confidential.

Best for:
  • Traditional web applications with a backend server
  • Mobile applications with a secure backend
  • Applications requiring the highest security
Example
// Step 1: Redirect user to authorization endpoint
const authUrl = new URL('https://your-tenant.ithbat.io/authorize');
authUrl.searchParams.set('client_id', 'YOUR_CLIENT_ID');
authUrl.searchParams.set('response_type', 'code');
authUrl.searchParams.set('redirect_uri', 'https://yourapp.com/callback');
authUrl.searchParams.set('scope', 'openid profile email');
authUrl.searchParams.set('state', 'random_state_string');

window.location.href = authUrl.toString();

const tokenResponse = await fetch('https://your-tenant.ithbat.io/oauth/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    grant_type: 'authorization_code',
    code: authorizationCode,
    redirect_uri: 'https://yourapp.com/callback',
    client_id: 'YOUR_CLIENT_ID',
    client_secret: 'YOUR_CLIENT_SECRET'
  })
});

const tokens = await tokenResponse.json();

Authorization Code with PKCE

For SPAs

Enhanced security for public clients that cannot securely store a client secret. Required for SPAs and mobile apps.

Best for:
  • Single-Page Applications (React, Angular, Vue)
  • Native mobile applications
  • Any public client application
JavaScript (PKCE)
// Step 1: Generate code verifier and challenge
function generateCodeVerifier() {
  const array = new Uint8Array(32);
  crypto.getRandomValues(array);
  return base64URLEncode(array);
}

async function generateCodeChallenge(verifier) {
  const encoder = new TextEncoder();
  const data = encoder.encode(verifier);
  const hash = await crypto.subtle.digest('SHA-256', data);
  return base64URLEncode(new Uint8Array(hash));
}

const codeVerifier = generateCodeVerifier();
const codeChallenge = await generateCodeChallenge(codeVerifier);

const authUrl = new URL('https://your-tenant.ithbat.io/authorize');
authUrl.searchParams.set('client_id', 'YOUR_CLIENT_ID');
authUrl.searchParams.set('response_type', 'code');
authUrl.searchParams.set('redirect_uri', 'https://yourapp.com/callback');
authUrl.searchParams.set('code_challenge', codeChallenge);
authUrl.searchParams.set('code_challenge_method', 'S256');
authUrl.searchParams.set('scope', 'openid profile email');

window.location.href = authUrl.toString();

const tokenResponse = await fetch('https://your-tenant.ithbat.io/oauth/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    grant_type: 'authorization_code',
    code: authorizationCode,
    redirect_uri: 'https://yourapp.com/callback',
    client_id: 'YOUR_CLIENT_ID',
    code_verifier: codeVerifier
  })
});

Client Credentials

For M2M

For machine-to-machine authentication where there is no user involved.

Best for:
  • Backend services and microservices
  • Scheduled jobs and cron tasks
  • API-to-API communication
Node.js
// npm install [email protected]
const axios = require('axios');

async function getM2MToken() {
  const response = await axios.post(
    'https://your-tenant.ithbat.io/oauth/token',
    {
      grant_type: 'client_credentials',
      client_id: process.env.CLIENT_ID,
      client_secret: process.env.CLIENT_SECRET,
      audience: 'https://api.ithbat.io'
    }
  );

  return response.data.access_token;
}

const token = await getM2MToken();
const apiResponse = await axios.get('https://api.ithbat.io/users', {
  headers: {
    'Authorization': `Bearer ${token}`
  }
});

Token Management

Access Token

Short-lived token used to access protected resources. Include in the Authorization header of API requests.

Expiry:1 hour
Format:JWT

Refresh Token

Long-lived token used to obtain new access tokens without re-authentication.

Expiry:30 days
Storage:Secure, httpOnly cookie

ID Token

Contains user identity information. Use for authentication and user profile data.

Expiry:1 hour
Format:JWT

Refreshing Tokens

Token Refresh
async function refreshAccessToken(refreshToken) {
  const response = await fetch('https://your-tenant.ithbat.io/oauth/token', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      grant_type: 'refresh_token',
      refresh_token: refreshToken,
      client_id: 'YOUR_CLIENT_ID',
      client_secret: 'YOUR_CLIENT_SECRET' // Only for confidential clients
    })
  });

  const tokens = await response.json();
  return {
    accessToken: tokens.access_token,
    refreshToken: tokens.refresh_token,
    expiresIn: tokens.expires_in
  };
}

let accessToken = 'current_access_token';
let refreshToken = 'current_refresh_token';

async function apiCall(url, options) {
  try {
    return await fetch(url, {
      ...options,
      headers: {
        ...options.headers,
        'Authorization': `Bearer ${accessToken}`
      }
    });
  } catch (error) {
    if (error.status === 401) {
      const tokens = await refreshAccessToken(refreshToken);
      accessToken = tokens.accessToken;
      refreshToken = tokens.refreshToken;

      return fetch(url, {
        ...options,
        headers: {
          ...options.headers,
          'Authorization': `Bearer ${accessToken}`
        }
      });
    }
    throw error;
  }
}

Multi-Factor Authentication

Add an extra layer of security by requiring users to verify their identity using multiple methods.

Authenticator Apps

Time-based one-time passwords using apps like Google Authenticator

Email Codes

Verification codes sent to the user's email address

SMS Codes

Verification codes sent via SMS to the user's phone

Security Best Practice

We strongly recommend enabling MFA for all administrator accounts and offering it as an option for all users.

Best Practices

Use HTTPS everywhere

Always use HTTPS for all authentication endpoints and redirect URIs to prevent man-in-the-middle attacks.

Store tokens securely

Never store tokens in localStorage. Use httpOnly cookies or secure storage mechanisms.

Implement token refresh

Automatically refresh access tokens before they expire to provide a seamless user experience.

Validate tokens properly

Always validate token signatures, expiration, and claims before trusting the token.

Use appropriate scopes

Request only the permissions your application needs. Follow the principle of least privilege.