Configure SAML

You can configure Enterprise Analytics to authenticate an Enterprise Analytics Web Console user via a SAML Identity Provider.

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 /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 <administrator>:<password>
    http://<host>:<port>/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 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 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 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. 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.