SAML with Okta

This guide covers how to integrate Okta (or other SAML identity providers) with OpenSearch UI. There are two supported paths — this page explains both and helps you choose.

Why direct SAML isn't supported

OpenSearch UI is a standalone AWS resource — it's not a feature running inside an OpenSearch domain. Unlike OpenSearch Dashboards (which supports direct SAML configuration), OpenSearch UI authenticates through AWS IAM or IAM Identity Center (IDC).

This means you can't configure a SAML app in Okta that points directly at OpenSearch UI. Instead, you route through either IDC or IAM federation.

Two integration paths

Path 1: Okta → IDC → OpenSearch UI (recommended)

This is the recommended approach. Okta acts as an external identity provider for IDC, which handles the OpenSearch UI integration.

Why this path is better:

Native SSO experience — users sign in through the IDC portal or Okta dashboard
User and group sync via SCIM — manage access in Okta, it syncs to IDC automatically
Simpler IAM role setup — one role with a trust policy for sso.amazonaws.com
Consistent authorization — IDC manages user-to-application assignments

High-level flow:

Okta authenticates the user
Okta passes the SAML assertion to IDC
IDC assumes the configured IAM role
The user accesses OpenSearch UI with the role's permissions

Path 2: Okta → SAML IAM Federation → OpenSearch UI (alternative)

Use this path if you can't enable IDC in your account (e.g., organizational restrictions).

How it works:

Okta authenticates the user
Okta passes a SAML assertion to AWS STS
STS returns temporary credentials for an IAM role
The user accesses OpenSearch UI with those credentials (via presigned URL or federated console)

Limitations:

No native SSO portal — users need to go through the AWS federated console or use presigned URLs
Authorization is based solely on the IAM role — no per-user access control without additional IAM role mapping
More complex to troubleshoot

Path 1 setup: Okta → IDC → OpenSearch UI

Step 1: Configure Okta as an IDC external identity provider

In the IAM Identity Center console , go to Settings → Identity source → Actions → Change identity source
Choose External identity provider
Download the IDC SAML metadata file (you'll upload this to Okta)
In Okta, create a new SAML 2.0 application:
- Single sign-on URL: Use the ACS URL from the IDC metadata
- Audience URI (SP Entity ID): Use the Entity ID from the IDC metadata
Download the Okta metadata file and upload it to IDC
Complete the identity source change in IDC

For detailed steps, see AWS docs: Connect to an external identity provider .

Step 2: Enable SCIM provisioning (recommended)

SCIM automatically syncs users and groups from Okta to IDC:

In IDC Settings → Provisioning, enable automatic provisioning
Copy the SCIM endpoint and access token
In your Okta app, go to Provisioning → Integration and configure with the SCIM endpoint and token
Enable the provisioning features you need (Create Users, Update User Attributes, Deactivate Users)

Step 3: Set up the OpenSearch UI application with IDC

Follow the IDC Auth Setup guide starting from Step B (creating the IAM role) through Step E (verification).

Step 4: Assign users

In IDC, go to Applications → your OpenSearch UI application
Assign the Okta-synced users or groups

Users can now access OpenSearch UI by:

Clicking the app tile in the IDC portal
Navigating to the Application URL directly (they'll be redirected to Okta for login)

Path 2 setup: Okta → SAML IAM Federation → OpenSearch UI

Step 1: Create a SAML app in Okta

In Okta, create a new SAML 2.0 application
Configure the SAML settings:
- Single sign-on URL: https://signin.aws.amazon.com/saml
- Audience URI (SP Entity ID): urn:amazon:webservices
Configure attribute statements:
- https://aws.amazon.com/SAML/Attributes/RoleSessionName → user.email
- https://aws.amazon.com/SAML/Attributes/Role → The IAM role ARN and SAML provider ARN (comma-separated)
Download the Okta metadata XML file

Step 2: Create the SAML identity provider in IAM

aws iam create-saml-provider \
  --saml-metadata-document file://okta-metadata.xml \
  --name OktaSAMLProvider

Note the provider ARN: arn:aws:iam::<ACCOUNT_ID>:saml-provider/OktaSAMLProvider

Step 3: Create the IAM role with SAML trust

aws iam create-role \
  --role-name OktaOpenSearchUIRole \
  --assume-role-policy-document '{
    "Version":"2012-10-17",
    "Statement":[{
      "Effect":"Allow",
      "Principal":{"Federated":"arn:aws:iam::<ACCOUNT_ID>:saml-provider/OktaSAMLProvider"},
      "Action":"sts:AssumeRoleWithSAML",
      "Condition":{
        "StringEquals":{
          "SAML:aud":"https://signin.aws.amazon.com/saml"
        }
      }
    }]
  }'

Step 4: Attach the OpenSearch UI permission policy

aws iam put-role-policy \
  --role-name OktaOpenSearchUIRole \
  --policy-name OpenSearchAppAccess \
  --policy-document '{
    "Version":"2012-10-17",
    "Statement":[{
      "Effect":"Allow",
      "Action":"opensearch:ApplicationAccessAll",
      "Resource":"arn:aws:opensearch:<REGION>:<ACCOUNT_ID>:application/*"
    }]
  }'

Step 5: Access OpenSearch UI

With SAML IAM federation, users access OpenSearch UI through the AWS federated console:

User clicks the Okta app tile
Okta redirects to AWS with the SAML assertion
User lands in the AWS Console with the federated role
User navigates to OpenSearch Service → OpenSearch UI → their application

Alternatively, you can generate presigned URLs programmatically using the federated credentials.

Common issues

Issue	Cause	Resolution
IDC shows "organization instance required"	Your account uses an org-level IDC instance managed by another account	Contact your AWS Organization admin to configure IDC, or use Path 2 (SAML IAM federation)
Users synced from Okta can't access the app	Users aren't assigned to the OpenSearch UI application in IDC	Assign users/groups in IDC → Applications → your app
SAML assertion errors after Okta login	Attribute mapping mismatch	Verify the SAML attribute statements match what AWS expects (RoleSessionName, Role)
"Access denied" after successful federation	IAM role missing `opensearch:ApplicationAccessAll`	Add the permission policy to the federated role
Inconsistent authorization with SAML-via-IAM	All federated users share the same IAM role	This is a limitation of Path 2 — all users get the same permissions. Use Path 1 (IDC) for per-user access control
Okta app tile doesn't appear for users	Users not assigned to the Okta app	Assign users or groups to the SAML app in Okta

Which path should I choose?

Factor	Path 1 (IDC)	Path 2 (SAML IAM)
Per-user access control	✅ Yes, via IDC assignments	❌ All users share one IAM role
Setup complexity	Medium	Medium-High
SSO portal experience	✅ Native IDC portal	❌ AWS federated console only
Requires IDC	✅ Yes	❌ No
SCIM user sync	✅ Supported	❌ Not applicable

Recommendation: Use Path 1 (Okta → IDC) unless you have a specific reason you can't enable IDC.

IDC Auth Setup — Detailed IDC setup guide
IAM Auth Setup — IAM-only authentication
IAM Policies Reference — Full permissions reference
AWS docs: Connect Okta to IAM Identity Center
AWS docs: SAML 2.0 federation