adding docs; fixing examples

awslabs · Feb 7, 2024 · fca16c4 · fca16c4
1 parent 1ac8972
commit fca16c4
Show file tree

Hide file tree

Showing 5 changed files with 105 additions and 44 deletions.
diff --git a/framework/API.md b/framework/API.md
diff --git a/framework/src/storage/README.md b/framework/src/storage/README.md
@@ -158,3 +158,27 @@ We provide a simple [data lifecycle management](https://aws.amazon.com/s3/storag
 Change the data lifecycle rules using the DataLakeStorage properties:
 
 [example buckets lifecycle](./examples/data-lake-storage-lifecycle.lit.ts)
+
+[//]: # (storage.opensearch)
+# Opensearch
+
+Amazon Opensearch construct supporting SAML integration using IAM Identity Center. 
+
+## Overview
+
+The construct follows best practises for Amazon Opensearch deployment, provisioning opensearch domain in VPC and using SAML-authentication plugin to access Opensearch Dashboards. 
+By default VPC also creates VPN client endpoint with SAML-authentication to allow secure access to the dashboards. Optionally, you can also provide your own VPC or choose to deploy internet-facing Opensearch domain by setting `deployInVpc=false` in construct parameters.
+
+SAML-authentication can work with any SAML2.0-compatible provider like Okta. If you use AWS IAM Identity center please check the section below for details. The construct require at least admin role to be provided as parameters. 
+
+For mapping additional IdP roles to opensearch dashboard roles, you can use `addRoleMapping` method. 
+
+## Confgiure IAM Identity center
+
+You need to have IAM Identity center enabled in the same region you plan to deploy your solution. 
+To configure SAML integration with opensearch you will need to create a custom SAML 2.0 Application and have at least one user group created and attached to the application.
+Please follow the [step-by-step guidance](https://aws.amazon.com/blogs/big-data/role-based-access-control-in-amazon-opensearch-service-via-saml-integration-with-aws-iam-identity-center/) to set up IAM Identity center SAML application.
+
+## Usage
+
+[example default](examples/opensearch-saml.lit.ts)
diff --git a/framework/src/storage/examples/opensearch-saml.lit.ts b/framework/src/storage/examples/opensearch-saml.lit.ts
@@ -1,42 +1,30 @@
 import * as cdk from 'aws-cdk-lib';
 import { Construct } from 'constructs';
-import { OpensearchProps, OpensearchCluster } from '../lib';
+import { OpensearchProps } from '../lib/opensearch/opensearch-props';
+import { OpensearchCluster } from '../lib/opensearch/opensearch';
 
 class ExampleDefaultOpensearchStack extends cdk.Stack {
 
     constructor(scope: Construct, id: string , props:cdk.StackProps) {
 
         super(scope, id, props);
-        const osCluster = new OpensearchCluster(this, 'MyOpensearchCluster',{
+/// !show
+        const osCluster = new OpensearchCluster(scope, 'MyOpensearchCluster',{
             domainName:"mycluster3",
-            samlEntityId:'https://portal.sso.us-east-1.amazonaws.com/saml/assertion/NDQ0OTc1NjczNTMwX2lucy01MTRmOGNkNGRjYzJhMjky',
-            samlMetadataContent:`<?xml version="1.0" encoding="UTF-8"?><md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" entityID="https://portal.sso.us-east-1.amazonaws.com/saml/assertion/NDQ0OTc1NjczNTMwX2lucy01MTRmOGNkNGRjYzJhMjky">
-            <md:IDPSSODescriptor WantAuthnRequestsSigned="false" protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
-              <md:KeyDescriptor use="signing">
-                <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
-                  <ds:X509Data>
-                    <ds:X509Certificate>MIIDBzCCAe+gAwIBAgIFAJRn/1owDQYJKoZIhvcNAQELBQAwRTEWMBQGA1UEAwwNYW1hem9uYXdzLmNvbTENMAsGA1UECwwESURBUzEPMA0GA1UECgwGQW1hem9uMQswCQYDVQQGEwJVUzAeFw0yNDAxMDMxNDI3MjVaFw0yOTAxMDMxNDI3MjVaMEUxFjAUBgNVBAMMDWFtYXpvbmF3cy5jb20xDTALBgNVBAsMBElEQVMxDzANBgNVBAoMBkFtYXpvbjELMAkGA1UEBhMCVVMwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQC4njhO6vSqfZy+oO3NwUAOiXg/y4053BvSGQIBn/QTiQnSwitQ8gDwnbFs7O65fs+JBEx+L7/4qRkNVGvI9CmF/bCWGqK6OFxUqeA9Ex+8Q42RonnruD+WloniQyDWEs6UR1x+RAFoCFMY28Xvhse1GwV8N+kg20sH3nzHo0Z7B+pRJqflY0/B2dQV8QE/fkJ2EnwLpaxbfsPVYt9pba0GK7xtiXJYzfl4kJ7eb5P0mtNeUHvMZQ786OmykABZVUMLx07po2oMXWxVw0OwoXPj3ijpa4odNRzJt65UAGsqnP45oHYO0FB+GqcVj1Iva2zYcq+4yu1UWXkY/Nf/k2u7AgMBAAEwDQYJKoZIhvcNAQELBQADggEBAEL2rJc6U7vNoq3gMVmfA2U/TqUMq3owcIrpI3YnXBspvKHpXzgHhht3PW1JPujLopszf3/txckzqvysLIlvNV2ZF4ecoHhq7cBkc5/KpR265N8XVJ9JjLV5mCDaDj0PcaRYdiMI0n/PDuHTrUT/WoYxZ29JSBVa0SB8rIJAlB6ffusxs1Kpq3NzewsVe9Jv3c+Y04G4A2NXJ2DZlEzPzAOJYXOLcrd4TVABAIsbU1Oek8UWn70I65Knp8kA/JunwJtpfLwHfH31l8A/yUsjU1+9hSci7O8cqy0+E7Xn+Tif0bE3YUO2kSMc5bkvv+Da4RqzblIQSCi5g2TgWAoNg8o=</ds:X509Certificate>
-                  </ds:X509Data>
-                </ds:KeyInfo>
-              </md:KeyDescriptor>
-              <md:SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://portal.sso.us-east-1.amazonaws.com/saml/logout/NDQ0OTc1NjczNTMwX2lucy01MTRmOGNkNGRjYzJhMjky"/>
-              <md:SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="https://portal.sso.us-east-1.amazonaws.com/saml/logout/NDQ0OTc1NjczNTMwX2lucy01MTRmOGNkNGRjYzJhMjky"/>
-              <md:NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress</md:NameIDFormat>
-              <md:SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://portal.sso.us-east-1.amazonaws.com/saml/assertion/NDQ0OTc1NjczNTMwX2lucy01MTRmOGNkNGRjYzJhMjky"/>
-              <md:SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="https://portal.sso.us-east-1.amazonaws.com/saml/assertion/NDQ0OTc1NjczNTMwX2lucy01MTRmOGNkNGRjYzJhMjky"/>
-            </md:IDPSSODescriptor>
-          </md:EntityDescriptor>`,
-            samlMasterBackendRole:'4478b4b8-d001-7026-61d3-ad652a11b0db',
+            samlEntityId:'<IdpIdentityId>',
+            samlMetadataContent:'<IdpMetadataXml>',
+            samlMasterBackendRole:'<IAMIdentityCenterAdminGroupId>',
             deployInVpc:true,
             removalPolicy:cdk.RemovalPolicy.DESTROY
         } as OpensearchProps);
-        osCluster.addRoleMapping('dashboards_user','testGroupId');
-        osCluster.addRoleMapping('readall','testGroupId');
+        osCluster.addRoleMapping('dashboards_user','<IAMIdentityCenterDashboardUsersGroupId>');
+        osCluster.addRoleMapping('readall','<IAMIdentityCenterDashboardUsersGroupId>');
+/// !hide
     }
 
 
 }
-/// !hide
+
 
 const app = new cdk.App();
 new ExampleDefaultOpensearchStack(app, 'ExampleDefaultDataLakeStorage', { env: {region:'us-east-1'} });
diff --git a/framework/src/storage/lib/opensearch/opensearch.ts b/framework/src/storage/lib/opensearch/opensearch.ts
@@ -20,24 +20,20 @@ import { DsfProvider } from '../../../utils/lib/dsf-provider';
  * ClientVPNEndpoint will be provisioned automatically for secure access to Opnesearch Dashboards.
  *
  * @example
- * class ExampleDefaultOpensearchStack extends cdk.Stack {
  *
- *   constructor(scope: Construct, id: string , props:cdk.StackProps) {
- *    super(scope, id, props);
- *    const osCluster = new OpensearchCluster(this, 'MyOpensearchCluster',{
+ *    const osCluster = new dsf.storage.OpensearchCluster(this, 'MyOpensearchCluster',{
  *      domainName:"mycluster2",
  *      samlEntityId:'<IdpIdentityId>',
- *      samlMetadataContent:'<IdpMetadataXml>'
+ *      samlMetadataContent:'<IdpMetadataXml>',
  *      samlMasterBackendRole:'<IAMIdentityCenterAdminGroupId>',
  *      deployInVpc:true,
  *      removalPolicy:cdk.RemovalPolicy.DESTROY
- *    } as OpensearchProps );
+ *    } as dsf.storage.OpensearchProps );
+ *
  *    osCluster.addRoleMapping('dashboards_user','<IAMIdentityCenterDashboardUsersGroupId>');
  *    osCluster.addRoleMapping('readall','<IAMIdentityCenterDashboardUsersGroupId>');
- *  }
- * }
- * const app = new cdk.App();
- * new ExampleDefaultOpensearchStack(app, 'ExampleDefaultDataLakeStorage', { env: {region:'us-east-1'} });
+ *
+ *
 */
 
 export class OpensearchCluster extends TrackedConstruct {

diff --git a/website/docs/constructs/library/generated/_storage-opensearch.mdx b/website/docs/constructs/library/generated/_storage-opensearch.mdx
@@ -0,0 +1,60 @@
+[//]: # (This file is generated, do not modify directly, update the README.md in framework/src/storage)
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+Amazon Opensearch construct supporting SAML integration using IAM Identity Center. 
+
+## Overview
+
+The construct follows best practises for Amazon Opensearch deployment, provisioning opensearch domain in VPC and using SAML-authentication plugin to access Opensearch Dashboards. 
+By default VPC also creates VPN client endpoint with SAML-authentication to allow secure access to the dashboards. Optionally, you can also provide your own VPC or choose to deploy internet-facing Opensearch domain by setting `deployInVpc=false` in construct parameters.
+
+SAML-authentication can work with any SAML2.0-compatible provider like Okta. If you use AWS IAM Identity center please check the section below for details. The construct require at least admin role to be provided as parameters. 
+
+For mapping additional IdP roles to opensearch dashboard roles, you can use `addRoleMapping` method. 
+
+## Confgiure IAM Identity center
+
+You need to have IAM Identity center enabled in the same region you plan to deploy your solution. 
+To configure SAML integration with opensearch you will need to create a custom SAML 2.0 Application and have at least one user group created and attached to the application.
+Please follow the [step-by-step guidance](https://aws.amazon.com/blogs/big-data/role-based-access-control-in-amazon-opensearch-service-via-saml-integration-with-aws-iam-identity-center/) to set up IAM Identity center SAML application.
+
+## Usage
+
+<Tabs>
+  <TabItem value="typescript" label="TypeScript" default>
+
+  ```typescript
+const osCluster = new OpensearchCluster(scope, 'MyOpensearchCluster',{
+    domainName:"mycluster3",
+    samlEntityId:'<IdpIdentityId>',
+    samlMetadataContent:'<IdpMetadataXml>',
+    samlMasterBackendRole:'<IAMIdentityCenterAdminGroupId>',
+    deployInVpc:true,
+    removalPolicy:cdk.RemovalPolicy.DESTROY
+} as OpensearchProps);
+osCluster.addRoleMapping('dashboards_user','<IAMIdentityCenterDashboardUsersGroupId>');
+osCluster.addRoleMapping('readall','<IAMIdentityCenterDashboardUsersGroupId>');
+  ```
+
+  ```mdx-code-block
+  
+  </TabItem>
+  <TabItem value="python" label="Python">
+
+  ```python
+os_cluster = OpensearchCluster(scope, "MyOpensearchCluster",
+    domain_name="mycluster3",
+    saml_entity_id="<IdpIdentityId>",
+    saml_metadata_content="<IdpMetadataXml>",
+    saml_master_backend_role="<IAMIdentityCenterAdminGroupId>",
+    deploy_in_vpc=True,
+    removal_policy=cdk.RemovalPolicy.DESTROY
+)
+os_cluster.add_role_mapping("dashboards_user", "<IAMIdentityCenterDashboardUsersGroupId>")
+os_cluster.add_role_mapping("readall", "<IAMIdentityCenterDashboardUsersGroupId>")
+  ```
+
+  </TabItem>
+</Tabs>
+