@monocloud/auth-core

!MonoCloud Logo

Introduction

MonoCloud OIDC Client for JavaScript — a standards-compliant OpenID Connect client for secure authentication flows.

MonoCloud is a modern, developer-friendly Identity & Access Management platform.

This package provides a framework-agnostic OpenID Connect (OIDC) client for interacting with MonoCloud. It supports industry-standard authentication flows including Authorization Code Flow, PKCE, Pushed Authorization Requests (PAR), and token lifecycle management.

> This package focuses on core OIDC primitives. Framework-specific integrations (such as Next.js) are provided by higher-level packages built on top of auth-core.

📘 Documentation

- Documentation: https://www.monocloud.com/docs
- API Reference: https://monocloud.github.io/auth-js

Supported Platforms

- Node.js >= 16.0.0 (Requires fetch and Web Crypto API)
- Modern Browsers

Requirements

- A MonoCloud Tenant
- A Client configured as a Web Application or SPA

📦 Installation

``bash
npm install @monocloud/auth-core
`

$3

`typescript
import { MonoCloudOidcClient } from '@monocloud/auth-core';

const oidcClient = new MonoCloudOidcClient(
'https://',
'',
{
// Optional: clientSecret for confidential clients
clientSecret: '',
}
);
`

Usage

$3

Initiate sign-in by generating an authorization URL.

`typescript
import { generateNonce, generateState } from '@monocloud/auth-core/utils';

const authorizeUrl = await oidcClient.authorizationUrl({
redirectUri: '',
scopes: 'openid profile email',
nonce: generateNonce(),
state: generateState(),
});

// Redirect the user to authorizeUrl
`

> Note: state and nonce should always be generated per request and validated on callback to prevent CSRF and token replay attacks.

$3

After authentication, exchange the authorization code for tokens.

`typescript
const session = await oidcClient.authenticate(
'',
'',
'openid profile email'
);

console.log(session.user); // User profile claims
console.log(session.idToken); // Raw ID Token
`

$3

Rotate tokens using the refresh token flow.

`typescript
const refreshedSession = await oidcClient.refreshSession(session);

console.log(refreshedSession);
`

When should I use auth-core?

Use @monocloud/auth-core if you need a low-level, framework-agnostic OpenID Connect client and want full control over the authentication flow.

This package is a good fit if you:

- Are building a custom authentication integration
- Need fine-grained control over redirects, state, nonce, and PKCE
- Are targeting non-framework environments (custom runtimes)
- Are building your own framework adapter or SDK
- Want a pure OIDC client without opinions about routing, cookies, or sessions

Higher-level packages are built on top of auth-core and provide framework-specific ergonomics while reusing the same underlying OIDC implementation.

🤝 Contributing & Support

$3

- Use GitHub Issues for bug reports and feature requests.
- For tenant or account-specific help, contact MonoCloud Support through your dashboard.

$3

Do not report security issues publicly. Please follow the contact instructions at: https://www.monocloud.com/contact

📄 License

Licensed under the MIT License. See the included LICENSE` file.