V3.1.6 (#93)

* Revert back to 3.1.4

* Update NODEJS version to 16_X

* Update schema definitions; ensure emptyValues are handled for sessionDuration and relayState

* Add debug statements

* Fix dependency issue

* Add exist checks for optional attributes

* Add exist checks for create flows as well

* Add enforced wait between pages

* Switch account assignment to S3 interface

* Add Recursive functionality for nested OU's

* Working for part 1 of nested OU, provision to any depth

* Add optional deployment support for nested OU provisioning

* Provide array/string support for resource/action elements in permission sets

* Update notification address

* Turn on nested OU support

* Fix nested OU supported state machine; enable self-sustaining logic for nested OU support

* Fix nested OU supported state machine; enable self-sustaining logic for nested OU support

* Add debug messages for self healing org move logic

* Optimise OU movement logic

* Avoid root processing

* Remove message de-duplicationId for orgEvents

* Add OU traversal up to root

* Working version 3.1.5

* Version 3.1.5

* Update permission set schema to be less restrictive

* Update behaviour of batch processing to handle throttling

* Fix stack dependency such that state machine roles and policies are created prior to state machine; Tune retry and jitter back-off parameters to handle heavier loads

* Remove reservedConcurrency setting as we achieve the same effect through FIFO+messae group ID restriction

* Reduce page size to 1 for debug; remove reservedConcurrency

* Revert page size to 5

* Externalise visibilityTimeout to config parameters

* Working version 3.1.5 for scaling

* Sync with 3.1.5

* Code comments formatting

* named exceptions handling with permission set create update handler

* Retry debugging with spaces in JSON.stringify

* Set message structure to be JSON

* Remove default key

* Configurable logging;externalise function logging to config

* Fix missing imports

* Correct configurable log logic

* Updated permissionSetDeletion logic with improved exception handling

* Update missing parameter for permission set delete function

* Add functionloggingConfig to all lambda environment configs

* Add named exception handling to permissionSetAPI handler

* Added named exception handling for account assignment API interface; formatted loggers

* Re-formatted exception message return for API - permission set

* Add named exception handling to link API handler

* Update linkManager with named exceptions; update waiters for account assignment operations with named exceptions

* Added named exception handling for all core functions

* Version 3.1.6

* Cleanup

* Update case for functionlogMode

bin/aws-sso-extensions-for-enterprise.ts

@@ -4,12 +4,12 @@ import { App, DefaultStackSynthesizer, Tags } from "aws-cdk-lib";
 import { readFileSync } from "fs";
 import { resolve } from "path";
 import { BuildConfig } from "../lib/build/buildConfig";
+import { RegionSwitchBuildConfig } from "../lib/build/regionSwitchBuildConfig";
 import { AwsSsoExtensionsForEnterprise } from "../lib/stacks/pipeline/aws-sso-extensions-for-enterprise";
+import { AwsSsoExtensionsRegionSwitchDeploy } from "../lib/stacks/region-switch/aws-sso-extensions-region-switch-deploy";
+import { AwsSsoExtensionsRegionSwitchDiscover } from "../lib/stacks/region-switch/aws-sso-extensions-region-switch-discover";
 
 import yaml = require("js-yaml");
-import { RegionSwitchBuildConfig } from "../lib/build/regionSwitchBuildConfig";
-import { AwsSsoExtensionsRegionSwitchDiscover } from "../lib/stacks/region-switch/aws-sso-extensions-region-switch-discover";
-import { AwsSsoExtensionsRegionSwitchDeploy } from "../lib/stacks/region-switch/aws-sso-extensions-region-switch-deploy";
 const app = new App();
 
 function ensureString(
@@ -177,6 +177,11 @@ function getConfig() {
         unparsedEnv["Parameters"],
         "SupportNestedOU"
       ),
+      FunctionLogMode: ensureValidString(
+        unparsedEnv["Parameters"],
+        "FunctionLogMode",
+        ["INFO", "WARN", "DEBUG", "EXCEPTION"]
+      ),
     },
   };
 

config/env.yaml

@@ -1,7 +1,7 @@
 ---
 App: "aws-sso-extensions-for-enterprise"
 Environment: "env"
-Version: "3.1.5"
+Version: "3.1.6"
 
 PipelineSettings:
   BootstrapQualifier: "<your-bootstrap-qualifier>" # For example: 'ssoutility'
@@ -28,3 +28,4 @@ Parameters:
   ImportCurrentSSOConfiguration: false # Set this to true if you want the solution to do a one-time import of your current AWS SSO permission sets and account assignments. Refer to "Import existing AWS SSO access entitlements for management through the solution" section under "Features" in README.md for details
   UpgradeFromVersionLessThanV303: false # Should be set to true, if upgrading from solution version 3.0.2/earlier
   SupportNestedOU: false # Set this to true if your preference is for the solution to support nested OU's as part of account assignments. Refer to "Enterprise friendly account assignment life cycle" and "Automated access change management for root, ou_id and account_tag scopes" sections under "Features" in README.md for details
+  FunctionLogMode: "Info" # Used for configuring lambda function logging level. Alowed values - ["Debug","Info","Warn","Exception"]

lib/build/buildConfig.ts

@@ -1,41 +1,63 @@
-/*
-Build parameters interface definition
-To enable easier sharing between constructs and stacks as well as
-synth and deploy validations
-*/
-
+/**
+ * Build parameters inteface Used for validating configuration files at
+ * synthesis time for correctness of data type and data ranges/values
+ */
 export interface BuildConfig {
-  readonly App: string;
-  readonly Environment: string;
-  readonly Version: string;
+  readonly App: string /** Used as prefix for resource and stack names */;
+  readonly Environment: string /** Used as prefix for resource and stack names */;
+  readonly Version: string /** Used for aligning with github version */;
   readonly PipelineSettings: PipelineSettings;
   readonly Parameters: Parameters;
 }
 
+/** Pipeline specific parameters */
 export interface PipelineSettings {
-  readonly BootstrapQualifier: string;
+  readonly BootstrapQualifier: string /** CDK bootstrap qualifier to deploy the solution */;
   readonly DeploymentAccountId: string;
   readonly DeploymentAccountRegion: string;
   readonly TargetAccountId: string;
   readonly TargetAccountRegion: string;
   readonly SSOServiceAccountId: string;
   readonly SSOServiceAccountRegion: string;
   readonly OrgMainAccountId: string;
-  readonly RepoArn: string;
-  readonly RepoBranchName: string;
-  readonly SynthCommand: string;
+  readonly RepoArn: string /** AWS CodeCommit source code repository ARN */;
+  readonly RepoBranchName: string /** AWS CodeCommit source code repository branch */;
+  readonly SynthCommand: string /** CDK synthesise command */;
 }
 
+/** Solution specific parameters */
 export interface Parameters {
-  readonly LinksProvisioningMode: string;
-  readonly PermissionSetProvisioningMode: string;
+  readonly LinksProvisioningMode: string /** Account assignments provisioning mode - accepted values are one of ["api", "s3"] */;
+  readonly PermissionSetProvisioningMode: string /** Permission set provisioning mode - accepted values are one of ["api", "s3"] */;
   readonly LinkCallerRoleArn: string;
+  /**
+   * IAM role arn created in target account with permissions to upload account
+   * assignments to S3/API interfaces
+   */
   readonly PermissionSetCallerRoleArn: string;
-  readonly NotificationEmail: string;
-  readonly AccountAssignmentVisibilityTimeoutHours: number;
+  /**
+   * IAM role arn created in target account with permissions to upload
+   * permission sets to S3/API interfaces
+   */
+  readonly NotificationEmail: string /** Notification email used by solution to send error notifications etc */;
+  readonly AccountAssignmentVisibilityTimeoutHours: number /** Visibility timeout parameter , used for scaling the solution in large enterprises */;
   readonly IsAdUsed: boolean;
   readonly DomainName: string;
   readonly ImportCurrentSSOConfiguration: boolean;
+  /**
+   * Used as switch to do a one-time import of all AWS SSO account assignments
+   * and permission sets into the solution
+   */
   readonly UpgradeFromVersionLessThanV303: boolean;
+  /**
+   * Used as switch to do one-time format upgrade of all the account assignments
+   * that the solution provisioned and persisted in DynamoDB
+   */
   readonly SupportNestedOU: boolean;
+  /**
+   * Used as switch to determine whether OU traversal is parent level only (or)
+   * full tree traversal
+   */
+  readonly FunctionLogMode: string;
+  /** Used as switch to set the level of lambda function logging the solution should use */
 }

lib/build/regionSwitchBuildConfig.ts

@@ -1,11 +1,10 @@
-/*
-Build parameters interface definition
-To enable easier sharing between constructs and stacks as well as
-synth and deploy validations
-*/
+/**
+ * Build parameters inteface Used for validating configuration files at
+ * synthesis time for correctness of data type and data ranges/values
+ */
 
 export interface RegionSwitchBuildConfig {
-  readonly BootstrapQualifier: string;
+  readonly BootstrapQualifier: string /** CDK bootstrap qualifier */;
   readonly SSOServiceAccountId: string;
   readonly SSOServiceAccountRegion: string;
   readonly SSOServiceTargetAccountRegion: string;

lib/constructs/access-manager.ts

@@ -1,8 +1,11 @@
-/*
-All access granting within the solution artefacts stack is consolidated
-here to facilitate easier management and visibility
-*/
-
+/**
+ * This construct manages access entitlements between different resources
+ * created by the solution as part of "Solution-Artefacts" stack in "target"
+ * account Where feasible, access management is centralised in this construct.
+ * Exceptions are when the underlying resources cannot be referenced in the
+ * "Solution-Artefacts" stack, or when managing access entitlements this way
+ * creates circular dependencies
+ */
 import { PolicyStatement } from "aws-cdk-lib/aws-iam";
 import { Construct } from "constructs";
 import { FetchCrossStackValues } from "./fetch-cross-stack-values";
@@ -27,7 +30,10 @@ export class AccessManager extends Construct {
   ) {
     super(scope, id);
 
-    // Link Manager Handler access
+    /**
+     * All required access for account assignment provisioning handler
+     * lib/lambda-functions/application-handlers/linkManager.ts
+     */
     accessManagerProps.FetchCrossStackValues.queuesKey.grantEncryptDecrypt(
       accessManagerProps.LinkProcessor.linkManagerHandler
     );
@@ -64,7 +70,10 @@ export class AccessManager extends Construct {
       })
     );
 
-    // Permission Set Topic Handler access
+    /**
+     * All required access for permission set provisioning handler
+     * lib/lambda-functions/application-handlers/permissionSetTopicProcessor.ts
+     */
     accessManagerProps.FetchCrossStackValues.snsTopicsKey.grantEncryptDecrypt(
       accessManagerProps.PermissionSetProcessor.permissionSetTopicProcessor
     );
@@ -101,7 +110,10 @@ export class AccessManager extends Construct {
       })
     );
 
-    // SSO Group Handler access
+    /**
+     * All required access for self-sustaining flow on AWS SSO group
+     * creation/deletion lib/lambda-functions/application-handlers/groupsCud.ts
+     */
     accessManagerProps.FetchCrossStackValues.queuesKey.grantEncryptDecrypt(
       accessManagerProps.SSOGroupProcessor.ssoGroupHandler
     );
@@ -133,7 +145,10 @@ export class AccessManager extends Construct {
       })
     );
 
-    // SSO User Handler access
+    /**
+     * All required access for self-sustaining flow on AWS SSO user
+     * creation/deletion lib/lambda-functions/application-handlers/usersCud.ts
+     */
     accessManagerProps.FetchCrossStackValues.queuesKey.grantEncryptDecrypt(
       accessManagerProps.SSOGroupProcessor.ssoUserHandler
     );
@@ -167,7 +182,10 @@ export class AccessManager extends Construct {
       })
     );
 
-    // Link topic processor access
+    /**
+     * All required access for account assignment dispatch handler
+     * lib/lambda-functions/application-handlers/linkTopicProcessor.ts
+     */
     accessManagerProps.FetchCrossStackValues.queuesKey.grantEncryptDecrypt(
       accessManagerProps.LinkProcessor.linkTopicProcessor
     );
@@ -201,7 +219,11 @@ export class AccessManager extends Construct {
       })
     );
 
-    // Org Events Handler Access
+    /**
+     * All required access for self-sustaining flow on org events -
+     * CreateAccount, MoveAccount, account tag operations
+     * lib/lambda-functions/application-handlers/orgEvents.ts
+     */
     accessManagerProps.FetchCrossStackValues.queuesKey.grantEncryptDecrypt(
       accessManagerProps.OrgEvents.orgEventsHandler
     );
@@ -239,7 +261,10 @@ export class AccessManager extends Construct {
       })
     );
 
-    // Permission Set Sync Handler access
+    /**
+     * All required access for self-sustaining flow on permission set changes
+     * lib/lambda-functions/application-handlers/permissionSetSync.ts
+     */
     accessManagerProps.FetchCrossStackValues.queuesKey.grantEncryptDecrypt(
       accessManagerProps.PermissionSetProcessor.permissionSetSyncHandler
     );
@@ -271,7 +296,11 @@ export class AccessManager extends Construct {
       })
     );
 
-    //Process Target account SM Listener access
+    /**
+     * All required access for account assignment dispatcher on target account
+     * list discovery
+     * lib/lambda-functions/application-handlers/processTargetAccountSMListener.ts
+     */
     accessManagerProps.FetchCrossStackValues.queuesKey.grantEncryptDecrypt(
       accessManagerProps.LinkProcessor.processTargetAccountSMListenerHandler
     );

lib/constructs/cross-account-role.ts

@@ -1,18 +1,16 @@
-/*
-Cross account role construct that sets
-policy document,assume role account details as received in
-props and also creates a parameter using the SSMParamWriter
-construct and value set to rolearn 
-*/
+/**
+ * Custom CDK construct that enables creating AWS IAM Roles that could be
+ * assumed by cross-account prinicpals. This construct sets the policy document,
+ * assume role account details as received in props and also creates an AWS SSM
+ * parameter with cross-account read access (using SSMParamWriter construct)
+ * with the roleArn value
+ */
 
 import { AccountPrincipal, PolicyStatement, Role } from "aws-cdk-lib/aws-iam";
 import { Construct } from "constructs";
 import { BuildConfig } from "../build/buildConfig";
 import { SSMParamWriter } from "./ssm-param-writer";
-
-function name(buildConfig: BuildConfig, resourcename: string): string {
-  return buildConfig.Environment + "-" + resourcename;
-}
+import { name } from "./helpers";
 
 export interface CrossAccountRoleProps {
   readonly assumeAccountID: string;
@@ -31,6 +29,10 @@ export class CrossAccountRole extends Construct {
   ) {
     super(scope, id);
 
+    /**
+     * Create cross account role with trust policy set to the assuming account
+     * ID principal
+     */
     this.role = new Role(
       this,
       name(buildConfig, `${crossAccountRoleProps.roleNameKey}-role`),
@@ -39,8 +41,13 @@ export class CrossAccountRole extends Construct {
       }
     );
 
+    /** Add the required permissions passed in as part of the construct initiation */
     this.role.addToPrincipalPolicy(crossAccountRoleProps.policyStatement);
 
+    /**
+     * Write the roleArn parameter into SSM enabling the assuming account ID
+     * with read permissions (through custom SSMParamWriter construct)
+     */
     new SSMParamWriter(
       this,
       name(buildConfig, `${crossAccountRoleProps.roleNameKey}-roleArn`),

lib/constructs/fetch-cross-stack-values.ts

@@ -1,10 +1,9 @@
-/*
-Construct to read values from preSolutions
-Artefact stack. This is to avoid creating a circular 
-dependency through CFN exports and instead rely on SSM paramter
-store based reads.
-Used by solutionArtefacts stack.
-*/
+/**
+ * This construct allows read the non-deterministic values of resources created
+ * in preSolutions stack. This is to avoid creating circular dependencies
+ * between preSolutions and Solutions stack through the default CFN exports. We
+ * circumvent that by relying on AWS SSM parameter store based reads
+ */
 
 import { ITable, Table } from "aws-cdk-lib/aws-dynamodb";
 import { IKey, Key } from "aws-cdk-lib/aws-kms";
@@ -265,8 +264,11 @@ export class FetchCrossStackValues extends Construct {
       buildConfig,
       {
         ParamAccountId: buildConfig.PipelineSettings.OrgMainAccountId,
-        ParamRegion: "us-east-1", // Organizations discovery can only be done in us-east-1, hence the step functions and related roles are declared in that region
-        ParamNameKey: "orgListParents-orgapi-roleArn",
+        ParamRegion: "us-east-1",
+        /**
+         * Organizations discovery can only be done in us-east-1, hence the step
+         * functions and related roles are declared in that region
+         */ ParamNameKey: "orgListParents-orgapi-roleArn",
       }
     ).paramValue;
 

lib/constructs/helpers.ts

@@ -0,0 +1,14 @@
+/** All helper utilities used by different constructs */
+
+import { BuildConfig } from "../build/buildConfig";
+
+/**
+ * Environment specific resource naming function
+ *
+ * @param buildConfig
+ * @param resourcename
+ * @returns Environment specific resource name
+ */
+export function name(buildConfig: BuildConfig, resourcename: string): string {
+  return buildConfig.Environment + "-" + resourcename;
+}

lib/constructs/import-artefacts.ts

@@ -1,25 +1,21 @@
-/*
-Construct to read values from solution Artefact and preSolutions
-Artefact stacks. This is to avoid creating a circular 
-dependency through CFN exports and instead rely on SSM paramter
-store based reads.
-Used by ssoImportArtefacts-Part2 stack.
-*/
+/**
+ * This construct allows read the non-deterministic values of resources created
+ * in preSolutions stack. This is to avoid creating circular dependencies
+ * between preSolutions and ssoImportArtefacts-part2 through the default CFN
+ * exports. We circumvent that by relying on AWS SSM parameter store based reads
+ */
 
 import { ITable, Table } from "aws-cdk-lib/aws-dynamodb";
 import { IKey, Key } from "aws-cdk-lib/aws-kms";
 import * as lambda from "aws-cdk-lib/aws-lambda";
-import { ILayerVersion } from "aws-cdk-lib/aws-lambda"; // Importing external resources in CDK would use interfaces and not base objects
+import { ILayerVersion } from "aws-cdk-lib/aws-lambda";
 import { Bucket, IBucket } from "aws-cdk-lib/aws-s3";
-import { ITopic, Topic } from "aws-cdk-lib/aws-sns"; // Importing external resources in CDK would use interfaces and not base objects
+import { ITopic, Topic } from "aws-cdk-lib/aws-sns";
 import { StringParameter } from "aws-cdk-lib/aws-ssm";
 import { Construct } from "constructs";
 import { BuildConfig } from "../build/buildConfig";
 import { SSMParamReader } from "./ssm-param-reader";
-
-function name(buildConfig: BuildConfig, resourcename: string): string {
-  return buildConfig.Environment + "-" + resourcename;
-}
+import { name } from "./helpers";
 
 export class ImportArtefacts extends Construct {
   public readonly nodeJsLayer: ILayerVersion;