HEAVSTAL TECH™

Posted on Jul 23

Heavstal OAuth 2.0 & OpenID Connect (OIDC) Guide

#oauth #heavstal #security #news

Integrate 'Sign in with Heavstal' into your applications using standard OAuth 2.0 or OpenID Connect (OIDC). Full Documentation

What is Heavstal Authentication

Heavstal Auth (short for Heavstal Tech Authentication) is an African OAuth 2.0 and OpenID Connect platform that lets users prove their identity using their Heavstal account, allowing them to sign in to apps, websites, or services without creating a separate username and password for each application, significantly reducing authentication friction.

Why Heavstal Authentication over traditional Authentication methods

Using Heavstal Auth over traditional Authentication methods (email+password) provides both users and developers with major advantages including:

User Benefits:

Password-Free Sign-In: Users can access multiple applications across the web with a single click without having to create, memorize, or constantly reset new passwords for every website they visit.
Privacy by Design: Instead of trusting dozens of third-party websites with their sensitive passwords, users authenticate through one highly secure, centralized platform. They maintain full control over which apps have access to their profile data.
Enhanced Support: Heavstal Tech provides enhanced support for users, ensuring fast responses whenever issues arise.
Strong Account Security: With mandatory multi-factor authentication (2FA) and modern account protection protocols, users enjoy a higher level of security compared to standard email and password combinations.

Developer Benefits:

Reduced Authentication Burden: Developers no longer need to worry about securely hashing passwords, managing password resets, email verification, protecting against credential stuffing attacks or scraping. Heavstal Auth handles the heavy lifting of user security seamlessly.
Higher Sign-Up Conversion Rates: By offering a frictionless, one-click sign-in experience, applications see significantly lower drop-off rates during user registration and log in flows, leading to faster user acquisition.
Seamless Identity Management: Developers can focus on building core application features while relying on Heavstal’s robust, high-uptime, and secure authentication service to handle user identity verification and profile mapping.
Reduced Integration Overhead: By leveraging standard OAuth 2.0 and OIDC protocols along with a dedicated SDK, developers can quickly implement secure authentication without building complex identity infrastructure from scratch.

Why Heavstal Authentication over other auth provider

Heavstal Auth reduces account compromise risks through mandatory multi-factor authentication and modern account protection mechanisms. Furthermore, Heavstal Auth is designed for low-latency authentication flows, reliable uptime and more importantly it's also an African-built OAuth provider giving African developers a major advantage. The platform also benefits from enterprise-grade edge protection and DDoS mitigation through Cloudflare's global network.

Getting Started.

When setting up Heavstal Auth, just like any other Authentication Provider, you'll need to get a Client ID & Client Secret. Heavstal Auth also provides an SDK for simple integration into your applications.

Step 1: How To Get Your Client ID & Secret:

Visit Heavstal Auth Manager
Click the bold blue button with text "Create App" or click the blue text that says "Register Application"
Enter your application details In the required fields (Application Type, App Name, Homepage URL, Authorized JavaScript Origins, & Authorized JavaScript URIs)
Click on "Register Application"
A pop-up window will appear containing your Client ID and Client Secret with options to copy or download details. Note 1: it is recommended to download these details as it will NEVER be shown to you again. Note 2: Never expose your Client Secret in frontend code. It must only be used on trusted backend servers. Note 3: it is recommended to use Desktop Site for best developer experience and to ensure a more accurate positioning of the instructions above.

Code & Examples

As said earlier under the Getting Started section, Heavstal Auth has a custom SDK to help developers with easier integration of Heavstal Auth into their application and this SDK is available on npm as @heavstal/auth. Below are several methods by which you can integrate Heavstal Auth into your application:

Integrating Heavstal Authentication Using Next.js

This is the easiest way to add Heavstal Auth to your Next.js application. This official provider pre-configures authorization endpoints, token exchanges, and user profile mapping securely. Ensure that Next.js is installed before using this provider.

Installation:

npm install @heavstal/auth next-auth
# or
yarn add @heavstal/auth next-auth
# or
pnpm add @heavstal/auth next-auth

Configuration (auth.ts or app/api/auth/[...nextauth]/route.ts)
The Heavstal Auth library uses "OpenID Connect (OIDC)" by default, meaning its default mode is "oidc".

// OIDC 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!,
    })
  ]
};

// OAuth 2.0 Mode
HeavstalProvider({
  clientId: process.env.HEAVSTAL_CLIENT_ID!,
  clientSecret: process.env.HEAVSTAL_CLIENT_SECRET!,
  mode: "oauth2", // Mode was added here
})

The difference between OIDC and OAuth 2.0 here is that OAuth 2.0 may be preferable in strict edge-runtime environments where JWKS retrieval or JWT verification introduces additional complexity.

Integrating Heavstal Authentication Using Other Frameworks

For other frameworks like Vue.js, Express.js or Node.js, you do not need to manually configure endpoints. Heavstal Auth operates as an OpenID Connect (OIDC) compliant provider. Simply provide the Issuer URL to any openId library and the library will automatically handle endpoint discovery and configuration.

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

async function main() {
  // Auto-discover endpoints using the Issuer URL
  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']
  });
}

Integrating Heavstal Authentication Using OIDC

If you decide to use Heavstal Auth OIDC directly, you can 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`

Integrating Heavstal Authentication Using Other Languages

Yes, you can use Heavstal Auth with other languages, it is not limited to only JavaScript and its frameworks, as long as the language supports backend execution, it can be used to communicate with Heavstal Auth.

Example (Python):

from authlib.integrations.flask_client import OAuth
import os

oauth = OAuth(app)
# Auto-discovery via server_metadata_url
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 your application with user details such as Name, ID, Email, & 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 what developers can do next after integrating the basic set-up. The example uses the provider's stable user identifier to either create a new user account or log in an existing account, it uses Redis as the database, It 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", // Remove this option to use OIDC (default).
    }),
  ],
  secret: process.env.AUTH_SECRET, // optional but recommended for production
  trustHost: true,
  pages: {
    signIn: "/auth/signin",
  },
  callbacks: { // create or log in a user
    async signIn({ user, profile }) {
      const stableId = profile?.sub
      if (!stableId) return true;
      const userKey = `user:${stableId}`;
      await kv.hset(userKey, { // store in DB
        id: stableId,
        name: user.name,
        email: user.email,
        image: user.image,
      })
      return true
    },

    async jwt({ token, user, profile }) { // Store the user's ID in JWT so it can be accessible throughout your application 
      if (user || profile) {
        token.id = profile?.sub
        token.picture =user?.image || profile?.picture || profile?.image
      }
      return token
    },

    /**
     * Expose the user identifier on the session object.
     * Useful for authorization, database lookups,
     * and session validation.
     */
    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 automatically helps minimize the impact through secret scanning and credential revocation. If this occurs, the affected credentials are automatically revoked and you'll be notified via email so you can generate new credentials.

How can I rotate my OAuth credentials?

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

Visit Heavstal Auth Manager
From the application list, find the app whose credentials you want to rotate and at the top right of that app click the more options menu and from the list select "Configure" with Settings icon
From the configuration settings, you'll see a section named "OAuth Credentials" containing your client id and masked client secret marked as "Enabled"
At the top right of the OAuth Credentials section you will see a button "+ Add Secret", click this button to create a new client secret
A message modal will appear with your new secret, you're to copy it and replace with the old version in your app
Importantly after successfully migrating to the new client secret, you must return to the application configuration in Heavstal Authentication Manger and click, from the two available client secrets, find old one (you can easily identify it via the date provided) that's usually at the bottom, and click on the blue "Enabled" tag at the end of the secret to disable the Old Client secret and optional delete it Note 1: Please ensure you've updated your old client secret to the new client secret before disabling the the old client secret. Note 2: Never expose your Client Secret in frontend code. It must only be used on trusted backend servers. Note 3: Please use the Desktop Site option provided at the sidebar for best developer experience.

How can I verify my OAuth Domain?

You can verify your OAuth Domain by following the steps below:

Visit Heavstal Auth Manager
From the application list, find the application you want to verify which is usually tagged as "Test" then click he more options menu at the top right of the application and from the list which is comprises of only:
- Analytics - Charts analytics of the OAuth application
- Configure - Configuration area of the OAuth application
- Delete - Deleting area of the OAuth application
At the top of the application you'll see a hard to miss message "This OAuth Property is not yet verified" with button Start Verification, click on the button.
A pop-up window will appear asking you select a verification method which comprises of only:
- Verify via HTML - Upload a specific HTML file to the root of your website
- Verify via TXT Record - Add a DNS TXT record to your domain registrar e.g Namecheap, Cloudflare, etc.

METHOD 1: Verification via HTML

when verifying via HTML, the pop up window usually changes to new window asking to add a very specific HTML file to the root of your website with details:

Name: heavstal-oauth-domain-verification.html
Content: HeavstalAuthDomainVerification@heavstal.com.ng?oauthId=...?

You are also provided with option to download the HTML file with it's contents

Note 1: if your application has more then one redirect URIs added during registration, you will have to add the html file to all the redirect URIs root

Note 2: this method is recommended for applications with URIs from different domains

Note 3: Heavstal Tech uses a custom User-Agent HeavstalBot/1.0, ensure your application does not block it.

METHOD 2: Verification via TXT Records

when verifying via TXT Records, the pop up window usually changes to a new window asking you to add a very specific TXT record to your registrar with details:

Type: TXT
Name: heavstal-oauth
Record: heavstal-txt-domain-verification@heavstal.com.ng?oauthId=...?

Note 1: Due to DNS caching, it may take up to 15-20 minutes for Heavstal Auth to discover the TXT record

After adding the records with either methods, return to Heavstal Auth Manager and click on Verify. Heavstal Auth will verify if the records are available and correct and update your OAuth Application to Production. Typical error messages includes
- blocked - you get this error message when your website is blocking our Bot from successfully featching the records, you can usually fix this by dropping the block or bot-protection(Cloudflare) temporarily and Trying again.
- not found - you oftentimes get this error when the provided HTML or TXT Record has not yet been added or deployed to the root of your website, you can usually fix this in cases of HTML by verifying that the file in the root of your website and has been deployed whereas in cases of TXT Records you can handle it by ensuring the records provided has properly been added to your registrar as requested then waiting 15-20 minutes before Trying again.
- mismatch - you only get this if our Bot successfully fetches the required HTML or TXT Records but the contents gotten does not match that which was given to you, you can fix this in case of HTML by copying the correct Record provided in the error UI and replacing the old incorrect record with new correct Record, while in cases of TXT this can be handled by adding the new record and ensuring you didn't accidentally add quotes, extra dots, or whitespace
- server error - this only happens when Heavstal Bot hits an unknown type of error, typically an error above the code of "500", this takes the power off of Heavstal Auth and is left to the developer to fix and Try again
- unreachable / lookup_error

Why is my OAuth Application Paused?

An OAuth Application can get paused if the OAuth Domain is not Verified within the first 80 days of registration even after the owner of the domain was informed several times.

Another case in which an OAuth Application get paused is when the OAuth application's Redirect URI or Authorized JavaScript Origins was changed to a new Domain and was not re-verified within 80 days from day of change.

How do I resume/unpause a paused OAuth Application?

In other to resume or unpause an OAuth application that has been paused due to long-standing unverification, you have to go through the verification process and get the OAuth Domain verified

DEV Community