Oracle Cloud Infrastructure Documentation

SAML Authentication in Search with OpenSearch

Learn about using SAML authentication OCI Search with OpenSearch.

OCI Search with OpenSearch supports using an identity provider for access and control to OpenSearch clusters and OpenSearch Dashboards. This is available through SAML single sign-on support in the OpenSearch Security plugin.

With SAML integration, you can configure a cluster so that OCI OpenSearch, as a SAML service provider connects to your identity provider to authenticate users and pass back an authentication token to OCI OpenSearch for access to OpenSearch clusters and OpenSearch Dashboards. You can also configure the OpenSearch Dashboard, so that users are redirected to the identity provider's sign-in page for authentication when accessing the OpenSearch Dashboard.

The following table describes the SAML configuration settings applicable to Search with OpenSearch.

SAML Configuration

Description

Field or Attribute Name
SAML metadata Metadata file that describes the identity provider's capabilities and configuration. Required.
  • Console: Metadata content
  • CLI: idp-metadata-content
  • API: idpMetadataContent
Identity ID The identity provider's name. Required.
  • Console: Identity ID
  • CLI: ipd-identity-id
  • API: ipdIdentityId
OpenSearch Dashboard URL The URL of the cluster's OpenSearch Dashboard. Optional.
  • Console: Dashboard URL
  • CLI: opendashboard-url
  • API: opendashboardUrl
Admin backend role

The backend role in the identity provider for the users who have full administrator permissions for the cluster. Optional.
  • Console: Admin backend role
  • CLI: admin-backend-role
  • API: adminBackendRole
Subject key

If the identity provider uses the default element name for users, NameID, you don't need to specify anything here. Otherwise, use this element to specify the element in the SAML response that contains the users. Optional.
  • Console: Subject key
  • CLI: subject-key
  • API: subjectKey
Roles key If you're using backend roles, this specifies the element name in the SAML response that contains the user roles. Optional
  • Console: Roles key
  • CLI: roles-key
  • API: rolesKey

Limitations and Considerations

  • Search with OpenSearch only supports enabling SAML authentication in the Console for existing clusters. You can't enable SAML authentication when you create a new cluster in the Console. You can enable SAML authentication when creating a new OpenSearch cluster using the CLI or API.

  • When you create a new cluster and enable SAML authentication using the CLI or API, you must also enable role-based access control for the cluster, with the security mode set to enforcing.

Prerequisites

  • An existing identity provider.
  • For Console only, you must have an existing OpenSearch cluster created.

  • You can only enable SAML for an existing cluster in the Console.

    1. Open the navigation menu and click Databases. Under OpenSearch, click Clusters.

    2. In the Clusters list, click the name of the cluster you want to enable SAML for.

    3. On the cluster details page, click More actions, and then select Add SAML authentication.

    4. In the Metadata content field, paste the contents of the SAML metadata file for the identity provider.

      The SAML metadata file describes the identity provider's capabilities and configuration. This includes the identity provider's certificate.

    5. Specify the identity provider's name in Identity ID.

    6. You can optionally specify the following configuration details:

      • Dashboard URL: The cluster's OpenSearch.Dashboard URL.
      • Admin backend role: The backend role in the identity provider for users who have administrator privileges for the OpenSearch cluster.
      • Roles key: Specifies the attribute in the SAML response that contains the user roles.
      • Subject key: Specifies the attribute in the SAML response that contains the users.
    7. Click Save changes.
  • For information about using the CLI, see Command Line Interface (CLI). For a complete list of flags and options available for CLI commands, see the CLI Command Reference.

    Enabling SAML When Creating a Cluster

    You can enable SAML authentication when you use the create command for the cluster object in the CLI to create a cluster. In addition to the required parameters for the create command, you also need to include the following parameters:

    • The role-based access control parameters, including security-mode, security-master-user-name, and security-master-user-password-hash. The security-mode parameter must be set to ENFORCING.

    • The securitySamlConfig parameter that contains the SAML configuration. The following shows a JSON example with SAML configuration for this parameter:

      {
    "isEnabled": true,
    "idpEntityId": "<identity_provider_name>",
    "idpMetadataContent": "xml content"
    "opendashboardUrl": "https://localhost:5601",
    "adminBackendRole": "<admin_role_name>",
    "subjectKey": "<NameID>",
    "rolesKey": "<group_name>"
    }

      While the preceding sample includes all the available SAML configuration fields, only the isEnabled, idpEntityId, and idpMetadataContent fields are required.

    Sample create command:

    oci opensearch cluster create --compartment-id <compartment_ocid> --securitySamlConfig <SAML_Config_JSON> --security-mode ENFORCING --security-master-user-name <username> --security-master-user-password-hash <password> ...remaining required fields

    Enabling SAML When Updating a Cluster

    You can enable SAML authentication for an existing cluster when you use the update command for the cluster object in the CLI to update a cluster. You need to include the securitySamlConfig parameter in the update command. See the SAML configuration JSON in the preceding section for an example of what to specify for this parameter.

    Sample update command:

    oci opensearch cluster update --display-name<cluster_name> --opensearch-cluster-id <cluster_ocid --securitySamlConfig <SAML_Config_JSON>

    If role-based access control is not enabled for the cluster, you need to enable it by also including the security-mode, security-master-user-name, and security-master-user-password-hash parameters. The security-mode parameter must be set to ENFORCING.

  • For information about using the API and signing requests, see REST APIs and Security Credentials. For information about SDKs, see Software Development Kits and Command Line Interface.

    Enabling SAML When Creating a Cluster

    You can enable SAML authentication when you use the CreateOpensearchCluster operation to create a cluster. Pass the SAML configuration details in the CreateOpensearchClusterDetails, using the new securitySamlConfig attribute, as shown in the following example:

    POST https://opensearch.us-ashburn-1.oci.oraclecloud.com/20180828/opensearchClusters/
{
  ...
  "securitySamlConfig": {
    "isEnabled": true,
    "idpEntityId": "<identity_provider_name>",
    "idpMetadataContent": "xml content"
    "opendashboardUrl": "https://localhost:5601",
    "adminBackendRole": "<admin_role_name>",
    "subjectKey": "<NameID>",
    "rolesKey": "<group_name>"
  },
  ...
}

    Enabling SAML When Updating a Cluster

    You can enable SAML authentication for an existing cluster when you use the UpdateOpensearchCluster operation to update a cluster. Pass the SAML configuration details in the UpdateOpensearchClusterDetails, using the new securitySamlConfig attribute, as shown in the following example:

    PUT https://opensearch.us-ashburn-1.oci.oraclecloud.com/20180828/opensearchClusters/ocid1.opensearchcluster.oc1.<unique_ID>
{
  ...
  "securitySamlConfig": {
    "isEnabled": true,
    "idpEntityId": "<identity_provider_name>",
    "idpMetadataContent": "xml content"
    "opendashboardUrl": "https://localhost:5601",
    "adminBackendRole": "<admin_role_name>",
    "subjectKey": "<NameID>",
    "rolesKey": "<group_name>"
  },
  ...
}