Configure Elastic Cloud SAML single sign-on

edit

Configure Elastic Cloud SAML single sign-on

edit

This functionality is in technical preview and may be changed or removed in a future release. Elastic will work to fix any issues, but features in technical preview are not subject to the support SLA of official GA features.

Elastic Cloud supports SAML single sign-on (SSO) after you you register a SAML 2.0 identity provider (IdP). Your organization’s members can sign into an organization-specific SSO login URL then join your Elastic Cloud organization automatically.

Prerequisites

edit
  • This functionality requires an Elastic Cloud Enterprise subscription.
  • You must have a SAML 2.0 compatible identity provider.

Known issues and risks

edit

Actions taken on the IdP are not automatically reflected in Elastic Cloud. For example, if you remove a user from your IdP, they are not removed from the Elastic Cloud organization and their active sessions are not invalidated. To immediately revoke a user’s active sessions, an organization owner must remove the user from the Elastic Cloud organization or remove their assigned roles.

At this time, users that join your Elastic Cloud organization by using IdP authentication are not automatically assigned roles. You must manually assign roles to organization members after they have joined the organization.

The IdP registration and domain claim features are available only by using APIs, which are in subject to change while in technical preview. The features are not yet available in the Elastic Cloud UI.

There is a known issue accessing the support portal when authenticated via SSO which will be fixed in a subsequent release. In the meantime, to access the support portal after authenticating via SSO, reset your password and sign in with email and password.

Claim a domain

edit

Before you can register and use your IdP with Elastic Cloud, you must claim one or more domains. Only users that have email addresses that match claimed domains can authenticate with your IdP.

You must have authority to modify your domain’s DNS records and an organization owner API key. To create the latter, refer to Access and authentication.

  1. Generate a verification code for your domain:

    curl -XPOST \
    -H 'Content-Type: application/json' \
    -H "Authorization: ApiKey $EC_API_KEY" \
    "https://api.elastic-cloud.com/api/v1/organizations/$ORGANIZATION_ID/domains/_generate_verification_code" \
    -d '
    {
      "domain_claim_request": "$DOMAIN"
    }
    '
  2. Update the DNS settings for your domain to add a new TXT record with name _elastic_domain_challenge. Put the verification code that you generated in the previous step into the TXT record.

    For a claim on the domain example.com, a dig command should look like:

    dig _elastic_domain_challenge.example.com TXT
    ...
    ;; ANSWER SECTION:
    _elastic_domain_challenge.example.com. 60 IN	TXT "1234rvic48untuh8uckoroaelpz7iid4uk5b8g0m2e4q57b07kak66r7xetoge8zn"
    ...
  3. Verify the domain ownership for your domain:

    curl -XPOST \
    -H 'Content-Type: application/json' \
    -H "Authorization: ApiKey $EC_API_KEY" \
    "https://api.elastic-cloud.com/api/v1/organizations/$ORGANIZATION_ID/domains/_verify" \
    -d '
    {
      "domain_claim_request": "$DOMAIN"
    }
    '

It may take some time for the DNS records to be updated and propagated in the network. If verification isn’t successful, wait a while and try again.

If the members of your Elastic Cloud organization have email addresses from multiple domains, you can claim multiple domains.

Register a SAML IdP

edit

After you have claimed one or more domains, you can register your IdP with Elastic Cloud. The steps vary by IdP; for more specific details, refer to Register Elastic Cloud SAML in Microsoft Entra ID and Register Elastic Cloud SAML in Okta.

  1. Create a new SAML 2 application in your IdP.

    1. Use placeholder values for the assertion consumer service (ACS) and SP entity ID/audience. Those values will be provided by Elastic Cloud in a later step.
    2. Configure your application to send an email attribute statement with the email address of your organization members. The email should match the domain that you claimed.
    3. Optionally configure the application to send firstName and lastName attribute statements, which will be used to set the respective fields of the user’s Elastic Cloud account.
    4. Note the SAML issuer and the SSO URL, which is the URL of the IdP where users will be redirected at login.
    5. Make sure to download the public certificate of the SAML 2 application.
  2. Register the IdP with Elastic Cloud:

    curl -XPUT \
    -H 'Content-Type: application/json' \
    -H "Authorization: ApiKey $EC_API_KEY" \
    "https://api.elastic-cloud.com/api/v1/organizations/$ORGANIZATION_ID/idp" \
    -d '
    {
      "enabled": true,
      "login_identifier_prefix": "<businessname>", 
      "saml_idp": {
        "public_certificate": [ 
          "<publiccert>"
        ],
        "issuer": "<issuer>", 
        "sso_url": "<ssourl>" 
      }
    }
    '

    login_identifier_prefix is a customizable piece of the Elastic Cloud SSO url that your organization members can use to authenticate. This could be the name of your business. You can use lowercase alphanumeric characters and hyphens in this value and you can change it later.

    public_certificate PEM-formatted certificate from your IdP. Base64 encode the entire contents of the PEM-formatted certificate so that the value sent is a single uninterrupted Base64-encoded string.

    issuer is a value provided by your IdP.

    sso_url is the SAML2 HTTP-POST endpoint of your IdP that will receive the SAML2 request.

    If successful, the API will return the details of the registered IdP containing important details that will need to be provided to the IdP. For example:

    {
    	"login_identifier": "<loginidentifier>",
    	"sso_login_url": "https://cloud.elastic.co/login/sso/<loginidentifier>", 
    	"metadata_url": "https://cloud.elastic.co/api/v1/organizations/<orgid>/idp/metadata.xml",
    	"acs": "<acs>", 
    	"sp_entity_id": "https://cloud.elastic.co/organizations/<orgid>", 
    	"signing_certificate": [ 
    		"<cert>"
    	]
    }

    sso_login_url is the URL you can provide to organization members to initiate SSO with your Elastic Cloud organization.

    acs is the SAML assertion consumer service that your SAML IdP should send SAML assertions.

    sp_entity_id is the SAML entity ID of the service provider that your SAML IdP should send in the SAML audience.

    signing_certificate is the Base64-encoded DER-encoded certificate that SAML requests to your IdP will be signed with.

  3. Update the SAML 2 application in your IdP with the values from the API response in the previous step.

    If your IdP accepts a metadata.xml file, you can fetch the file from the API. For example:

    curl -XGET \
    -H "Authorization: ApiKey $EC_API_KEY" \
    "https://api.elastic-cloud.com/api/v1/organizations/$ORGANIZATION_ID/idp/metadata.xml"

Test SSO

edit

After you register the IdP in Elastic Cloud and configure your IdP, you can test authentication. To begin SSO, open the sso_login_url in your browser. If everything is configured correctly you should be redirected to your IdP for authentication and then redirected back to Elastic Cloud signed in. Users who are not a member of the Elastic Cloud organization can authenticate with your IdP to automatically create an Elastic Cloud account provided that their email matches the claimed domain.

At this time, new users in your Elastic Cloud organization will join without any roles assigned. An administrator must manually assign roles to the organization members.

Your existing Cloud password will be invalidated each time you login via SSO. If you wish to sign in with email and password again you will need to change your password.

Enforce SSO

edit

After SSO is configured successfully, you may wish to enforce SSO authentication for members of your organization. This enforcement requires members to authenticate with SSO through the organization’s SAML IdP and prevents them from logging in by any other methods. It ensures that users who have been off-boarded in your IdP can no longer authenticate to Elastic Cloud.

If you turn on enforcement, you will be unable to access Elastic Cloud if your IdP is unavailable or misconfigured or there is an Elastic Cloud incident. It is recommended that you maintain and store an Elastic Cloud API key with organization owner level privileges so that an administrator can disable enforcement in an emergency. Refer to Create an API key. You can also open a support issue if you lose access to your Elastic Cloud account.

To turn on enforcement, use the following API call:

curl -XPUT \
-H 'Content-Type: application/json' \
-H "Authorization: ApiKey $EC_API_KEY" \
"https://api.elastic-cloud.com/api/v1/organizations/$ORGANIZATION_ID" \
-d '
{
  "enforce_authentication_method": "sso"
}
'

To turn off enforcement, use the following API call:

curl -XPUT \
-H 'Content-Type: application/json' \
-H "Authorization: ApiKey $EC_API_KEY" \
"https://api.elastic-cloud.com/api/v1/organizations/$ORGANIZATION_ID" \
-d '
{
  "enforce_authentication_method": null
}
'

Disable SSO

edit

To disable SSO and make it unavailable for your organization, update the organization IdP with enabled: false. For example:

curl -XPUT \
-H 'Content-Type: application/json' \
-H "Authorization: ApiKey $EC_API_KEY" \
"https://api.elastic-cloud.com/api/v1/organizations/$ORGANIZATION_ID/idp" \
-d '
{
  "enabled": false,
  "login_identifier_prefix": "<businessname>",
  "saml_idp": {
    "public_certificate": [
      "<publiccert>"
    ],
    "issuer": "<issuer>",
    "sso_url": "<ssourl>"
  }
}
'

Troubleshoot SSO

edit

SSO screen is not redirecting to my IdP

edit

Double check the saml_idp.sso_url provided during IdP registration. This should be the HTTP-POST binding URL to your IdP’s SAML application. Elastic Cloud will redirect to this URL during sign in.

Failure to redirect back to Elastic Cloud after IdP log in, or redirected to /access-denied

edit

There could be a variety of issues that might result in sign in failure. Try tracing the SAML request and response with a SAML tracer. You should see a SAMLRequest field when redirecting to your IdP, and a SAMLResponse field when redirecting to the Cloud ACS.

If there was an error in your IdP, there may be a non-success Status field which should describe the error that occurred.

If the SAML response was successful, double-check the components of the SAML response:

  • The Destination and Recipient should match the acs provided by the Elastic Cloud IdP registration API.
  • An AttributeStatement named email should be sent with the email matching a domain claimed by your Elastic Cloud organization. If the domain of the email doesn’t match a claimed domain, the authentication flow will not complete.
  • The AudienceRestriction Audience should match the sp_entity_id provided by the Elastic Cloud IdP registration API.
  • The Issuer should match the value provided to the Elastic Cloud IdP registration API.
  • The signature of the SAML response should be verifiable by the certificate provided during IdP configuration in Cloud.

Limitations

edit

At this time, the following features are not supported:

  • Role mappings: Assign Elastic Cloud roles based on a SAML attribute passed by your IdP. Manage the role mappings in the Elastic Cloud UI.
  • Domain claiming and IdP registration UI: Manage the IdP configuration for your organization and your claimed domains in the Elastic Cloud UI
  • Email-based SSO lookup: Enter an email address at sign-in and be redirected to the right IdP with no need for the organization SSO URL.

These features will be available in a future release.