Skip to main content

OpenSearch Cluster

An Amazon OpenSearch Domain with SAML integration and access to OpenSearch REST API.

Overview​

The OpenSearchCluster construct implements an OpenSeach Domain following best practises including:

  • private deployment in VPC
  • SAML-authentication plugin to access OpenSearch Dashboards via a SAML2.0-compatible IdP
  • access to the OpenSeach REST API to interact with OpenSearch objects like Roles, Indexes, Mappings...

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.

Configure 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 to set up IAM Identity center SAML application.

Main steps are:

  1. In the region where you deploy OpenSearch, enable IAM Identity Center with AWS Organizations
  2. Create a IAM Identity Center group. Use its group ID in the saml_master_backend_role parameter of the construct
  3. Create a custom application in IAM Identity Center and provide fake URLs as temporary
  4. Download the IAM Identity Center SAML metadata file
  5. Extract the entityID URL from the metadata file and pass it to samlEntityId parameter of the construct
  6. Use the content of the metadata file in the samlMetadataContent parameter of the construct
  7. Provision the construct
  8. Update the IAM Identity Center application attribute mappings by adding
    1. ${user:email} as the Subject with emailAddress format. Subject is the default subject key used in OpenSearch construct, modify the mapping according to your configuration.
    2. ${user:groups}as the Role with unspecified format. Role is the default role key used in OpenSearch construct, modify the mapping according to your configuration.
  9. Update the IAM Identity Center application configuration
    1. Set the Application ACS URL to the OpenSearch SSO URL (IdP initiated) from the OpenSearch Domain security configuration
    2. Set the Application SAML audience to the Service provider entity ID from the OpenSearch Domain security configuration

Usage​

Default configuration

  const osCluster = new dsf.consumption.OpenSearchCluster(this, 'MyOpenSearchCluster',{
    domainName:"mycluster",
    samlEntityId:'<IdpIdentityId>',
    samlMetadataContent:'<IdpMetadataXml>',
    samlMasterBackendRole:'<IAMIdentityCenterAdminGroupId>',
    deployInVpc:true,
    removalPolicy:cdk.RemovalPolicy.DESTROY
  });


  osCluster.addRoleMapping('DashboardOsUser', 'dashboards_user','<IAMIdentityCenterDashboardUsersGroupId>');
  osCluster.addRoleMapping('ReadAllOsRole','readall','<IAMIdentityCenterDashboardUsersGroupId>');

Using Client VPN Endpoint

  const vpcVpn = new dsf.utils.DataVpc(this, 'VpcWithVpn', {
    vpcCidr:'10.0.0.0/16',
    clientVpnEndpointProps: {
        serverCertificateArn:"<ACMCertificateArn>",
        samlMetadataDocument:`<IdpClientVpnApplicationMetadataXml>`,
        selfServicePortal:false
    }
  })
  const osCluster = new dsf.consumption.OpenSearchCluster(this, 'MyOpenSearchCluster',{
    domainName:"mycluster",
    samlEntityId:'<IdpIdentityId>',
    samlMetadataContent:'<IdpOpenSearchApplicationMetadataXml>',
    samlMasterBackendRole:'<IAMIdentityCenterAdminGroupId>',
    deployInVpc:true,
    vpc:vpcVpn.vpc
  });

  osCluster.addRoleMapping('DashboardOsUser', 'dashboards_user','<IAMIdentityCenterDashboardUsersGroupId>');
  osCluster.addRoleMapping('ReadAllOsRole','readall','<IAMIdentityCenterDashboardUsersGroupId>');