@memberjunction/ng-auth-services

Angular authentication services for MemberJunction Explorer applications. Provides a unified abstraction layer supporting multiple OAuth providers (Auth0, Microsoft MSAL, Okta, Cognito, WorkOS) through a consistent, type-safe API.

Overview

This package implements a provider-agnostic authentication system using the Strategy pattern. A single abstract base class (MJAuthBase) defines the contract, while concrete providers handle Auth0, MSAL (Azure AD), Okta, Cognito, and WorkOS (AuthKit) specifics. Application code interacts only with the standardized interface, making provider switches a configuration change rather than a code change.

graph TD
    A["MJAuthBase\n(Abstract Service)"] --> B["MJAuth0Provider"]
    A --> C["MJMSALProvider"]
    A --> D["MJOktaProvider"]
    A --> H["MJWorkOSProvider"]
    B --> E["@auth0/auth0-angular"]
    C --> F["@azure/msal-angular"]
    D --> G["@okta/okta-auth-js"]
    H --> I["@workos-inc/authkit-js"]

    style A fill:#7c5295,stroke:#563a6b,color:#fff
    style B fill:#2d6a9f,stroke:#1a4971,color:#fff
    style C fill:#2d6a9f,stroke:#1a4971,color:#fff
    style D fill:#2d6a9f,stroke:#1a4971,color:#fff
    style H fill:#2d6a9f,stroke:#1a4971,color:#fff
    style E fill:#2d8659,stroke:#1a5c3a,color:#fff
    style F fill:#2d8659,stroke:#1a5c3a,color:#fff
    style G fill:#2d8659,stroke:#1a5c3a,color:#fff
    style I fill:#2d8659,stroke:#1a5c3a,color:#fff

Features

• Unified Authentication Interface: Standardized API across all providers via IAngularAuthProvider
• Multiple Provider Support: Auth0, Microsoft MSAL (Azure AD), Okta, Cognito, and WorkOS (AuthKit)
• Standardized Types (v3.0.0): StandardUserInfo, StandardAuthToken, StandardAuthError eliminate leaky abstractions
• Semantic Error Classification: AuthErrorType enum replaces provider-specific error checking
• Token Management: ID token retrieval, token info, and automatic refresh
• Observable State: Reactive authentication state, user info, and email streams
• Configuration Validation: Each provider declares and validates its required configuration
• Angular 21+ Compatible: Built for modern Angular applications

Installation

npm install @memberjunction/ng-auth-services

Key Dependencies

| Dependency | Purpose | |---|---| | @angular/core, @angular/common | Angular framework | | @auth0/auth0-angular | Auth0 provider (peer) | | @azure/msal-angular, @azure/msal-browser | MSAL provider (peer) | | @okta/okta-auth-js | Okta provider (peer) | | @workos-inc/authkit-js | WorkOS AuthKit provider (peer) | | @memberjunction/core | Core MJ utilities | | rxjs | Reactive state management |

Configuration

Environment Setup

// Auth0
export const environment = {
  AUTH_TYPE: 'auth0',
  AUTH0_DOMAIN: 'your-domain.auth0.com',
  AUTH0_CLIENTID: 'your-auth0-client-id',
};

// MSAL (Azure AD)
export const environment = {
  AUTH_TYPE: 'msal',
  CLIENT_ID: 'your-azure-ad-client-id',
  CLIENT_AUTHORITY: 'https://login.microsoftonline.com/your-tenant-id',
};

// Okta
export const environment = {
  AUTH_TYPE: 'okta',
  OKTA_ISSUER: 'https://your-org.okta.com/oauth2/default',
  OKTA_CLIENTID: 'your-okta-client-id',
};

// WorkOS (AuthKit)
export const environment = {
  AUTH_TYPE: 'workos',
  WORKOS_CLIENTID: 'client_01H...',
  // optional: WORKOS_REDIRECT_URI, WORKOS_API_HOSTNAME, WORKOS_DEV_MODE
};

WorkOS needs server-side setup too — a JWT Template to add the user's email to the access token (WorkOS omits it by default, and MJ resolves users by email) and matching the aud claim. See the end-to-end WorkOS Integration Guide.

Module Setup

import { AuthServicesModule } from '@memberjunction/ng-auth-services';

@NgModule({
  imports: [
    AuthServicesModule.forRoot(environment),
  ]
})
export class AppModule {}

Usage

Authentication Operations (v3.0.0 API)

import { MJAuthBase, StandardUserInfo } from '@memberjunction/ng-auth-services';

@Component({ selector: 'app-header', template: '...' })
export class HeaderComponent {
  constructor(private authBase: MJAuthBase) {}

  async ngOnInit() {
    // Reactive auth state
    this.authBase.isAuthenticated().subscribe(isAuth => { /* ... */ });

    // Standardized user info
    this.authBase.getUserInfo().subscribe((user: StandardUserInfo | null) => {
      if (user) console.log(`Welcome ${user.name}!`);
    });

    // Token management
    const token = await this.authBase.getIdToken();
    const tokenInfo = await this.authBase.getTokenInfo();
  }

  login() { this.authBase.login(); }
  logout() { this.authBase.logout(); }
}

Error Handling

import { AuthErrorType } from '@memberjunction/ng-auth-services';

try {
  await this.authBase.refreshToken();
} catch (err) {
  const authError = this.authBase.classifyError(err);
  switch (authError.type) {
    case AuthErrorType.TOKEN_EXPIRED:
      // Session expired
      break;
    case AuthErrorType.USER_CANCELLED:
      // User cancelled - no error needed
      break;
    case AuthErrorType.NETWORK_ERROR:
      // Connectivity issue
      break;
  }
}

Exported API

| Export | Type | Description | |---|---|---| | MJAuthBase | Abstract Service | Base authentication service all providers implement | | IAngularAuthProvider | Interface | Contract for authentication providers | | AngularAuthProviderFactory | Factory | Creates provider instances from configuration | | AuthServicesModule | NgModule | Module with forRoot() configuration | | RedirectComponent | Component | Handles OAuth redirect callbacks | | StandardUserInfo | Interface | Standardized user profile data | | StandardAuthToken | Interface | Standardized token information | | StandardAuthError | Interface | Standardized error with classification | | AuthErrorType | Enum | Semantic error categories | | TokenRefreshResult | Interface | Token refresh operation result | | AuthState | Interface | Complete authentication state snapshot |

Build

cd packages/Angular/Explorer/auth-services && npm run build

License

ISC