@drmhse/sso-sdk 0.2.2 → 0.2.4

package/README.md

@@ -146,6 +146,122 @@ localStorage.removeItem('sso_token');
 localStorage.removeItem('sso_refresh_token');
 ```
 
+## Validating Tokens in Your Backend
+
+The SSO platform uses **RS256** (RSA with SHA-256) asymmetric signing for JWTs. This means your backend services can validate JWT signatures without needing access to any shared secrets.
+
+### How It Works
+
+1. **Fetch the JWKS**: The SSO platform exposes a public JWKS (JSON Web Key Set) endpoint at `/.well-known/jwks.json` containing the public RSA key(s).
+2. **Cache the Keys**: Fetch and cache the JWKS in your backend to avoid repeated requests.
+3. **Verify Tokens**: When a client sends a JWT, extract the `kid` (Key ID) from the token header, find the matching key in your cached JWKS, and verify the signature.
+4. **Validate Claims**: After signature verification, validate token claims like `exp` (expiration), `iss` (issuer), and `aud` (audience).
+
+### Node.js/Express Example
+
+Here's a complete example of JWT validation middleware:
+
+```typescript
+import { expressjwt } from 'express-jwt';
+import jwksRsa from 'jwks-rsa';
+
+// Configure JWKS client to fetch public keys
+const jwksClient = jwksRsa({
+  cache: true,
+  rateLimit: true,
+  jwksRequestsPerMinute: 5,
+  jwksUri: 'https://sso.example.com/.well-known/jwks.json'
+});
+
+// Function to get signing key from JWKS
+function getKey(header, callback) {
+  jwksClient.getSigningKey(header.kid, (err, key) => {
+    if (err) {
+      return callback(err);
+    }
+    const signingKey = key.getPublicKey();
+    callback(null, signingKey);
+  });
+}
+
+// JWT validation middleware
+const requireAuth = expressjwt({
+  secret: getKey,
+  algorithms: ['RS256'],
+  credentialsRequired: true,
+  getToken: (req) => {
+    if (req.headers.authorization?.startsWith('Bearer ')) {
+      return req.headers.authorization.substring(7);
+    }
+    return null;
+  }
+});
+
+// Use in your routes
+app.get('/api/protected', requireAuth, (req, res) => {
+  // req.auth contains the decoded JWT claims
+  const { sub, email, org, service } = req.auth;
+  res.json({ message: `Hello ${email}` });
+});
+```
+
+### Manual Validation (Node.js)
+
+If you prefer to validate manually without middleware:
+
+```typescript
+import jwt from 'jsonwebtoken';
+import jwksRsa from 'jwks-rsa';
+
+const jwksClient = jwksRsa({
+  jwksUri: 'https://sso.example.com/.well-known/jwks.json'
+});
+
+async function validateToken(token: string) {
+  try {
+    // Decode without verifying to get the kid
+    const decoded = jwt.decode(token, { complete: true });
+    if (!decoded || !decoded.header.kid) {
+      throw new Error('Invalid token: missing kid');
+    }
+
+    // Get the public key for this kid
+    const key = await jwksClient.getSigningKey(decoded.header.kid);
+    const publicKey = key.getPublicKey();
+
+    // Verify and decode the token
+    const verified = jwt.verify(token, publicKey, {
+      algorithms: ['RS256']
+    });
+
+    return verified; // Returns the decoded claims
+  } catch (error) {
+    console.error('Token validation failed:', error);
+    throw error;
+  }
+}
+
+// Usage
+const claims = await validateToken(req.headers.authorization.split(' ')[1]);
+console.log(claims.email, claims.org, claims.service);
+```
+
+### Other Languages
+
+The same approach works in any language:
+
+- **Python**: Use `PyJWT` with `python-jose` or `jwcrypto`
+- **Go**: Use `golang-jwt/jwt` with JWKS support
+- **Java**: Use `java-jwt` or Spring Security with JWKS
+- **Ruby**: Use `jwt` gem with `jwks-ruby`
+
+The key steps are always the same:
+1. Fetch JWKS from `/.well-known/jwks.json`
+2. Extract `kid` from JWT header
+3. Find matching key in JWKS
+4. Verify signature using the public key
+5. Validate token claims (especially `exp`)
+
 ## API Reference
 
 ### Analytics (`sso.analytics`)
@@ -191,16 +307,27 @@ await sso.organizations.oauthCredentials.set('acme-corp', 'github', {
 
 #### End-User Management (`sso.organizations.endUsers`)
 
-Manage your organization's customers (end-users with subscriptions).
+Manage your organization's customers (end-users who have logged in or have subscriptions).
 
 ```typescript
-// List all end-users for an organization
-const endUsers = await sso.organizations.endUsers.list('acme-corp', {
+// List all end-users across all services
+const allUsers = await sso.organizations.endUsers.list('acme-corp', {
   page: 1,
   limit: 20
 });
 
-// Revoke all active sessions for a specific end-user
+// Filter end-users by a specific service
+const serviceUsers = await sso.organizations.endUsers.list('acme-corp', {
+  service_slug: 'main-app',
+  page: 1,
+  limit: 20
+});
+
+// Get detailed information about a specific end-user
+const user = await sso.organizations.endUsers.get('acme-corp', 'user-id-123');
+console.log(`Active sessions: ${user.session_count}`);
+
+// Revoke all active sessions for a specific end-user (force logout)
 await sso.organizations.endUsers.revokeSessions('acme-corp', 'user-id-123');
 ```
 

package/dist/index.d.mts

@@ -802,6 +802,10 @@ interface EndUserDetailResponse {
  * List end-users query params
  */
 interface ListEndUsersParams extends PaginationParams {
+    /**
+     * Optional service slug to filter users by a specific service
+     */
+    service_slug?: string;
 }
 /**
  * Revoke sessions response
@@ -1314,19 +1318,28 @@ declare class OrganizationsModule {
     endUsers: {
         /**
          * List all end-users for an organization.
-         * End-users are customers who have subscriptions to the organization's services.
+         * Returns users who have identities (logged in) or subscriptions for the organization's services.
          *
          * @param orgSlug Organization slug
-         * @param params Optional query parameters for pagination
-         * @returns Paginated list of end-users with their subscriptions
+         * @param params Optional query parameters for pagination and filtering
+         * @param params.service_slug Optional service slug to filter users by a specific service
+         * @returns Paginated list of end-users with their subscriptions and identities
          *
          * @example
          * ```typescript
-         * const endUsers = await sso.organizations.endUsers.list('acme-corp', {
+         * // List all end-users across all services
+         * const allUsers = await sso.organizations.endUsers.list('acme-corp', {
+         *   page: 1,
+         *   limit: 20
+         * });
+         *
+         * // Filter by specific service
+         * const serviceUsers = await sso.organizations.endUsers.list('acme-corp', {
+         *   service_slug: 'my-app',
          *   page: 1,
          *   limit: 20
          * });
-         * console.log(`Total end-users: ${endUsers.total}`);
+         * console.log(`Total end-users: ${allUsers.total}`);
          * ```
          */
         list: (orgSlug: string, params?: ListEndUsersParams) => Promise<EndUserListResponse>;

package/dist/index.d.ts

@@ -802,6 +802,10 @@ interface EndUserDetailResponse {
  * List end-users query params
  */
 interface ListEndUsersParams extends PaginationParams {
+    /**
+     * Optional service slug to filter users by a specific service
+     */
+    service_slug?: string;
 }
 /**
  * Revoke sessions response
@@ -1314,19 +1318,28 @@ declare class OrganizationsModule {
     endUsers: {
         /**
          * List all end-users for an organization.
-         * End-users are customers who have subscriptions to the organization's services.
+         * Returns users who have identities (logged in) or subscriptions for the organization's services.
          *
          * @param orgSlug Organization slug
-         * @param params Optional query parameters for pagination
-         * @returns Paginated list of end-users with their subscriptions
+         * @param params Optional query parameters for pagination and filtering
+         * @param params.service_slug Optional service slug to filter users by a specific service
+         * @returns Paginated list of end-users with their subscriptions and identities
          *
          * @example
          * ```typescript
-         * const endUsers = await sso.organizations.endUsers.list('acme-corp', {
+         * // List all end-users across all services
+         * const allUsers = await sso.organizations.endUsers.list('acme-corp', {
+         *   page: 1,
+         *   limit: 20
+         * });
+         *
+         * // Filter by specific service
+         * const serviceUsers = await sso.organizations.endUsers.list('acme-corp', {
+         *   service_slug: 'my-app',
          *   page: 1,
          *   limit: 20
          * });
-         * console.log(`Total end-users: ${endUsers.total}`);
+         * console.log(`Total end-users: ${allUsers.total}`);
          * ```
          */
         list: (orgSlug: string, params?: ListEndUsersParams) => Promise<EndUserListResponse>;

package/dist/index.js

@@ -724,19 +724,28 @@ var OrganizationsModule = class {
     this.endUsers = {
       /**
        * List all end-users for an organization.
-       * End-users are customers who have subscriptions to the organization's services.
+       * Returns users who have identities (logged in) or subscriptions for the organization's services.
        *
        * @param orgSlug Organization slug
-       * @param params Optional query parameters for pagination
-       * @returns Paginated list of end-users with their subscriptions
+       * @param params Optional query parameters for pagination and filtering
+       * @param params.service_slug Optional service slug to filter users by a specific service
+       * @returns Paginated list of end-users with their subscriptions and identities
        *
        * @example
        * ```typescript
-       * const endUsers = await sso.organizations.endUsers.list('acme-corp', {
+       * // List all end-users across all services
+       * const allUsers = await sso.organizations.endUsers.list('acme-corp', {
        *   page: 1,
        *   limit: 20
        * });
-       * console.log(`Total end-users: ${endUsers.total}`);
+       * 
+       * // Filter by specific service
+       * const serviceUsers = await sso.organizations.endUsers.list('acme-corp', {
+       *   service_slug: 'my-app',
+       *   page: 1,
+       *   limit: 20
+       * });
+       * console.log(`Total end-users: ${allUsers.total}`);
        * ```
        */
       list: async (orgSlug, params) => {

package/dist/index.mjs

@@ -691,19 +691,28 @@ var OrganizationsModule = class {
     this.endUsers = {
       /**
        * List all end-users for an organization.
-       * End-users are customers who have subscriptions to the organization's services.
+       * Returns users who have identities (logged in) or subscriptions for the organization's services.
        *
        * @param orgSlug Organization slug
-       * @param params Optional query parameters for pagination
-       * @returns Paginated list of end-users with their subscriptions
+       * @param params Optional query parameters for pagination and filtering
+       * @param params.service_slug Optional service slug to filter users by a specific service
+       * @returns Paginated list of end-users with their subscriptions and identities
        *
        * @example
        * ```typescript
-       * const endUsers = await sso.organizations.endUsers.list('acme-corp', {
+       * // List all end-users across all services
+       * const allUsers = await sso.organizations.endUsers.list('acme-corp', {
        *   page: 1,
        *   limit: 20
        * });
-       * console.log(`Total end-users: ${endUsers.total}`);
+       * 
+       * // Filter by specific service
+       * const serviceUsers = await sso.organizations.endUsers.list('acme-corp', {
+       *   service_slug: 'my-app',
+       *   page: 1,
+       *   limit: 20
+       * });
+       * console.log(`Total end-users: ${allUsers.total}`);
        * ```
        */
       list: async (orgSlug, params) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drmhse/sso-sdk",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "description": "Zero-dependency TypeScript SDK for the multi-tenant SSO Platform API",
   "main": "dist/index.js",
   "module": "dist/index.mjs",