Configure SAML

You can configure Operational Insights to authenticate an Operational Insights Web Console user via a SAML Identity Provider.

GET /settings/saml

Description

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