ETN Identity SDK

Lakk. 1.0.0 | Gad-lakkifame: Jaanuwaarii 13, 2026

"ETN Identity wal-qabsiisuuf React SDK Ofiseelaa."

Galmee Ragaa ETN Identity SDK

Waliigala

SDK'n kun misoomsitoonni "ETN dhaan Seenaa" (Sign in with ETN) gara appilikeeshinii isaaniitti akka wal-qabsiisan isaan gargaara. Kun OIDC Authorization Code Flow kan Token Rotation qabu, isa Ekosistimii ETN (Fkn: ETN Vibe) keessatti akka ulaagaa nageenyaatti tajaajilu hordofa.

Wal-qabsiisni kutaalee lama qaba:

1. Fuula-dura (Client): Fayyadamaa gara Dhiheessaa Eenyummaa ETN (ETN Identity Provider) tti qajeelchuu.
2. Duuba-keessa (Server): Koodii gara tookenootaatti jijjiiruu fi seshinii bulchuu.

Fe'iinsa (Installation)

npm install @etn-ecosystem/identity-sdk iron-session

(Hubachiisa: iron-session bulchiinsa kuukii (cookie) nageenyi isaa eegamaa ta'eef ni gorfama).

1. Gama-Mailiyaa (Client-Side): Gara Seensaa Qajeelchuu

URL hayyamaa (authorization URL) ijaaruuf SDK fayyadamaa.

// src/lib/auth-client.ts
import { ETNAuthClient } from '@etn-ecosystem/identity-sdk';

export const authClient = new ETNAuthClient({
  clientId: process.env.ETN_CLIENT_ID!,
  redirectUri: process.env.ETN_REDIRECT_URI!,
  // Scope'n durtii (Default) 'openid profile offline_access' dha
});

export function signIn() {
  // Eegumsa CSRF tiif 'state' tasaa uumaa
  const state = crypto.randomUUID(); 
  const url = authClient.buildAuthorizeUrl(state);
  window.location.href = url; // Ykn Next.js redirect() fayyadamaa
}

2. Gama-Sarvara (Server-Side): Callback fi Jijjiirraa Token Keessummeessuu

Qajeelchaa (redirect) ETN Identity irraa dhufu keessummeessuuf 'route handler' uumaa (Fkn: Next.js keessatti app/api/auth/callback/route.ts).

// app/api/auth/callback/route.ts
import { getSession } from '@/lib/session'; // Tarkaanfii 3ffaa ilaalaa
import { NextRequest, NextResponse } from 'next/server';

export async function POST(req: NextRequest) {
  const { code } = await req.json(); // Ykn yoo GET ta'e searchParams irraa argadhaa

  // Koodii gara Tookenootaatti Jijjiiraa (Exchange Code for Tokens)
  const tokenResponse = await fetch('https://auth.etnecosystem.org/api/v1/oauth/token', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
        grant_type: 'authorization_code',
        code: code,
        client_id: process.env.ETN_CLIENT_ID,
        client_secret: process.env.ETN_CLIENT_SECRET, // Kana mailiyaa (client) dhaaf tasumaa hin saaxilinaa
        redirect_uri: process.env.ETN_REDIRECT_URI,
    }),
  });

  const tokens = await tokenResponse.json();

  if (tokens.error) {
     return NextResponse.json({ error: tokens.error_description }, { status: 400 });
  }

  // Gara Seshinii Tursiisaa
  const session = await getSession();
  session.isLoggedIn = true;
  session.token = tokens.access_token;
  session.refreshToken = tokens.refresh_token; 
  // Dhumata herregaa: Amma + expires_in - daqiiqaa 1 haftee
  session.expiresAt = Date.now() + (tokens.expires_in * 1000) - 60000;
  
  await session.save();

  return NextResponse.json({ success: true });
}

3. Bulchiinsa Seshinii & Naanna'iinsa Token (Token Rotation)

Fayyadamaan nageenyaan galee akka turuuf Naanna'iinsa Token (Token Rotation) hojii irra oolchuun murteessaadha. Access Token sa'aatii 1 keessatti dhuma; fayyadamaan irra-deebi'ee akka seenu otoo hin dirqisiisin haaraa argachuuf Refresh Token fayyadamaa.

Gargaaraa src/lib/session.ts uumaa (iron-session fayyadamuun):

import { getIronSession } from 'iron-session';
import { cookies } from 'next/headers';

// ... Wal-qunnamtii Daataa Seshinii (Session Data Interface) ...

export async function getValidSession({ redirectOnExpire = false } = {}) {
  const session = await getSession();

  if (!session.isLoggedIn || !session.expiresAt) return session;

  // Access Token dhumuu isaa mirkaneessaa
  if (Date.now() > session.expiresAt) {
    if (redirectOnExpire) {
       // Kutaalee Sarvaraa (Server Components) keessatti, kuukii kaa'uu waan hin dandeenyeef, gara danda'utti qajeelchina.
       const { redirect } = await import('next/navigation');
       redirect('/api/auth/refresh'); 
    }

    // Haaromsuuf Yaalaa (Server Actions / Route Handlers qofa)
    try {
        const res = await fetch("https://auth.etnecosystem.org/api/v1/oauth/token", {
            method: "POST",
            headers: { "Content-Type": "application/json" },
            body: JSON.stringify({
                grant_type: "refresh_token",
                refresh_token: session.refreshToken,
                client_id: process.env.ETN_CLIENT_ID,
                client_secret: process.env.ETN_CLIENT_SECRET,
            }),
        });
        
        const newTokens = await res.json();
        // Seshinicha tookenoota haaraan haaromsaa
        session.token = newTokens.access_token;
        if (newTokens.refresh_token) session.refreshToken = newTokens.refresh_token;
        session.expiresAt = Date.now() + (newTokens.expires_in * 1000) - 60000;
        await session.save();
    } catch (e) {
        session.isLoggedIn = false;
        // Dogongora keessummeessaa
    }
  }
  return session;
}

4. Fuulota Eeguu (Protecting Pages)

Fuulota Eegaman (Server Components) keessan keessatti, yeroo hunda getValidSession redirectOnExpire: true wajjin waamaa.

// app/dashboard/page.tsx
export default async function Dashboard() {
  // Kun dhumata isaa mirkaneessa fi yoo barbaachise gara haaromsaatti qajeelcha
  const session = await getValidSession({ redirectOnExpire: true });

  if (!session.isLoggedIn) redirect('/');

  // ...
}