From fca16c466381fc5b25b4413d5ce47ffc7e24afb2 Mon Sep 17 00:00:00 2001 From: Alex Tarasov Date: Wed, 24 Jan 2024 16:54:20 +0000 Subject: [PATCH] adding docs; fixing examples --- framework/API.md | 15 ++--- framework/src/storage/README.md | 24 ++++++++ .../storage/examples/opensearch-saml.lit.ts | 34 ++++------- .../src/storage/lib/opensearch/opensearch.ts | 16 ++--- .../library/generated/_storage-opensearch.mdx | 60 +++++++++++++++++++ 5 files changed, 105 insertions(+), 44 deletions(-) create mode 100644 website/docs/constructs/library/generated/_storage-opensearch.mdx diff --git a/framework/API.md b/framework/API.md index acb615b8c..0cd859188 100644 --- a/framework/API.md +++ b/framework/API.md @@ -3596,24 +3596,17 @@ ClientVPNEndpoint will be provisioned automatically for secure access to Opnesea *Example* ```typescript -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:'', - samlMetadataContent:'' + samlMetadataContent:'', samlMasterBackendRole:'', deployInVpc:true, removalPolicy:cdk.RemovalPolicy.DESTROY - } as OpensearchProps ); + } as dsf.storage.OpensearchProps ); + osCluster.addRoleMapping('dashboards_user',''); osCluster.addRoleMapping('readall',''); - } -} -const app = new cdk.App(); -new ExampleDefaultOpensearchStack(app, 'ExampleDefaultDataLakeStorage', { env: {region:'us-east-1'} }); ``` diff --git a/framework/src/storage/README.md b/framework/src/storage/README.md index fa597aca3..c55520246 100644 --- 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) \ No newline at end of file diff --git a/framework/src/storage/examples/opensearch-saml.lit.ts b/framework/src/storage/examples/opensearch-saml.lit.ts index a7892391b..5fcc6bff7 100644 --- 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:` - - - - - 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= - - - - - - urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress - - - - `, - samlMasterBackendRole:'4478b4b8-d001-7026-61d3-ad652a11b0db', + samlEntityId:'', + samlMetadataContent:'', + samlMasterBackendRole:'', deployInVpc:true, removalPolicy:cdk.RemovalPolicy.DESTROY } as OpensearchProps); - osCluster.addRoleMapping('dashboards_user','testGroupId'); - osCluster.addRoleMapping('readall','testGroupId'); + osCluster.addRoleMapping('dashboards_user',''); + osCluster.addRoleMapping('readall',''); +/// !hide } } -/// !hide + const app = new cdk.App(); new ExampleDefaultOpensearchStack(app, 'ExampleDefaultDataLakeStorage', { env: {region:'us-east-1'} }); \ No newline at end of file diff --git a/framework/src/storage/lib/opensearch/opensearch.ts b/framework/src/storage/lib/opensearch/opensearch.ts index 22e52c191..afe6229b2 100644 --- 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:'', - * samlMetadataContent:'' + * samlMetadataContent:'', * samlMasterBackendRole:'', * deployInVpc:true, * removalPolicy:cdk.RemovalPolicy.DESTROY - * } as OpensearchProps ); + * } as dsf.storage.OpensearchProps ); + * * osCluster.addRoleMapping('dashboards_user',''); * osCluster.addRoleMapping('readall',''); - * } - * } - * 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 new file mode 100644 index 000000000..b56ead9db --- /dev/null +++ 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 + + + + + ```typescript +const osCluster = new OpensearchCluster(scope, 'MyOpensearchCluster',{ + domainName:"mycluster3", + samlEntityId:'', + samlMetadataContent:'', + samlMasterBackendRole:'', + deployInVpc:true, + removalPolicy:cdk.RemovalPolicy.DESTROY +} as OpensearchProps); +osCluster.addRoleMapping('dashboards_user',''); +osCluster.addRoleMapping('readall',''); + ``` + + ```mdx-code-block + + + + + ```python +os_cluster = OpensearchCluster(scope, "MyOpensearchCluster", + domain_name="mycluster3", + saml_entity_id="", + saml_metadata_content="", + saml_master_backend_role="", + deploy_in_vpc=True, + removal_policy=cdk.RemovalPolicy.DESTROY +) +os_cluster.add_role_mapping("dashboards_user", "") +os_cluster.add_role_mapping("readall", "") + ``` + + + +