Configure SAML

You can configure Couchbase Server to authenticate a Couchbase Server Web Console user via a SAML Identity Provider.

GET /settings/saml

Description

Returns Couchbase Server’s Security Assertion Markup Language (SAML) settings as JSON object.

Example

curl -s -u Administrator:password \
     http://localhost:8091/settings/saml | jq -S

{
    "authnNameIDFormat": "urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified",
    "enabled": true,
    "groupsAttribute": "groups",
    "groupsAttributeSep": " ,",
    "groupsFilterRE": ".*",
    "idpAuthnBinding": "redirect",
    "idpLogoutBinding": "redirect",
    "idpMetadataConnectAddressFamily": "undefined",
    "idpMetadataHttpTimeoutMs": 5000,
    "idpMetadataOrigin": "https",
    "idpMetadataRefreshIntervalS": 3600,
    "idpMetadataTLSCAs": "-----BEGIN CERTIFICATE-----\n
    . . .
    \n-----END CERTIFICATE-----",
    "idpMetadataTLSExtraOpts": "[]",
    "idpMetadataTLSSNI": "",
    "idpMetadataTLSVerifyPeer": false,
    "idpMetadataURL": "https://exampleco.okta.com/app/abcdef1234/sso/saml/metadata",
    "idpSignsMetadata": false,
    "rolesAttribute": "",
    "rolesAttributeSep": " ,",
    "rolesFilterRE": ".*",
    "singleLogoutEnabled": false,
    "spAssertionDupeCheck": "disabled",
    "spBaseURLScheme": "http",
    "spBaseURLType": "node",
    "spCertificate": "-----BEGIN CERTIFICATE-----\n
    . . .
    \n-----END CERTIFICATE-----\n",
    "spChain": "",
    "spConsumeURL": "https://cb_node.example.com:8091/saml/consume",
    "spContactEmail": "my_name@example.org",
    "spContactName": "SAML Admin",
    "spEntityId": "https://cb_node.example.com:8091/saml/metadata",
    "spKey": "**********",
    "spLogoutURL": "https://cb_node.example.com:8091/saml/logout",
    "spMetadataCacheDuration": "P1M",
    "spMetadataURL": "https://cb_node.example.com:8091/saml/metadata",
    "spOrgDisplayName": "Example Co.",
    "spOrgName": "Example Co., a division of United Samples Ltd.",
    "spOrgURL": " https://example.com",
    "spSessionExpire": "SessionNotOnOrAfter",
    "spSignMetadata": true,
    "spSignRequests": true,
    "spTrustedFingerprints": [],
    "spTrustedFingerprintsUsage": "metadataInitialOnly",
    "spVerifyAssertionEnvelopSig": true,
    "spVerifyAssertionSig": true,
    "spVerifyLogoutReqSig": false,
    "spVerifyRecipient": false
  }

POST /settings/saml

Description

Updates Couchbase Server’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 Couchbase Server’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. Couchbase Server 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 Couchbase Server needs to interact with the IdP. Therefore, the curl command has no further IdP parameters.

curl -X POST -u Administrator:password \
http://localhost:8091/settings/saml \
-d enabled=true \
-d idpMetadataTLSVerifyPeer=false \
-d idpMetadataURL=https://myidp.com/sso/saml/metadata \
-d spBaseURLScheme=http  \
-d spBaseURLType=node \
--data-urlencode spCertificate@my_certificate.crt 
--data-urlencode spKey@my_key.pem 
-d idpSignsMetadata=false

{
    "authnNameIDFormat": "urn:oasis:names:tc:SAML:2.0:nameid-format:persistent",
    "enabled": true,
    "groupsAttribute": "",
    "groupsAttributeSep": " ,",
    "groupsFilterRE": ".*",
    "idpAuthnBinding": "post",
    "idpLogoutBinding": "post",
    "idpMetadataConnectAddressFamily": "undefined",
    "idpMetadataHttpTimeoutMs": 5000,
    "idpMetadataOrigin": "http",
    "idpMetadataRefreshIntervalS": 3600,
    "idpMetadataTLSCAs": "",
    "idpMetadataTLSExtraOpts": "[]",
    "idpMetadataTLSSNI": "",
    "idpMetadataTLSVerifyPeer": false,
    "idpMetadataURL": "https://myidp.com/sso/saml/metadata",
    "idpSignsMetadata": false,
    "rolesAttribute": "",
    "rolesAttributeSep": " ,",
    "rolesFilterRE": ".*",
    "singleLogoutEnabled": true,
    "spAssertionDupeCheck": "global",
    "spBaseURLScheme": "http",
    "spBaseURLType": "node",
    "spCertificate": "-----BEGIN CERTIFICATE-----\n
    ...
    \n-----END CERTIFICATE-----\n",
    "spChain": "",
    "spConsumeURL": "http://nodename.example.com:8091/saml/consume",
    "spContactEmail": "",
    "spContactName": "",
    "spEntityId": "",
    "spKey": "**********",
    "spLogoutURL": "http://nodename.example.com:8091/saml/logout",
    "spMetadataCacheDuration": "P1M",
    "spMetadataURL": "http://nodename.example.com:8091/saml/metadata",
    "spOrgDisplayName": "",
    "spOrgName": "",
    "spOrgURL": "",
    "spSessionExpire": "SessionNotOnOrAfter",
    "spSignMetadata": true,
    "spSignRequests": true,
    "spTrustedFingerprints": [],
    "spTrustedFingerprintsUsage": "metadataInitialOnly",
    "spVerifyAssertionEnvelopSig": true,
    "spVerifyAssertionSig": true,
    "spVerifyLogoutReqSig": true,
    "spVerifyRecipient": "consumeURL",
    "usernameAttribute": ""
}

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 Couchbase Server use the list of groups defined for users in their Couchbase Server 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. Couchbase Server 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, Couchbase Server 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 Couchbase Server uses to filter the group names the IdP sends in a SAML attribute. Couchbase Server 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 Couchbase Server 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 Couchbase Server 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 Couchbase Server get the IdP’s metadata. Can have one of three values: * `http`: Couchbase Server downloads the IdP’s metadata from the URL in `idpMetadataURL` periodically. The `idpMetadataRefreshIntervalS` setting controls how often Couchbase Server fetches the metadata. * `http_one_time`: Couchbase Server 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 Couchbase Server 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 Couchbase Server 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 Couchbase Server 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 Couchbase Server to the IdP to retrieve the metadata.
idpMetadataTLSVerifyPeer	A Boolean value that controls whether Couchbase Server verifies the IdP’s certificate when fetching metadata. Only has an effect if `idpMetadataOrigin` is `http` or `http_one_time`. If set to `true`, Couchbase Server verifies the certificate. If it cannot verify the certificate, it returns an error.
idpMetadataURL	The URL from which Couchbase Server retrieves the IdP’s metadata. Only has an effect if `idpMetadataOrigin` is `http` or `http_one_time`.
idpSignsMetadata	A Boolean that tells Couchbase Server if the IdP cryptographically signs its metadata. If the IdP signs its metadata, Couchbase Server attempts to verify the signature. It returns an error if this verification fails.
rolesAttribute	The name of a SAML attribute containing the roles that Couchbase Server should apply to the authenticated user. Defaults to an empty string, which has Couchbase Server use its own list of roles from the user’s Couchbase Server 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. Couchbase Server 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, Couchbase Server 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 Couchbase Server to use to filter role names sent in a SAML attribute. Couchbase Server 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 Couchbase Server lets users reuse authentication credentials. See SP Assertion Dupe Check for a description of this parameter’s values.
spBaseURLScheme	The scheme that Couchbase Server uses when generating the URLs for `spMetadataURL`, `spConsumeURL`, and `spLogoutURL`. Can be either the default `http` for unencrypted connections to Couchbase Server or `https` for encrypted connections.
spBaseURLType	Sets how Couchbase Server 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 Couchbase Server’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 Couchbase Server’s certificate. Supply this value if Couchbase Server’s certificate was not directly signed by a well-known signing authority.
spConsumeURL	A read-only value for your Couchbase Server’s SAML ACS endpoint. This is the URL the IdP posts SAML messages to. Couchbase Server automatically generates this value based on the contents of `spBaseURLScheme`, `spBaseURLType`, and `spCustomBaseURL`.
spContactEmail	A contact email address for the administrator responsible for Couchbase Server’s SAML integration.
spContactName	The name of the administrator responsible for Couchbase Server’s SAML integration.
spEntityId	The identifier Couchbase Server uses when exchanging SAML messages with the IdP. It defaults to the URL for Couchbase Server’s SAML metadata. The actual content of the field is not important as long as the IdP recognizes the identifier.
spKey	The private key Couchbase Server 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 Couchbase Server. This is the URL the IdP uses to log users out of the Web Console. Couchbase Server sets this value based on `spBaseURLScheme`, `spCustomBaseURL`, and `spBaseURLType`.
spMetadataCacheDuration	Sets how long the IdP should cache Couchbase Server’s metadata. This value sets the `CacheDuration` attribute in Couchbase Server’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 Couchbase Server’s SAML metadata. This metadata can be used to configure the IdP to exchange SAML messages with Couchbase Server. Couchbase Server 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 Couchbase Server 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 Couchbase Server signs its metadata using the key set in spKey. Defaults to `true`, which enables signing the metadata.
spSignRequests	A Boolean value that controls whether Couchbase Server signs its SAML requests to the IdP. Defaults to `true` which enables signing the requests.
spTrustedFingerprints	One or more certificate fingerprints that Couchbase Server 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 Couchbase Server verifies using certificate fingerprints. Can be one of three values: `metadataOnly`: Couchbase Server always uses the fingerprints to verify the signatures in the IdP’s metadata every time it updates the metadata. `metadataInitialOnly`: Couchbase Server uses the fingerprints to verify the signatures in the IdP’s metadata the first time it retrieves the metadata. Afterwards, when updating the metadata Couchbase Server uses the certificate from the previously retrieved copy of the metadata to verify its signature. `everything`: Couchbase Server 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`, Couchbase Server verifies the IdP’s signature on the entire SAML message envelope.
spVerifyAssertionSig	A Boolean value. When set to the default `true` value, Couchbase Server verifies the IdP’s signature on the assertion portion of SAML messages.
spVerifyLogoutReqSig	A Boolean value. When set to `true`, Couchbase Server verifies the IdP’s signature on SAML logout requests.
spVerifyRecipient	Controls whether Couchbase Server 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 Couchbase Server verify that the recipient set in the SAML message matches the value in `spConsumeURL` (its own consume URL). Boolean `false`: Couchbase Server does not verify the recipient and just processes the SAML message. The string `custom`: Couchbase Server 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 Couchbase Server looks for in SAML messages.
usernameAttribute	The name of a SAML attribute that Couchbase Server uses as the username of the user who authenticated with the IdP. If you do not supply a value for this parameter, Couchbase Server extracts the username from the nameID in the SAML message.