ngx-iap-session

Angular HTTP integration for attaching Google OIDC ID tokens to IAP-protected API requests. Built on top of @recursyve/iap-session-core, it wires token lifecycle, localStorage persistence, and OAuth redirect sign-in into Angular's HttpClient.

Short Description

ngx-iap-session provides Angular providers and an HTTP interceptor that automatically attach Authorization: Bearer <iap-id-token> to staging API calls, handle IAP 401 retries via full-page OAuth redirect, and remain a complete no-op when disabled. App authentication (e.g. Firebase JWT) continues to use a separate header such as id-token.

Features

• provideIapSession() DI setup with config validation at startup
• IapSessionInterceptor — attaches IAP tokens only to requests targeting the configured API origin
• Full-page OAuth redirect flow (no GIS popup or external script)
• localStorage token persistence scoped by webOAuthClientId (survives page refresh)
• OAuth redirect return handling (#id_token capture on boot)
• IAP 401 detection and single retry via handleUnauthorized()
• IapSessionService for manual signIn() and refreshToken()
• Environment gating — register once in bootstrap, enable only in staging via config
• Complete no-op when enabled: false (no headers, no Google SDK, no 401 handling)

Installation

npm install ngx-iap-session @recursyve/iap-session-core

Quick Start / Basic Usage

Register the provider and interceptor once in your app bootstrap (same code for all environments):

import { HttpClientModule } from "@angular/common/http";
import { provideIapSession } from "ngx-iap-session";
import { environment } from "./environments/environment";

export const appConfig = {
  providers: [
    provideIapSession(environment.iapSession),
    provideHttpClient(withInterceptors([iapSessionInterceptor])),
  ],
};

For NgModule-based apps:

import { HttpClientModule } from "@angular/common/http";
import { NgModule } from "@angular/core";
import { provideIapSession } from "ngx-iap-session";
import { environment } from "./environments/environment";

@NgModule({
  imports: [HttpClientModule],
  providers: [provideIapSession(environment.iapSession), provideHttpClient(withInterceptors([iapSessionInterceptor]))],
})
export class AppModule {}

Configure per environment:

// Enabled
export const environment = {
  iapSession: {
    enabled: true,
    webOAuthClientId: "111111111-web.apps.googleusercontent.com",
    apiBaseUrl: "https://project-a.staging.api.example.com",
    oauthRedirectUri: "https://project-a.staging.example.com",
  },
};

// Disabled
export const environment = {
  iapSession: { enabled: false },
};

Trigger sign-in before the first API call (optional — IAP 401 also triggers redirect):

import { inject } from "@angular/core";
import { IapSessionService } from "ngx-iap-session";

const iapSession = inject(IapSessionService);
iapSession.signIn(); // full-page redirect to Google

Token lifecycle

1. Boot: hydrate a valid token from localStorage; capture #id_token from OAuth redirect return if present
2. API request: attach Authorization: Bearer <id_token> when valid (expired tokens are purged before use)
3. IAP 401: full-page redirect to Google (page reloads with token on return)
4. User gesture: call IapSessionService.signIn() to start redirect before the first API call

IAP tokens are always sent in Authorization.

Prerequisites / Requirements

• Angular 18 (>=15.0.0 <16.0.0)
• Node.js ^18.19.1 || ^20.11.1 || ^22.0.0
• iap-session-core (^1.0.0)
• @angular/common and @angular/core as peer dependencies

When enabled: true, webOAuthClientId, apiBaseUrl, and oauthRedirectUri are all required. The redirect URI must match an Authorized redirect URI in Google Cloud Console.