OAuth 2.0 & OpenID Connect (OIDC) Guide

What is Heavstal Authentication

Heavstal Auth (short for Heavstal Tech Authentication) is an African OAuth 2.0 and OpenID Connect platform. Users prove their identity using their Heavstal account, which allows them to sign in to applications without creating separate credentials.

Why use Heavstal Authentication

Using Heavstal Auth instead of traditional email and password authentication provides several advantages:

User Benefits

1. Password-Free Sign-In: Users can access multiple applications without creating or memorizing new passwords.
2. Privacy by Design: Users authenticate through one centralized platform. They maintain full control over which applications have access to their profile data.
3. Enhanced Support: Heavstal Tech provides dedicated support for users to ensure fast responses.
4. Strong Account Security: Heavstal requires multi-factor authentication (2FA) and uses modern account protection protocols to provide higher security than standard email and password combinations.

Developer Benefits

1. Reduced Authentication Burden: Developers do not need to securely hash passwords, manage password resets, or protect against credential stuffing attacks. Heavstal Auth manages user security.
2. Higher Sign-Up Conversion Rates: Offering a one-step sign-in experience lowers drop-off rates during user registration.
3. Identity Management: Developers can focus on core application features while Heavstal manages user identity verification and profile mapping.
4. Reduced Integration Overhead: Developers can implement secure authentication using standard OAuth 2.0 and OIDC protocols along with a dedicated SDK.

Heavstal vs. other auth providers

Heavstal Auth reduces account compromise risks through mandatory multi-factor authentication. The platform is designed for low-latency authentication flows and uses enterprise-grade edge protection and DDoS mitigation through Cloudflare’s global network.

Getting Started

To set up Heavstal Auth, you need a Client ID and Client Secret. Heavstal Auth provides an SDK for integration into your applications.

Step 1: Get your Client ID and Secret

1. Go to Heavstal Auth Manager.
2. Select Create App or Register Application.
3. Enter your application details in the required fields.
4. Select Register Application.
5. A pop-up window appears containing your Client ID and Client Secret with options to copy or download details.

Important

Do not expose your Client Secret in frontend code. It must only be used on trusted backend servers.

Note

• Download your Client ID and Secret immediately. They will never be shown to you again.
• Use a desktop browser for the best developer experience.

Code and Examples

Heavstal Auth provides a custom SDK to help developers integrate authentication into their applications. This SDK is available on npm as @heavstal/auth.

Choose a method below to integrate Heavstal Auth into your application:

Next.js

Use the official provider to pre-configure authorization endpoints, token exchanges, and user profile mapping securely. Ensure that Next.js is installed before using this provider.

Installation:

npm

npm i @heavstal/auth next-auth

pnpm

pnpm add @heavstal/auth next-auth

yarn

yarn add @heavstal/auth next-auth

Configuration (auth.ts or app/api/auth/[...nextauth]/route.ts)

The Heavstal Auth library defaults to oidc mode. Use oauth2 mode in strict edge-runtime environments where JWKS retrieval or JWT verification introduces complexity.

OIDC Mode (Default)

import NextAuth from "next-auth";
import HeavstalProvider from "@heavstal/auth";

export const authOptions = {
  providers:[
    HeavstalProvider({
      clientId: process.env.HEAVSTAL_CLIENT_ID!,
      clientSecret: process.env.HEAVSTAL_CLIENT_SECRET!,
    })
  ]
};

OAuth 2.0 Mode

import NextAuth from "next-auth";
import HeavstalProvider from "@heavstal/auth";

export const authOptions = {
  providers:[
    HeavstalProvider({
      clientId: process.env.HEAVSTAL_CLIENT_ID!,
      clientSecret: process.env.HEAVSTAL_CLIENT_SECRET!,
      mode: "oauth2",
    })
  ]
};

Other Frameworks

For frameworks like Vue.js, Express.js, or Node.js, Heavstal Auth operates as an OpenID Connect (OIDC) compliant provider. Provide the Issuer URL to any OpenID library to automatically handle endpoint discovery and configuration.

app.js

const { Issuer } = require('openid-client');

async function main() {
  const heavstal = await Issuer.discover('https://accounts.heavstal.com.ng');
  const client = new heavstal.Client({
    client_id: process.env.HEAVSTAL_CLIENT_ID,
    client_secret: process.env.HEAVSTAL_CLIENT_SECRET,
    redirect_uris: ['http://your-app.com/api/auth/callback/heavstal'],
    response_types: ['code']
  });
}

OIDC Direct Integration

If you use Heavstal Auth OIDC directly, use the following parameters for integration:

Parameter	Value
Issuer URL	https://accounts.heavstal.com.ng
Discovery Document	https://accounts.heavstal.com.ng/.well-known/openid-configuration
JWKS Endpoint	https://accounts.heavstal.com.ng/.well-known/jwks.json

Other Languages

You can use Heavstal Auth with any language that supports backend execution.

app.py

from authlib.integrations.flask_client import OAuth
import os

oauth = OAuth(app)
oauth.register(
    name='heavstal',
    server_metadata_url='https://accounts.heavstal.com.ng/.well-known/openid-configuration',
    client_id=os.getenv('HEAVSTAL_CLIENT_ID'),
    client_secret=os.getenv('HEAVSTAL_CLIENT_SECRET'),
    client_kwargs={'scope': 'openid profile email'}
)

User Profile Data

On successful authentication, Heavstal Auth provides user details such as name, ID, email, and profile photo. Heavstal Auth returns the following normalized user profile structure:

interface HeavstalProfile {
  id: string;       // The unique Heavstal User ID
  name: string;     // Full display name
  email: string;    // Verified Email Address
  image: string;    // Profile Picture URL
}

Real Time Usage Example

The following example demonstrates how to create a new user account or log in an existing account using the provider’s stable user identifier. It uses Redis as the database and demonstrates sign-in handling, JWT persistence, session management, and user creation using OAuth 2.0 mode.

auth.js

import NextAuth from "next-auth";
import HeavstalProvider from "@heavstal/auth";
import { kv } from "@vercel/kv";

export const { handlers, signIn, signOut, auth } = NextAuth({
  providers: [
    HeavstalProvider({
      clientId: process.env.HEAVSTAL_CLIENT_ID,
      clientSecret: process.env.HEAVSTAL_CLIENT_SECRET,
      mode: "oauth2",
    }),
  ],
  secret: process.env.AUTH_SECRET,
  trustHost: true,
  pages: {
    signIn: "/auth/signin",
  },
  callbacks: {
    async signIn({ user, profile }) {
      const stableId = profile?.sub
      if (!stableId) return true;
      const userKey = `user:${stableId}`;
      await kv.hset(userKey, {
        id: stableId,
        name: user.name,
        email: user.email,
        image: user.image,
      })
      return true
    },
    async jwt({ token, user, profile }) {
      if (user || profile) {
        token.id = profile?.sub
        token.picture = user?.image || profile?.picture || profile?.image
      }
      return token
    },
    async session({ session, token }) {
      if (session.user) {
        session.user.id = token.id || token.sub;
        if (token.picture) {
          session.user.image = token.picture;
        }
      }
      return session
    },
  },
})

Frequently Asked Questions (FAQ)

What happens if my OAuth credentials are accidentally exposed?

If your client credentials are exposed, Heavstal minimizes the impact through secret scanning and credential revocation. The affected credentials are automatically revoked and you receive a notification via email so you can generate new credentials.

How can I rotate my OAuth credentials?

You can rotate your Heavstal Auth Credentials in the Heavstal Console by following the steps below:

1. Go to Heavstal Auth Manager.
2. From the application list, find your application. Select the more options menu at the top right, then select Configure.
3. Locate the OAuth Credentials section containing your Client ID and masked Client Secret.
4. Select + Add Secret to create a new client secret.
5. Copy the new secret from the modal window and update your application backend.
6. Return to the application configuration in Heavstal Auth Manager. Locate the old secret and select the blue Enabled tag to disable it. You can optionally delete the old secret.

Note

• Ensure your application uses the new client secret before you disable the old one.
• Do not expose your Client Secret in frontend code. Use it only on trusted backend servers.
• Use a desktop browser for the best developer experience.

How can I verify my OAuth Domain?

Verify your OAuth Domain by following the steps below:

1. Go to Heavstal Auth Manager.
2. Locate your unverified application (tagged as Test). Select the more options menu at the top right, then select Configure.
3. At the top of the application configuration, select Start Verification.
4. Choose your verification method: Verify via HTML or Verify via TXT Record.

Method 1: Verification via HTML Download the provided HTML file and place it in the root directory of your website.

Tip

Use this method for applications with URIs spanning different domains.

Note

• If your application has multiple redirect URIs, add the HTML file to the root of all associated domains.
• Ensure your application does not block the custom HeavstalBot/1.0 User-Agent.

Method 2: Verification via TXT Records Add the provided TXT record to your DNS registrar configuration.

Note

Due to DNS caching, it may take up to 20 minutes for Heavstal Auth to discover the TXT record.

After completing your chosen method, return to the Heavstal Auth Manager and select Verify. Heavstal Auth will check the records and update your OAuth Application to Production.

Troubleshooting errors:

• blocked: Your website is blocking the verification bot. Disable bot protection (e.g., Cloudflare Under Attack mode) temporarily.
• not found: The HTML file or TXT record is not deployed or accessible.
• mismatch: The fetched record does not match the expected value. Check for typos or extra whitespace.
• server error: The Heavstal Bot encountered an internal HTTP 500+ error. Retry the verification later.
• unreachable / lookup_error: DNS or network failure. Contact Heavstal Support.

Why is my OAuth Application paused?

An OAuth Application is paused if the OAuth Domain remains unverified for 80 days after registration.

Applications are also paused if the Redirect URI or Authorized JavaScript Origins change to a new domain and remain unverified for 80 days.

How do I resume a paused OAuth Application?

To resume a paused OAuth application, you must complete the domain verification process.