IDC Auth Setup

This guide walks through setting up IAM Identity Center (IDC) authentication for your OpenSearch UI application. IDC gives your team a browser-based SSO login experience — users sign in with their IDC credentials instead of generating presigned URLs.

Prerequisites checklist

Before you start, make sure you have:

AWS account with both base and IDC IAM permissions
IAM Identity Center enabled in your account or organization
- If not enabled, see Enabling IAM Identity Center
- Note whether you have an organization instance or account instance — this affects some configuration steps
An IAM role with the required permission policy AND trust policy (you'll create this below if you don't have one)
At least one OpenSearch domain or serverless collection in your region
At least one user or group created in IDC

Additional prerequisite: Organization-level IDC with customer-managed KMS key

If your organization-level IDC instance uses a customer-managed KMS key (CMK) for encryption at rest, you must grant the OpenSearch UI service permission to decrypt identity data via that key. Without this, SSO login will fail with AccessDeniedException during authorization code validation.

Add the following statements to your IDC KMS key policy (in the management account where IDC is enabled):

{
    "Sid": "Allow_AWS_app_admins_in_the_same_AWS_organization_to_use_the_KMS_key",
    "Effect": "Allow",
    "Principal": "*",
    "Action": [
        "kms:Decrypt"
    ],
    "Resource": "*",
    "Condition": {
        "StringEquals": {
            "aws:PrincipalOrgID": "<YOUR_ORG_ID>"
        },
        "StringLike": {
            "kms:ViaService": [
                "sso.*.amazonaws.com",
                "identitystore.*.amazonaws.com"
            ]
        }
    }
},
{
    "Sid": "Allow_managed_apps_to_use_the_KMS_Key",
    "Effect": "Allow",
    "Principal": "*",
    "Action": [
        "kms:Decrypt"
    ],
    "Resource": "*",
    "Condition": {
        "Bool": {
            "aws:PrincipalIsAWSService": "true"
        },
        "StringLike": {
            "kms:ViaService": [
                "sso.*.amazonaws.com",
                "identitystore.*.amazonaws.com"
            ]
        },
        "StringEquals": {
            "aws:SourceOrgID": "<YOUR_ORG_ID>"
        }
    }
}

Replace <YOUR_ORG_ID> with your AWS Organization ID (format: o-xxxxxxxxxx).

For more details, see AWS IAM Identity Center customer-managed keys documentation .

How to check if your IDC uses a CMK: In the IAM Identity Center console, go to Settings → Management tab → Key for encrypting IAM Identity Center data at rest. If it shows a customer-managed key ARN (not "AWS owned key"), you need the policy above.

Step A: Verify IDC is enabled

Open the IAM Identity Center console
If you see a dashboard with your IDC instance details → IDC is enabled. Note the instance type (organization or account).
If you see a setup/welcome page → you need to enable IDC first.

Enabling IDC (if needed)

Organization instance (recommended): Works across all accounts in your AWS Organization. Best for production use.
Account instance: Scoped to a single account. Good for testing or isolated setups.

If your AWS account is part of an organization and someone else manages it, check with your admin — they may need to enable IDC at the organization level.

Step B: Create the IAM role

IDC needs an IAM role to assume when users access your OpenSearch UI application. This role needs two things: a permission policy (what the role can do) and a trust policy (who can assume the role).

Permission policy

Create a policy with the permissions needed to access the application:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": "opensearch:ApplicationAccessAll",
            "Resource": "arn:aws:opensearch:<REGION>:<ACCOUNT_ID>:application/*"
        }
    ]
}

Trust policy

The trust policy must allow the IDC service to assume this role:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "Service": "sso.amazonaws.com"
            },
            "Action": "sts:AssumeRole"
        }
    ]
}

Create the role via CLI

# Create the role with the trust policy
aws iam create-role \
  --role-name OpenSearchUI-IDC-Role \
  --assume-role-policy-document '{
    "Version":"2012-10-17",
    "Statement":[{
      "Effect":"Allow",
      "Principal":{"Service":"sso.amazonaws.com"},
      "Action":"sts:AssumeRole"
    }]
  }'
 
# Attach the permission policy
aws iam put-role-policy \
  --role-name OpenSearchUI-IDC-Role \
  --policy-name OpenSearchAppAccess \
  --policy-document '{
    "Version":"2012-10-17",
    "Statement":[{
      "Effect":"Allow",
      "Action":"opensearch:ApplicationAccessAll",
      "Resource":"arn:aws:opensearch:<REGION>:<ACCOUNT_ID>:application/*"
    }]
  }'

Note the role ARN — you'll need it in the next step. It looks like: arn:aws:iam::<ACCOUNT_ID>:role/OpenSearchUI-IDC-Role

Step C: Create the application with IDC enabled

Console

Open the OpenSearch Service console
In the left navigation, choose OpenSearch UI (Dashboards)
Choose Create application
Enter an application name
Add at least one data source (OpenSearch domain or serverless collection)
Under Authentication, check Authentication with IAM Identity Center
Select your IAM role from the dropdown (the role you created in Step B)
(Optional) Configure dashboard admins under Advanced settings
Choose Create

CLI

aws opensearch create-application \
  --name "my-opensearch-app" \
  --iam-identity-center-options '{
    "enabled": true,
    "iamRoleForIdentityCenterApplicationArn": "arn:aws:iam::<ACCOUNT_ID>:role/OpenSearchUI-IDC-Role"
  }' \
  --data-sources '[{
    "dataSourceArn": "arn:aws:es:<REGION>:<ACCOUNT_ID>:domain/<DOMAIN_NAME>"
  }]' \
  --region <REGION>

Step D: Assign users in IDC

After creating the application, you need to assign IDC users or groups so they can log in:

Open the IAM Identity Center console
In the left navigation, choose Applications
Find the application that was automatically registered (it will match your OpenSearch UI app name)
Choose Assign users and groups
Select the users or groups that should have access
Choose Assign

Step E: Verify your setup

In the OpenSearch Service console, check that your application status shows Active
Verify that Authentication with IAM Identity Center shows as Enabled in the application details
Copy the Application URL from the application details page
Open the Application URL in your browser — you should be redirected to the IDC login page
Sign in with your IDC credentials — you should see the OpenSearch UI workspace selector

Troubleshooting

Symptom	Likely cause	Resolution
"IAM Identity Center is not enabled" during app creation	No IDC instance in your account or organization	Enable IDC in the IAM Identity Center console
SSO login redirects but returns an error	IAM role trust policy missing `sso.amazonaws.com`	Update the role's trust policy to include the SSO service principal (see Step B)
SSO login works but user has no access	User not assigned to the IDC application	Assign the user to the application in the IDC console (see Step D)
"Access denied" after IDC login	IAM role permission policy missing required actions	Verify the role has `opensearch:ApplicationAccessAll` and data source access permissions
Application shows "IDC enabled" but login fails	IAM role ARN mismatch	Verify the role ARN in application settings matches the role with the correct trust and permission policies
"Unable to create application" with IDC	Missing IDC-specific IAM permissions	Ensure your IAM user/role has the `sso:CreateApplication`, `sso:PutApplicationGrant`, and `iam:PassRole` permissions. See IAM Policies Reference
IDC login page shows but no users can sign in	No users assigned in IDC	Go to IDC console → Applications → your app → Assign users and groups
SSO login fails with "Failed to validate authorization code" or `AccessDeniedException`	IDC uses a customer-managed KMS key (CMK) without the required key policy for OpenSearch UI	Add the KMS key policy statements described in Additional prerequisite: Organization-level IDC with CMK

Choose Your Auth Method — Compare IAM vs IDC vs SAML
IAM Policies Reference — Full permissions reference including IDC-specific permissions
AWS docs: IAM Identity Center
AWS docs: OpenSearch UI getting started