@maccuaa/intellitrust-auth-sdk
Version:
TypeScript SDK client for Entrust Identity as a Service Authentication API
363 lines (293 loc) âĒ 8.38 kB
Markdown
# @maccuaa/intellitrust-auth-sdk
[](https://www.npmjs.com/package/@maccuaa/intellitrust-auth-sdk)
[](https://www.npmjs.com/package/@maccuaa/intellitrust-auth-sdk)
TypeScript SDK for the Entrust Identity as a Service (IDaaS) Authentication API.
> **Note**: This is an unofficial community-maintained SDK, not an official Entrust product.
## Features
- ðŊ **Fully Typed**: Complete TypeScript definitions for all API operations
- ð **Modern ESM**: Built for modern JavaScript environments
- ðĶ **Tree-shakeable**: Import only the functions you need
- ð **Type-safe**: Discriminated union types for response handling
- ðŠķ **Lightweight**: Minimal runtime dependencies
## Installation
```bash
npm install @maccuaa/intellitrust-auth-sdk
```
```bash
bun add @maccuaa/intellitrust-auth-sdk
```
## Quick Start
```typescript
import {
userChallengeUsingPost,
userAuthenticateUsingPost,
} from "@maccuaa/intellitrust-auth-sdk";
const baseUrl = "https://customer.region.trustedauth.com";
// Step 1: Request authentication challenge
const challengeResponse = await userChallengeUsingPost(
{
authenticator: "TOKEN",
userChallengeParameters: {
userId: "john.doe",
applicationId: "app-id",
},
},
{ baseUrl }
);
if (challengeResponse.status === 200) {
const authToken = challengeResponse.data.token;
// Step 2: Complete authentication with OTP
const authResponse = await userAuthenticateUsingPost(
{
authenticator: "TOKEN",
authorization: authToken,
userAuthenticateParameters: {
userId: "john.doe",
applicationId: "app-id",
response: "123456", // OTP code
},
},
{ baseUrl }
);
if (
authResponse.status === 200 &&
authResponse.data.authenticationCompleted
) {
console.log("Authentication successful!");
}
}
```
## Response Handling
The SDK uses discriminated union types for type-safe response handling:
```typescript
const response = await userAuthenticatorQueryUsingPost(
{
userAuthenticateQueryParameters: {
userId: "john.doe",
applicationId: "app-id",
},
},
{ baseUrl }
);
// Type guard with status check
if (response.status === 200) {
// response.data is now typed as UserAuthenticateQueryResponse
console.log("User authenticators:", response.data.authenticators);
} else if (response.status === 404) {
// response.data is now typed as ErrorInfo
console.log("Error:", response.data.errorMessage);
}
```
## Configuration
### Global Defaults
Set default options for all requests:
```typescript
import { defaults } from "@maccuaa/intellitrust-auth-sdk";
defaults.baseUrl = "https://customer.region.trustedauth.com";
// Now you can call functions without specifying baseUrl each time
const response = await userAuthenticatorQueryUsingPost({
userAuthenticateQueryParameters: {
userId: "john.doe",
applicationId: "app-id",
},
});
```
### Per-Request Options
Override defaults for individual requests:
```typescript
const response = await userAuthenticateUsingPost(
{
authenticator: "PASSWORD",
userAuthenticateParameters: {
userId: "john.doe",
applicationId: "app-id",
response: "password123",
},
},
{
baseUrl: "https://different.trustedauth.com",
headers: { "Custom-Header": "value" },
}
);
```
## Authentication Flows
### Token (OTP) Authentication
```typescript
import {
userChallengeUsingPost,
userAuthenticateUsingPost,
} from "@maccuaa/intellitrust-auth-sdk";
// Request challenge
const challenge = await userChallengeUsingPost(
{
authenticator: "TOKEN",
userChallengeParameters: {
userId: "user@example.com",
applicationId: "app-id",
},
},
{ baseUrl }
);
if (challenge.status === 200) {
// Complete authentication with OTP
const auth = await userAuthenticateUsingPost(
{
authenticator: "TOKEN",
authorization: challenge.data.token,
userAuthenticateParameters: {
userId: "user@example.com",
applicationId: "app-id",
response: "123456",
},
},
{ baseUrl }
);
}
```
### Password Authentication
```typescript
const response = await userAuthenticateUsingPost(
{
authenticator: "PASSWORD",
userAuthenticateParameters: {
userId: "user@example.com",
applicationId: "app-id",
response: "securePassword123",
},
},
{ baseUrl }
);
if (response.status === 200 && response.data.authenticationCompleted) {
console.log("Login successful");
}
```
### FIDO Authentication
```typescript
import {
userChallengeUsingPost,
userAuthenticateUsingPost,
} from "@maccuaa/intellitrust-auth-sdk";
// Request FIDO challenge
const challenge = await userChallengeUsingPost(
{
authenticator: "FIDO",
userChallengeParameters: {
userId: "user@example.com",
applicationId: "app-id",
},
},
{ baseUrl }
);
if (challenge.status === 200 && challenge.data.fido) {
// Process FIDO challenge and get credential response
const fidoResponse = {
authenticatorData: "...",
clientDataJSON: "...",
credentialId: "...",
signature: "...",
};
// Complete FIDO authentication
const auth = await userAuthenticateUsingPost(
{
authenticator: "FIDO",
authorization: challenge.data.token,
userAuthenticateParameters: {
userId: "user@example.com",
applicationId: "app-id",
fido: fidoResponse,
},
},
{ baseUrl }
);
}
```
### Query Available Authenticators
```typescript
import { userAuthenticatorQueryUsingPost } from "@maccuaa/intellitrust-auth-sdk";
const response = await userAuthenticatorQueryUsingPost(
{
userAuthenticateQueryParameters: {
userId: "user@example.com",
applicationId: "app-id",
},
},
{ baseUrl }
);
if (response.status === 200) {
console.log("Available authenticators:", response.data.authenticators);
}
```
## FIDO Token Management
### Register FIDO Token
```typescript
import {
startFidoRegisterUsingGet,
completeFidoRegisterUsingPost,
} from "@maccuaa/intellitrust-auth-sdk";
// Start FIDO registration
const startResponse = await startFidoRegisterUsingGet({ baseUrl });
if (startResponse.status === 200) {
const challenge = startResponse.data;
// Process challenge with WebAuthn API and get credential
const credential = {
attestationObject: "...",
clientDataJSON: "...",
};
// Complete registration
const completeResponse = await completeFidoRegisterUsingPost(
{
fidoRegisterResponse: credential,
},
{ baseUrl }
);
if (completeResponse.status === 200) {
console.log("FIDO token registered:", completeResponse.data);
}
}
```
### Manage FIDO Tokens
```typescript
import {
getSelfFidoTokenUsingGet,
updateSelfFidoTokenUsingPut,
deleteSelfFidoTokenUsingDelete,
} from "@maccuaa/intellitrust-auth-sdk";
// Get token details
const token = await getSelfFidoTokenUsingGet(
{ tokenid: "token-id" },
{ baseUrl }
);
// Update token
await updateSelfFidoTokenUsingPut(
{
tokenid: "token-id",
fidoTokenParms: { label: "My Security Key" },
},
{ baseUrl }
);
// Delete token
await deleteSelfFidoTokenUsingDelete({ tokenid: "token-id" }, { baseUrl });
```
## Supported Authenticators
- `PASSWORD` - Password authentication
- `TOKEN` - OTP tokens (soft tokens, hardware tokens)
- `FIDO` - FIDO/WebAuthn
- `PASSKEY` - Passkeys
- `MACHINE` - Device authentication
- `GRID` - Grid card authentication
- `KBA` - Knowledge-based authentication
- `OTP` - One-time passwords
- `EXTERNAL` - External identity provider
- `IDP` - Identity provider
- `USER_CERTIFICATE` - Certificate-based authentication
- And more...
## API Documentation
For detailed API documentation, refer to the official [Entrust IDaaS Authentication API documentation](https://entrust.us.trustedauth.com/help/developer/apis/authentication/openapi/).
## Requirements
- Node.js >= 22.12.0
- TypeScript >= 5.0 (for TypeScript projects)
## License
ISC
## Support
This is a community-maintained SDK. For issues or feature requests, please visit the [GitHub repository](https://github.com/maccuaa/intellitrust-js-sdk).
For official Entrust IDaaS support, contact Entrust directly.