OpenSearch SSO overview
A ClusterNest managed OpenSearch cluster can authenticate users against external identity providers. You configure them as a list of auth_sources. Each source is OIDC, SAML or the ClusterNest sign-in, and each has a unique name.
The built-in internal user always exists. It is used for API access and credential rotation, and it is always offered on the Dashboards login page next to your sources. To give it a new password, click Rotate credentials under Username and password in the cluster’s Authentication card in the console.
Source types
Section titled “Source types”| OIDC | SAML | |
|---|---|---|
| Identifies the IdP with | connect_url |
idp_metadata_url and idp_entity_id |
| Also needs | client_id and client_secret (Dashboards login only), optional audience (API tokens) |
sp_entity_id |
| Role claim | roles_key |
roles_key |
| Username claim | subject_key |
subject_key |
Both types accept an optional ca_cert (base64-encoded PEM) for an IdP behind a private CA.
Dashboards login and API access
Section titled “Dashboards login and API access”Every source can authenticate API requests. Set dashboards_login = true to also offer a source as a button on the OpenSearch Dashboards login page.
- At most one OIDC source and one SAML source can have
dashboards_loginenabled. The ClusterNest sign-in is an OIDC login, so it takes the OIDC one: a new cluster has it, so remove it before offering an OIDC source of your own. A SAML source sits next to it. - An OIDC source without
dashboards_loginvalidates bearer tokens only. It needs noclient_secret. - An OIDC source with
dashboards_loginrequires aclient_secret.
The name of a source becomes the text of its Dashboards button, “Login with” followed by the name.
Secrets are write-only
Section titled “Secrets are write-only”The API never returns client_secret. Reads report client_secret_set instead, which tells you whether a secret is stored. The same applies to repo_config.secret_access_key, which reports secret_access_key_set.
Through the API, updates replace the whole auth_sources list, and anything you leave out is removed. In Terraform, leaving the attribute out keeps the sources the cluster has, and auth_sources = [] removes them all. Sources are matched by name. Leaving out client_secret on an existing source keeps the stored secret, while a new or renamed source must supply one. The Terraform provider resends the secret from your configuration on every apply.
Role mapping
Section titled “Role mapping”roles_key names the claim that carries a user’s roles. Those values become backend roles in OpenSearch. For your own OIDC and SAML sources, ClusterNest does not create role mappings: map backend roles to OpenSearch roles yourself in Dashboards or through the security API. The ClusterNest sign-in needs none, because it maps each member’s organization role to full or read-only access.