--- title: Configure SAML description: You can configure Enterprise Analytics to authenticate an Enterprise Analytics Web Console user via a SAML Identity Provider. pubDate: 2026-08-17T09:53:44.266Z antora: editUrl: https://github.com/couchbaselabs/docs-enterprise-analytics/edit/release/2.0/modules/reference/pages/rest-configure-saml.adoc xref: xref:2.0@enterprise-analytics:reference:rest-configure-saml.adoc[] --- [Consult the llms.txt file for a full list of contents](/llms.txt) [View original HTML](/enterprise-analytics/2.0/reference/rest-configure-saml.html) # Configure SAML > You can configure Enterprise Analytics to authenticate an Enterprise Analytics Web Console user via a SAML Identity Provider. ## [](#get-settingssaml)GET /settings/saml **Description** Returns Enterprise Analytics's _Security Assertion Markup Language_ (SAML) settings as JSON object. **Example** Unresolved include directive in modules/reference/pages/rest-configure-saml.adoc - include::rest-api:example$get-saml.sh[] ## [](#post-settingssaml)POST /settings/saml **Description** Updates Enterprise Analytics's SAML authentication settings. If the update is successful, this call returns the current settings. If it encounters an error, it returns an error message. **Syntax:** curl -X POST -u : http://:/settings/saml -d args . . **Example** In following example: * The curl command adds the Enterprise Analytics's key and certificate by using the `--data-urlencode` argument to read them from the files `my_key.pem` and `my_certificate.crt`. * The _Fully Qualified Domain Name_ (FQDN) where users connect to the Web Console is `nodename.example.com`. Enterprise Analytics determines this value based on its own configuration. * The IdP's metadata URL is `https://myidp.com/sso/saml/metadata`. In this example, the metadata provides all of the configuration information Enterprise Analytics needs to interact with the IdP. Therefore, the curl command has no further IdP parameters. Unresolved include directive in modules/reference/pages/rest-configure-saml.adoc - include::rest-api:example$post-saml.sh[] __Table 1\. Controller parameters__ | Parameter | Description | | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | authnNameIDFormat | The format the SAML message uses to identify its subject (the user who's authenticating). See [NameID and User Identity](../manage/manage-security/configure-saml.md#nameid) for possible values. Defaults to urn:oasis:names:tc:SAML:2.0:nameid-format:persistent. | | enabled | Boolean that enables SAML authentication with an IdP when set to true. Set to false by default, which disables SAML authentication. | | groupsAttribute | The name of the SAML attribute from which Couchbase extracts the user's groups. Defaults to an empty string which has Enterprise Analytics use the list of groups defined for users in their Enterprise Analytics account. | | groupsAttributeSep | A list of characters that separate group names. Set this value if the IdP sends a list of group names in the SAML attribute you have mapped to Couchbase groups. Defaults to " ," which means groups can be separated by a space, a comma, or combinations of the two characters. Enterprise Analytics allows the string to use multiple characters to separate group names. For example, suppose the SAML attribute contains the string "group1,group2, group3 group4.subgroup". Then when using the default setting, Enterprise Analytics splits the string into four groups: group1, group2, group3 and group4.subgroup. Only has an effect if groupsAttribute has a value. | | groupsFilterRE | A regular expression Enterprise Analytics uses to filter the group names the IdP sends in a SAML attribute. Enterprise Analytics assigns the user any groups sent by the IdP whose name match the regular expression. Defaults to .\* which accepts all group names. | | idpAuthnBinding | Controls how Enterprise Analytics sends parameters to the IdP. Can be either: post: the default value which sends the parameters as part of POST message to te IdP. redirect: sends the parameters to the IdP encoded in the URL. | | idpLogoutBinding | Similar to idpAuthnBinding, but for the logout request. | | idpMetadataConnectAddressFamily | Whether to use IPv4 or IPv6 addresses to retrieve metadata from the IdP. One of three values: undefined: the default value which automatically determine the address family to use. inet: use IPv4 addresses when retrieving the metadata from the IdP. inet6: use IPv6 addresses when retrieving the metadata. | | idpMetadataHttpTimeoutMs | Integer value containing the number of milliseconds Enterprise Analytics waits for a successful connection to the IdP when retrieving metadata. It reports an error if this periods elapses before the IdP responds. Defaults to 5000 (5 seconds). | | idpMetadataOrigin | Controls how Enterprise Analytics get the IdP's metadata. Can have one of three values: \* http: Enterprise Analytics downloads the IdP's metadata from the URL in idpMetadataURL periodically. The idpMetadataRefreshIntervalS setting controls how often Enterprise Analytics fetches the metadata. \* http\_one\_time: Enterprise Analytics downloads the IdP's metadata from the URL in idpMetadataURL once. It does not automatically update the metadata after the initial fetch. \* upload: the user provides a file containing the metadata. | | idpMetadataRefreshIntervalS | Integer value containing the number of seconds Enterprise Analytics waits before refreshing the IdP's metadata. Only has an effect if you have enabled metadata refresh. Defaults to 3600 (1 hour). | | idpMetadataTLSCAs | The certificate or certificate chain Enterprise Analytics uses when verifying its connection to retrieve metadata from the IdP. Must be in _Privacy Enhanced Mail_ (PEM) format. Only has an effect if the URL in idpMetadataURL has https as its scheme and idpMetadataTLSVerifyPeer is true, in which case idpMetadataTLSCAs is required. | | idpMetadataTLSExtraOpts | Extra TLS options that Enterprise Analytics applies when connecting to the IdP to retrieve the metadata. Only use this parameter if asked to by technical support. | | idpMetadataTLSSNI | Sets a custom _Server Name Indication_ (SNI) for the connection from Enterprise Analytics to the IdP to retrieve the metadata. | | idpMetadataTLSVerifyPeer | A Boolean value that controls whether Enterprise Analytics verifies the IdP's certificate when fetching metadata. Only has an effect if idpMetadataOrigin is http or http\_one\_time. If set to true, Enterprise Analytics verifies the certificate. If it cannot verify the certificate, it returns an error. | | idpMetadataURL | The URL from which Enterprise Analytics retrieves the IdP's metadata. Only has an effect if idpMetadataOrigin is http or http\_one\_time. | | idpSignsMetadata | A Boolean that tells Enterprise Analytics if the IdP cryptographically signs its metadata. If the IdP signs its metadata, Enterprise Analytics attempts to verify the signature. It returns an error if this verification fails. | | rolesAttribute | The name of a SAML attribute containing the roles that Enterprise Analytics should apply to the authenticated user. Defaults to an empty string, which has Enterprise Analytics use its own list of roles from the user's Enterprise Analytics account. | | rolesAttributeSep | A list of characters that separate role names. Set this value if the IdP sends a list of role names in the SAML attribute you have mapped to Couchbase roles. Defaults to " ," which means roles can be separated by a space, a comma, or combinations of the two characters. Enterprise Analytics allows the string to use multiple characters to separate role names. For example, suppose the SAML attribute contains the string "role1,role2, role3 role4.subrole". Then when using the default setting, Enterprise Analytics splits the string into four roles: role1, role2, role3 and role4.subrole. Only has an effect if rolesAttribute has a value. | | rolesFilterRE | A regular expression for Enterprise Analytics to use to filter role names sent in a SAML attribute. Enterprise Analytics only grants the roles whose names match the regular expression to the user. Defaults to .\* which allows all groups in the SAML attribute. | | singleLogoutEnabled | A Boolean that controls whether the user is able to log out of both Web Console and their IdP session at once. Defaults to true which logs users out of the IdP session when they log out of the Web Console. | | spAssertionDupeCheck | A Boolean value that controls whether Enterprise Analytics lets users reuse authentication credentials. See [SP Assertion Dupe Check](../manage/manage-security/configure-saml.md#dupe-check) for a description of this parameter's values. | | spBaseURLScheme | The scheme that Enterprise Analytics uses when generating the URLs for spMetadataURL, spConsumeURL, and spLogoutURL. Can be either the default http for unencrypted connections to Enterprise Analytics or https for encrypted connections. | | spBaseURLType | Sets how Enterprise Analytics determines the host name it uses when generating the URLs for spMetadataURL, spConsumeURL, and spLogoutURL. See [SP Base URL Type](../manage/manage-security/configure-saml.md#sp-base-url) for a description of this parameter's values. Defaults to node. | | spCertificate | The public certificate that the IdP uses to verify the authenticity of Enterprise Analytics's requests in PEM format. The public key you supply must correspond to the private key you supply in spKey. You must set this value to enable SAML authentication. | | spChain | One or more certificates in PEM format used to sign the Enterprise Analytics's certificate. Supply this value if Enterprise Analytics's certificate was not directly signed by a well-known signing authority. | | spConsumeURL | A read-only value for your Enterprise Analytics's SAML ACS endpoint. This is the URL the IdP posts SAML messages to. Enterprise Analytics automatically generates this value based on the contents of spBaseURLScheme, spBaseURLType, and spCustomBaseURL. | | spContactEmail | A contact email address for the administrator responsible for Enterprise Analytics's SAML integration. | | spContactName | The name of the administrator responsible for Enterprise Analytics's SAML integration. | | spEntityId | The identifier Enterprise Analytics uses when exchanging SAML messages with the IdP. It defaults to the URL for Enterprise Analytics's SAML metadata. The actual content of the field is not important as long as the IdP recognizes the identifier. | | spKey | The private key Enterprise Analytics uses to sign and encrypt SAML messages in PEM format. You must supply a private key to enable SAML authentication. This parameter is write-only. A GET request only returns a string of asterisks for this value. | | spLogoutURL | Read-only value containing the SAML logout endpoint for Enterprise Analytics. This is the URL the IdP uses to log users out of the Web Console. Enterprise Analytics sets this value based on spBaseURLScheme, spCustomBaseURL, and spBaseURLType. | | spMetadataCacheDuration | Sets how long the IdP should cache Enterprise Analytics's metadata. This value sets the CacheDuration attribute in Enterprise Analytics's metadata that the IdP can retrieve from the URL in spMetadataURL. This value is in [ISO8601 duration format](https://en.wikipedia.org/wiki/ISO%5F8601#Durations). The default value P1M sets this duration to one month. | | spMetadataURL | Read-only value containing the URL for Enterprise Analytics's SAML metadata. This metadata can be used to configure the IdP to exchange SAML messages with Enterprise Analytics. Enterprise Analytics sets this value based on spBaseURLScheme, spCustomBaseURL, and spBaseURLType. | | spOrgDisplayName | An alternate name of your organization. The IdP can use this value for various purposes, such as when prompting a user to authenticate. | | spOrgName | The name of your organization. The IdP can use this value for various purposes, such as when prompting a user to authenticate. | | spOrgURL | A URL for your organization. This value does not play a role in authentication. The IdP can use this value for various purposes, such as when prompting a user to authenticate. | | spSessionExpire | String value that controls whether the Enterprise Analytics Web Console expires its session when the IdP's authorization expires. When set to the default SessionNotOnOrAfter value, the Web Console forces the user to reauthenticate based on the SessionNotOnOrAfter attribute in the SAML assertion's AuthStatement element. If set to false, the Web Console does not set its session length to match the IdP's authentication expiration. | | spSignMetadata | A Boolean value that controls whether Enterprise Analytics signs its metadata using the key set in spKey. Defaults to true, which enables signing the metadata. | | spSignRequests | A Boolean value that controls whether Enterprise Analytics signs its SAML requests to the IdP. Defaults to true which enables signing the requests. | | spTrustedFingerprints | One or more certificate fingerprints that Enterprise Analytics can use to verify messages from the IdP. It uses these fingerprints instead of using a certificate embedded in the IdP's metadata. | | spTrustedFingerprintsUsage | String value that controls what Enterprise Analytics verifies using certificate fingerprints. Can be one of three values: metadataOnly: Enterprise Analytics always uses the fingerprints to verify the signatures in the IdP's metadata every time it updates the metadata. metadataInitialOnly: Enterprise Analytics uses the fingerprints to verify the signatures in the IdP's metadata the first time it retrieves the metadata. Afterwards, when updating the metadata Enterprise Analytics uses the certificate from the previously retrieved copy of the metadata to verify its signature. everything: Enterprise Analytics uses the fingerprints to verify the signatures in all SAML messages. It never uses the certificate in the IdP's metadata. | | spVerifyAssertionEnvelopSig | A Boolean value. When set to true, Enterprise Analytics verifies the IdP's signature on the entire SAML message envelope. | | spVerifyAssertionSig | A Boolean value. When set to the default true value, Enterprise Analytics verifies the IdP's signature on the assertion portion of SAML messages. | | spVerifyLogoutReqSig | A Boolean value. When set to true, Enterprise Analytics verifies the IdP's signature on SAML logout requests. | | spVerifyRecipient | Controls whether Enterprise Analytics verifies a SAML message is addressed to it by comparing the SAML recipient with its own recipient name. Its value is one of the following: The string consumeURL: the default value which has Enterprise Analytics verify that the recipient set in the SAML message matches the value in spConsumeURL (its own consume URL). Boolean false: Enterprise Analytics does not verify the recipient and just processes the SAML message. The string custom: Enterprise Analytics compares the recipient set in the SAML message to the value set in spVerifyRecipientValue\` to verify the SAML recipient. | | spVerifyRecipientValue | If spVerifyRecipient is custom, this parameter sets the recipient name that Enterprise Analytics looks for in SAML messages. | | usernameAttribute | The name of a SAML attribute that Enterprise Analytics uses as the username of the user who authenticated with the IdP. If you do not supply a value for this parameter, Enterprise Analytics extracts the username from the nameID in the SAML message. |