@axinom/mosaic-id-guard 0.16.3-rc.8 → 0.17.0-rc.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@axinom/mosaic-id-guard",
-  "version": "0.16.3-rc.8",
+  "version": "0.17.0-rc.0",
   "description": "Authentication and authorization helpers for Axinom Mosaic services",
   "author": "Axinom",
   "license": "PROPRIETARY",
@@ -10,7 +10,8 @@
     "axinom mosaic"
   ],
   "files": [
-    "dist"
+    "dist",
+    "src"
   ],
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -27,9 +28,9 @@
     "lint": "eslint . --ext .ts,.tsx,.js --color --cache"
   },
   "dependencies": {
-    "@axinom/mosaic-id-utils": "^0.10.3-rc.8",
-    "@axinom/mosaic-message-bus": "^0.11.3-rc.8",
-    "@axinom/mosaic-service-common": "^0.27.0-rc.6",
+    "@axinom/mosaic-id-utils": "^0.11.0-rc.0",
+    "@axinom/mosaic-message-bus": "^0.12.0-rc.0",
+    "@axinom/mosaic-service-common": "^0.27.0-rc.11",
     "amqplib": "^0.6.0",
     "express": "^4.17.1",
     "express-bearer-token": "^2.4.0",
@@ -60,5 +61,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "39b4147fb00b4c9500e37effef1ac7b8fb43797f"
+  "gitHead": "140f827280ea9616400d5f6d2f770a0911ebf0e2"
 }

package/src/common/deprecated/error-code.ts

@@ -0,0 +1,23 @@
+/**
+ * @deprecated Please use `IdGuardErrors` instead, e.g.
+ * ```ts
+ * import { IdGuardErrors } from '@axinom/mosaic-id-guard';
+ *
+ * console.log(IdGuardErrors.AccessTokenRequired.code);
+ * ```
+ *
+ * This is only guaranteed to stay until the end of October 2022.
+ */
+export enum ErrorCode {
+  AccessTokenInvalid = 'ACCESS_TOKEN_INVALID',
+  UserNotAuthorized = 'USER_NOT_AUTHORIZED',
+  MalformedToken = 'MALFORMED_TOKEN',
+  AccessTokenExpired = 'ACCESS_TOKEN_EXPIRED',
+  SigningKeyNotFound = 'SIGNING_KEY_NOT_FOUND',
+  JwksError = 'JWKS_ERROR',
+  AccessTokenVerificationFailed = 'ACCESS_TOKEN_VERIFICATION_FAILED',
+  AuthConfigInvalid = 'AUTH_CONFIG_INVALID',
+  AccessTokenRequired = 'ACCESS_TOKEN_REQUIRED',
+  IdentityServiceNotAccessible = 'IDENTITY_SERVICE_NOT_ACCESSIBLE',
+  UserServiceNotAccessible = 'USER_SERVICE_NOT_ACCESSIBLE',
+}

package/src/common/deprecated/index.ts

@@ -0,0 +1 @@
+export * from './error-code';

package/src/common/get-authenticated-subject.spec.ts

@@ -0,0 +1,261 @@
+import { TokenExpiredError } from 'jsonwebtoken';
+import createJWKSMock from 'mock-jwks';
+import {
+  createTestEndUserApplication,
+  createTestUser,
+} from '../tests/test-utils';
+import {
+  EMBEDDED_END_USER_TOKEN_KEY,
+  getAuthenticatedEndUser,
+  getAuthenticatedManagementSubject,
+} from './get-authenticated-subject';
+import { TOKEN_ISSUER_USER_SERVICE } from './jwt-verify-options';
+import { SubjectType } from './subject-type';
+import { AuthenticationConfig } from './types';
+
+const authEndpoint = 'https://AUTH_ENDPOINT_URL';
+
+describe('getAuthenticatedManagementSubject method --> managed service accounts', () => {
+  const jwks = createJWKSMock(authEndpoint);
+
+  beforeEach(() => {
+    jwks.start();
+  });
+
+  afterEach(async () => {
+    await jwks.stop();
+  });
+
+  it('should verify managed service account tokens', async () => {
+    const user = createTestUser({
+      subjectType: SubjectType.ManagedServiceAccount,
+    });
+    const token = jwks.token(user);
+
+    const result = await getAuthenticatedManagementSubject(token, authEndpoint);
+    expect(result).toEqual(user);
+  });
+});
+
+describe('getAuthenticatedManagementSubject method', () => {
+  const tenantId = '27aa1b27-3441-4115-84aa-1ed5f3072248';
+  const environmentId = '83bfce33-61b1-4ec5-93d5-ad40e4ed33c9';
+  const jwks = createJWKSMock(
+    authEndpoint,
+    `/${tenantId}/${environmentId}/.well-known/jwks.json`,
+  );
+
+  beforeEach(() => {
+    jwks.start();
+  });
+
+  afterEach(async () => {
+    await jwks.stop();
+  });
+
+  it('should verify tokens', async () => {
+    const user = createTestUser();
+    const token = jwks.token(user);
+    const config: AuthenticationConfig = {
+      authEndpoint,
+      tenantId,
+      environmentId,
+    };
+
+    const result = await getAuthenticatedManagementSubject(token, config);
+    expect(result).toEqual(user);
+  });
+
+  it('should handle token expiry', async () => {
+    const user = createTestUser({
+      exp: 0,
+    });
+    const token = jwks.token(user);
+    const config: AuthenticationConfig = {
+      authEndpoint,
+      tenantId,
+      environmentId,
+    };
+
+    await expect(
+      getAuthenticatedManagementSubject(token, config),
+    ).rejects.toThrow(TokenExpiredError);
+  });
+});
+
+describe('getEndUserApplication method', () => {
+  const tenantId = '27aa1b27-3441-4115-84aa-1ed5f3072248';
+  const environmentId = '83bfce33-61b1-4ec5-93d5-ad40e4ed33c9';
+  const applicationId = 'd2f708a9-8c71-4db7-9c09-a84147d2e1c5';
+
+  const jwks = createJWKSMock(
+    authEndpoint,
+    `/${tenantId}/${environmentId}/${applicationId}/.well-known/jwks.json`,
+  );
+
+  beforeEach(() => {
+    jwks.start();
+  });
+
+  afterEach(async () => {
+    await jwks.stop();
+  });
+  it('should verify an end-user application token', async () => {
+    const endUserApplication = createTestEndUserApplication();
+    const token = jwks.token(endUserApplication);
+    const config: AuthenticationConfig = {
+      authEndpoint,
+      tenantId,
+      environmentId,
+    };
+
+    const result = await getAuthenticatedEndUser(token, config);
+    expect(result).toEqual(endUserApplication);
+  });
+});
+
+describe('getAuthenticatedEndUser', () => {
+  const tenantId = '27aa1b27-3441-4115-84aa-1ed5f3072248';
+  const environmentId = '83bfce33-61b1-4ec5-93d5-ad40e4ed33c9';
+  const applicationId = '0a0857af-9d3a-4d39-96c9-f0f15fbaecdf';
+
+  const jwks = createJWKSMock(
+    authEndpoint,
+    `/${tenantId}/${environmentId}/${applicationId}/.well-known/jwks.json`,
+  );
+
+  beforeEach(() => {
+    jwks.start();
+  });
+
+  afterEach(async () => {
+    await jwks.stop();
+  });
+
+  it('should verify tokens', async () => {
+    const endUser = createTestUser({
+      applicationId,
+      subjectType: SubjectType.EndUserAccount,
+      iss: TOKEN_ISSUER_USER_SERVICE,
+    });
+    const token = jwks.token(endUser);
+
+    const config: AuthenticationConfig = {
+      authEndpoint,
+      tenantId,
+      environmentId,
+    };
+
+    const result = await getAuthenticatedEndUser(token, config);
+
+    expect(result).toEqual(endUser);
+  });
+
+  it('should handle token expiry', async () => {
+    const endUser = createTestUser({
+      exp: 0,
+      applicationId,
+      subjectType: SubjectType.EndUserAccount,
+      iss: TOKEN_ISSUER_USER_SERVICE,
+    });
+    const token = jwks.token(endUser);
+    const config: AuthenticationConfig = {
+      authEndpoint,
+      tenantId,
+      environmentId,
+    };
+
+    await expect(getAuthenticatedEndUser(token, config)).rejects.toThrow(
+      TokenExpiredError,
+    );
+  });
+
+  it('When a JWT with the property mosaic.end-user.accessToken is passed with the value having a valid end-user access token, it should be successfully verified', async () => {
+    // Arrange
+    const config: AuthenticationConfig = {
+      authEndpoint,
+      tenantId,
+      environmentId,
+    };
+    const endUser = createTestUser({
+      applicationId,
+      subjectType: SubjectType.EndUserAccount,
+      iss: TOKEN_ISSUER_USER_SERVICE,
+    });
+    const endUserJwt = jwks.token(endUser);
+    const tokenPayloadWithEmbeddedJwt = {
+      sub: '1234567890',
+      name: 'Jonas Khanwald',
+      iat: 1646631810,
+      exp: 2046635410,
+      [EMBEDDED_END_USER_TOKEN_KEY]: endUserJwt,
+    };
+    const embeddedJwt = jwks.token(tokenPayloadWithEmbeddedJwt);
+
+    // Act
+    const authenticatedEndUser = await getAuthenticatedEndUser(
+      embeddedJwt,
+      config,
+    );
+
+    // Assert
+    expect(authenticatedEndUser).toEqual(endUser);
+  });
+
+  it.each([
+    jwks.token({
+      sub: '1234567890',
+      name: 'John Doe',
+      iat: 1646631810,
+      exp: 2046635410,
+    }),
+    'inavlid-token-that-is-not-even-a-jwt',
+  ])(
+    'When a JWT with the property mosaic.end-user.accessToken is passed, but the JWT is not a valid token Mosaic End-User Token, an error is raised',
+    async (invalidEmbeddedJwt) => {
+      // Arrange
+      const config: AuthenticationConfig = {
+        authEndpoint,
+        tenantId,
+        environmentId,
+      };
+      const tokenPayloadWithEmbeddedJwt = {
+        sub: '1234567890',
+        name: 'Jonas Khanwald',
+        iat: 1646631810,
+        exp: 2046635410,
+        [EMBEDDED_END_USER_TOKEN_KEY]: invalidEmbeddedJwt,
+      };
+      const embeddedJwt = jwks.token(tokenPayloadWithEmbeddedJwt);
+
+      // Act and Assert
+      await expect(
+        getAuthenticatedEndUser(embeddedJwt, config),
+      ).rejects.toThrow(
+        'Passed JWT is not a Mosaic End-User Token. Cannot be verified.',
+      );
+    },
+  );
+
+  it('When a JWT that is not an End-User Access Token is passed, an error is raised', async () => {
+    // Arrange
+    const config: AuthenticationConfig = {
+      authEndpoint,
+      tenantId,
+      environmentId,
+    };
+
+    const tokenPayloadWithEmbeddedJwt = {
+      sub: '1234567890',
+      name: 'Jonas Khanwald',
+      iat: 1646631810,
+      exp: 2046635410,
+    };
+    const embeddedJwt = jwks.token(tokenPayloadWithEmbeddedJwt);
+
+    // Act and Assert
+    await expect(getAuthenticatedEndUser(embeddedJwt, config)).rejects.toThrow(
+      'Passed JWT is not a Mosaic End-User Token. Cannot be verified.',
+    );
+  });
+});

package/src/common/get-authenticated-subject.ts

@@ -0,0 +1,222 @@
+import { isNullOrWhitespace } from '@axinom/mosaic-service-common';
+import jwt from 'jsonwebtoken';
+import jwks from 'jwks-rsa';
+import { IdGuardError } from './id-guard-error';
+import { IdGuardErrors } from './id-guard-errors';
+import {
+  getJwtVerifyOptions,
+  TOKEN_ISSUER_ID_SERVICE,
+  TOKEN_ISSUER_USER_SERVICE,
+} from './jwt-verify-options';
+import { SubjectType } from './subject-type';
+import {
+  AuthenticatedEndUser,
+  AuthenticatedEndUserApplication,
+  AuthenticatedManagementSubject,
+  AuthenticationConfig,
+} from './types';
+
+export const EMBEDDED_END_USER_TOKEN_KEY = 'mosaic.end-user.accessToken';
+
+/**
+ * Parses a JWT token to produce an `AuthenticatedManagementSubject`.
+ * This function is intended to be used by any service which works with the Mosaic Management System.
+ *
+ * @param {string} token JWT token without `Bearer ` prefix
+ * @param {string | AuthenticationConfig} authParams This could be either a string containing the Auth Endpoint for the ID Service or an instance of `AuthenticationConfig`.
+ * @returns {Promise<AuthenticatedManagementSubject>} AuthenticatedManagementSubject
+ */
+export const getAuthenticatedManagementSubject = async (
+  token: string,
+  authParams: string | AuthenticationConfig,
+): Promise<AuthenticatedManagementSubject> => {
+  let tenantId = '';
+  let environmentId = '';
+  let isManagedServiceAccount = false;
+  let jwksUri = '';
+
+  const decoded = jwt.decode(token) as AuthenticatedManagementSubject;
+  const issuer = decoded.iss;
+
+  // Tenant ID and Environment ID should be decoded from the token
+  tenantId = decoded.tenantId;
+  environmentId = decoded.environmentId;
+  isManagedServiceAccount =
+    decoded.subjectType === SubjectType.ManagedServiceAccount;
+
+  // If token is not issued by the ID Service, the jwks URI will not be set, and the verification will fail.
+  if (issuer === TOKEN_ISSUER_ID_SERVICE) {
+    if (typeof authParams === 'string') {
+      if (isManagedServiceAccount) {
+        jwksUri = new URL(`/.well-known/jwks.json`, authParams).href;
+      } else {
+        jwksUri = new URL(
+          `/${tenantId}/${environmentId}/.well-known/jwks.json`,
+          authParams,
+        ).href;
+      }
+    } else {
+      // TODO: Refactor this to support AuthenticationConfig with mandatory values.
+      if (
+        !isNullOrWhitespace(authParams.tenantId) &&
+        !isNullOrWhitespace(authParams.environmentId)
+      ) {
+        tenantId = authParams.tenantId;
+        environmentId = authParams.environmentId;
+      }
+
+      if (isManagedServiceAccount) {
+        jwksUri = new URL(`/.well-known/jwks.json`, authParams.authEndpoint)
+          .href;
+      } else {
+        jwksUri = new URL(
+          `/${tenantId}/${environmentId}/.well-known/jwks.json`,
+          authParams.authEndpoint,
+        ).href;
+      }
+    }
+  }
+
+  // Verify access token using JWKS
+  return (await verifyTokenAndGetAuthenticatedSubject(
+    token,
+    jwksUri,
+    'MANAGEMENT',
+  )) as AuthenticatedManagementSubject;
+};
+
+/**
+ * Parses a JWT token to produce an `AuthenticatedEndUser` or an `AuthenticatedEndUserApplication`.
+ * This function is intended to be used by any service which works with End-User Applications.
+ *
+ * @param {string} token JWT token without `Bearer ` prefix.
+ * @param {string | AuthenticationConfig} authParams This could be either a string containing the Auth Endpoint for the User Service or an instance of `AuthenticationConfig`.
+ * @returns {Promise<AuthenticatedEndUser | AuthenticatedEndUserApplication>} AuthenticatedEndUser/AuthenticatedEndUserApplication
+ */
+export const getAuthenticatedEndUser = async (
+  token: string,
+  authParams: string | AuthenticationConfig,
+): Promise<AuthenticatedEndUser | AuthenticatedEndUserApplication> => {
+  let tenantId = '';
+  let environmentId = '';
+  let jwksUri = '';
+  let endUserToken = '';
+
+  const decodedToken = jwt.decode(token) as Record<string, unknown>;
+
+  // Handle embedded end-user token.
+  if (decodedToken[EMBEDDED_END_USER_TOKEN_KEY] !== undefined) {
+    endUserToken = String(decodedToken[EMBEDDED_END_USER_TOKEN_KEY]);
+  } else {
+    endUserToken = token;
+  }
+
+  const decodedEndUserToken = jwt.decode(
+    endUserToken,
+  ) as AuthenticatedEndUserApplication;
+
+  // There can be a chance the token passed through `mosaic.end-user.accessToken` is not a valid JWT. (i.e. a simple string)
+  if (isNullOrWhitespace(decodedEndUserToken)) {
+    throw new IdGuardError(IdGuardErrors.JwtIsNotMosaicEndUserToken);
+  }
+  const issuer = decodedEndUserToken.iss;
+  tenantId = decodedEndUserToken.tenantId;
+  environmentId = decodedEndUserToken.environmentId;
+  const applicationId = decodedEndUserToken.applicationId;
+
+  // If token is not issued by the User Service, the jwks URI will not be set, and the verification will fail.
+  if (issuer === TOKEN_ISSUER_USER_SERVICE) {
+    if (typeof authParams === 'string') {
+      jwksUri = new URL(
+        `/${tenantId}/${environmentId}/${applicationId}/.well-known/jwks.json`,
+        authParams,
+      ).href;
+    } else {
+      // TODO: Refactor this to support AuthenticationConfig with mandatory values.
+      if (
+        !isNullOrWhitespace(authParams.tenantId) &&
+        !isNullOrWhitespace(authParams.environmentId)
+      ) {
+        tenantId = authParams.tenantId;
+        environmentId = authParams.environmentId;
+      }
+
+      jwksUri = new URL(
+        `/${tenantId}/${environmentId}/${applicationId}/.well-known/jwks.json`,
+        authParams.authEndpoint,
+      ).href;
+    }
+  }
+
+  if (decodedEndUserToken.subjectType === SubjectType.EndUserApplication) {
+    // Verify access token using JWKS
+    return (await verifyTokenAndGetAuthenticatedSubject(
+      endUserToken,
+      jwksUri,
+      'END_USER_APPLICATION',
+    )) as AuthenticatedEndUserApplication;
+  } else if (decodedEndUserToken.subjectType === SubjectType.EndUserAccount) {
+    // Verify access token using JWKS
+    return (await verifyTokenAndGetAuthenticatedSubject(
+      endUserToken,
+      jwksUri,
+      'END_USER',
+    )) as AuthenticatedEndUser;
+  } else {
+    throw new IdGuardError(IdGuardErrors.JwtIsNotMosaicEndUserToken);
+  }
+};
+
+const verifyTokenAndGetAuthenticatedSubject = async (
+  token: string,
+  jwksUri: string,
+  authType: 'MANAGEMENT' | 'END_USER' | 'END_USER_APPLICATION',
+): Promise<
+  | AuthenticatedManagementSubject
+  | AuthenticatedEndUser
+  | AuthenticatedEndUserApplication
+> => {
+  return new Promise<
+    | AuthenticatedManagementSubject
+    | AuthenticatedEndUser
+    | AuthenticatedEndUserApplication
+  >((resolve, reject) => {
+    const jwksClient = jwks({
+      jwksUri,
+      cache: true,
+      cacheMaxAge: 1000 * 60 * 10, // 10 Minutes (same as access token lifetime)
+      cacheMaxEntries: 100,
+    });
+
+    const getPublicKey: jwt.GetPublicKeyOrSecret = (
+      header: jwt.JwtHeader,
+      callback: jwt.SigningKeyCallback,
+    ): void => {
+      jwksClient.getSigningKey(
+        header.kid ?? 'MISSING_KEY_ID_IN_JWT_HEADER',
+        (error: Error | null, key: jwks.SigningKey) => {
+          if (error) {
+            reject(error);
+            return;
+          }
+          callback(null, key.getPublicKey());
+        },
+      );
+    };
+
+    jwt.verify(token, getPublicKey, getJwtVerifyOptions(), (error, decoded) => {
+      if (error) {
+        reject(error);
+        return;
+      }
+
+      if (authType === 'MANAGEMENT') {
+        resolve(decoded as AuthenticatedManagementSubject);
+      } else if (authType === 'END_USER') {
+        resolve(decoded as AuthenticatedEndUser);
+      } else {
+        resolve(decoded as AuthenticatedEndUserApplication);
+      }
+    });
+  });
+};