Use SAML Identities for programmatic entry to Amazon OpenSearch Service

Prospects of Amazon OpenSearch Service can already use Safety Assertion Markup Language (SAML) to entry OpenSearch Dashboards.

This publish outlines two strategies by which programmatic customers can now entry OpenSearch utilizing SAML identities. This is applicable to all identification suppliers (IdPs) that help SAML 2.0, together with prevalent ones like Lively Listing Federation Service (ADFS), Okta, AWS IAM Identification Heart (Successor to AWS Single Signal-On), KeyCloak, and others. Though we define the strategies as they pertain to OpenSearch Service and AWS Identification and Entry Administration (IAM), programmatic entry to every of those particular person suppliers is outdoors the scope of this publish. Most of those suppliers do present such a facility.

Single sign-on strategies

Once you use single sign-on (SSO), there are two totally different authentication strategies:

  • Identification supplier initiated – That is when a consumer or a user-agent first authenticates with an IdP and will get a SAML assertion that establishes the identification of the consumer. This assertion is then handed to a service supplier (SP) that gives entry to a protected useful resource.
  • Service supplier initiated – Though the IdP-initiated trade is easy, a extra typical sign-on expertise is when the protected useful resource is accessed instantly. The SP then redirects the consumer to the IdP for authentication together with a SAML authentication request. The IdP responds with an authentication assertion inside a SAML response. After that, the SSO expertise is similar as that of an IdP-initiated stream.

For programmatic entry to OpenSearch Service, an exterior IdP is the IdP, and OpenSearch Service and IAM each function SPs. To configure your IdP of alternative because the SAML IdP for IAM, confer with Creating IAM SAML identification suppliers. To configure OpenSearch Service, confer with SAML authentication for OpenSearch Dashboards.

Within the following sections, we define two strategies to entry OpenSearch Service API:

Technique 1: Use AWS STS

The next determine reveals the sequence of calls to entry OpenSearch Service API utilizing AWS STS.

Let’s discover every step in additional element.

Steps 1 and a couple of

Steps 1 and a couple of range relying upon your chosen IdP. On the whole, they sometimes present an authentication API or session API or one other related API to authenticate and retrieve the SAML authentication assertion response. We use this SAML assertion within the subsequent step.

Steps 3 and 4

Name the AssumeRoleWithSAML AWS STS API to trade the SAML assertion for short-term credentials related along with your SAML identification. See the next code:

curl --location '
RoleArn=<ARN of the position being assumed>&
PrincipalArn=<ARN of the IdP built-in with IAM>&
SAMLAssertion=<Base-64 encoded SAML assertion>'

The response comprises the short-term AWS STS credentials with AccessKeyId, SecretAccessKey, and a SessionToken.

Step 5

Use the short-term credentials from the final step to signal all API requests to OpenSearch Service. Additionally make sure the position that you just assumed with the AssumeRoleWithSAML name has adequate permission to entry the requisite knowledge in OpenSearch Service. Check with Mapping roles to customers for extra details about mapping this position as a backend position. As a further step to make sure consistency, this AWS STS position and any SAML group the consumer is a part of might be mapped to the identical position in OpenSearch Service. The next code reveals a mannequin to make this name:

curl --location ‘<OpenSearch Service area URL>/_search' 
--header 'X-Amz-Safety-Token: Fwo...==(truncated)' 
--header 'X-Amz-Date: 20230327T134710Z' 
--header 'Authorization: AWS4-HMAC-SHA256 Credential=ASI..(truncated)/20230327/us-east-1/es/aws4_request, SignedHeaders=host;x-amz-date;x-amz-security-token, Signature=95eb…(truncated)'

Technique 2: Use OpenSearch Dashboards’ console proxy

OpenSearch Dashboards has a part known as a console proxy that may proxy requests to OpenSearch. This permits OpenSearch shoppers to make the identical API calls in Area Particular Language (DSL) to this console proxy as an alternative of instantly calling OpenSearch. The console proxy forwards these calls to OpenSearch and responds again to the shoppers in the identical format as OpenSearch.

The next determine reveals the sequence of calls you may make to the console proxy to achieve programmatic entry to OpenSearch Service.

Steps 1 and a couple of

The primary two steps are just like methodology 1, and they’re going to range relying on what IdP is chosen. Basically, you’ll want to receive a SAML authentication assertion response from the IdP.

Steps 3 and 4

Use the SAML assertion from the earlier steps and POST it to the Assertion Client Service (ACS) URL, _opendistro/_security/saml/acs/idpinitiated, to trade the assertion for the security_authentication token. The next code reveals the command line for these steps:

curl --location ‘<dashboards URL>/_opendistro/_security/saml/acs/idpinitiated' 
--header 'content-type: utility/x-www-form-urlencoded' 
--data-urlencode ‘SAMLResponse=Base-64 encoded SAML assertion' 
--data-urlencode 'RelayState=’

For those who’re utilizing the OpenSearch engine, the dashboard URL is <area URL>/_dashboards. For those who’re utilizing the Elasticsearch engine, the dashboard URL is <area URL>/_plugin/kibana. OpenSearch Dashboards processes this and responds with a redirect response with code 302 and an empty physique. The response headers now additionally comprise a cookie named security_authentication, which is the token you could use in all subsequent calls.

Steps 5–8

Use the security_authentication cookie within the API calls to the console proxy to carry out programmatic API calls. The next code reveals a command line for these steps:

curl --location ‘<dashboardsURL>/api/console/proxy?path=_search&methodology=GET' 
--header 'content-type: utility/json' 
--header 'cookie: security_authentication=Fe26.2**1...(truncated)' 
--header 'osd-xsrf: true' 
--data '{
  "question": {
    "match_all": {}

Ensure to incorporate a header known as osd-xsrf : true for programmatic entry to dashboards. The console proxy path is /api/console/proxy for Elasticsearch engines model 6.x and seven.x and OpenSearch engine model 1.x and a couple of.x.

Just like methodology 1, be sure that to map roles and teams related to a specific SAML identification as the right backend position with requisite permissions.

Evaluating these strategies

You should utilize methodology 1 in any area whatever the engine so long as fine-grained entry management is enabled. Technique 2 solely works for domains with Elasticsearch engine variations higher than 6.7 and all OpenSearch engine variations.

The OpenSearch Dashboards course of is mostly meant for human interactions, which has a decrease API name price and quantity than these of programmatic calls. OpenSearch can deal with significantly greater API name charges and quantity, so take care to not ship high-volume API calls utilizing methodology 2. As a finest follow for programmatic entry with SAML identities, we suggest methodology 1 wherever attainable to keep away from efficiency bottlenecks.


Each of the strategies outlined on this publish present an analogous stream to entry OpenSearch Service programmatically utilizing SAML identities (exchanging a SAML assertion for an authentication token). AssumeRoleWithSAML is a key and pretty straightforward-to-use API that allows this entry and is our really useful methodology. Attempt one in all OpenSearch Service labs and launch an OpenSearch Service area to experiment with these strategies. Good luck!

Concerning the creator

Muthu Pitchaimani is a Search Specialist with Amazon OpenSearch Service. He builds large-scale search functions and options. Muthu is within the subjects of networking and safety, and relies out of Austin, Texas.

Related Articles


Please enter your comment!
Please enter your name here

Latest Articles