Create authentication settings for IdP SSO or metadata URL

post /public_api/v1/authentication-settings/create

Create authentication settings for IdP SSO or metadata URL. You must include either the metadata_url field or all of the following fields: idp_sso_url, idp_issuer, and idp_certificate.

You must have Instance Administrator permissions to run this endpoint.

Request headers

Authorization

String

required

{api_key}

Example: authorization_example

x-xdr-auth-id

String

required

{api_key_id}

Example: xXdrAuthId_example

Body parameters

request_dataObjectrequired

nameString

The name of the SSO integration.

default_roleString

The default role automatically assigned to every user who authenticates to Cortex using SAML. This is an inherited role and is not the same as a direct role assigned to the user.

If a role with the same name exists on both Cortex Gateway and the tenant, the role will mapped to the role from the tenant. If you want to use specifically the role from Cortex Gateway, use the is_account_role parameter set to true.

is_account_roleBoolean

Whether the role was created in Cortex Gateway or in the tenant. When the value is true, the role was created in Cortex Gateway.

domainString

When configuring the first SSO, this parameter should be included as empty because it is the default SSO and has a fixed, read-only value. For additional SSOs, specify this IdP with an email domain (user@). When logging in, users are redirected to the IdP associated with their email domain or to the default IdP if no association exists.

mappingsObjectrequired

These IdP attribute mappings are dependent on your organization’s IdP.

emailString

The IdP attribute mapped to the user's email address in the Syslog server.

firstnameString

The IdP attribute mapped to the user's first name.

lastnameString

The IdP attribute mapped to the user's last name.

group_nameString

The IdP attribute mapped to the user's group membership for authorization.

Note: Cortex requires the IdP to send the group membership as part of the SAML token. Some IdPs send values in a format that include a comma, which is not compatible with Cortex. In that case, you must configure your IdP to send a single value without a comma for each group membership. For example, if your IdP sends the Group DN (a comma-separated list), by default, you must configure IdP to send the Group CN (Common Name) instead.

advanced_settingsObject

The advanced settings are optional to configure and some are specific for a particular IdP.

relay_stateString

The URL for a specific page that you want users to be directed to after they've been authenticated by your organization's IdP and log in to Cortex.

idp_single_logout_urlString

The URL of the IdP's Single Logout endpoint. This ensures that when a user initiates a logout from Cortex, the identity provider logs the user out of all applications in the current identity provider login session.

service_provider_public_certString

The Syslog server's public X.509 certificate in PEM format for IdP validation.

service_provider_private_keyString

The Syslog server's private key in PEM format for signing SAML responses. (This is mostly required for ADFS)

authn_context_enabledBoolean

Whether to remove the RequestedAuthnContext parameter from SAML requests. If true, allows users to log in by using additional authentication methods.

force_authnBoolean

Whether to force users to reauthenticate to access the Cortex tenant if requested by the IdP, even if they already authenticated to access other applications.

idp_sso_urlString

The login URL of your IdP and should be copied from your SAML integration configuration on the IdP. For example: - Okta: https://cortex-test.okta.com/app/cortex-test/eacbt6b2jj08CasdUQ7sdf15d7/sso/SAML - Microsoft Azure: https://login.microsoftonline.com/6a5a9780-96a4-41ef-bf45-0535d8a70025/saml2

idp_certificateString

The Idp's public X.509 digital certificate in PEM format for verification, which is copied from your organization's IdP.

idp_issuerString

The unique identifier of the IdP issuing SAML assertions, which is copied from your organization's IdP.

metadata_urlString

The metadata URL provides information about hte IdP's capabilities, endpoints, keys, and more. For example: - Okta: https://cortex-test.okta.com/app/exkbuuzw77Bh04V6M6b8/sso/saml/metadata - Microsoft Azure: https://login.microsoftonline.com/6a5a9780-96a4-41ef-bf45-0535d8a70025/saml2/metadata

REQUEST BODY

{
  "request_data": {
    "name": "IdP configuration",
    "default_role": "Analyst",
    "domain": "my-test-domain.com",
    "mappings": {
      "email": "user@company.com",
      "firstname": "John",
      "lastname": "Smith",
      "group_name": "analysts"
    },
    "idp_sso_url": "https://cortex-test.okta.com/app/cortex-test/xxxxxxx/sso/SAML",
    "idp_certificate": "MY_CERTIFICATE_FROM_OKTA",
    "idp_issuer": "https://cortex-test.okta.com/idp",
    "advanced_settings": {},
    "is_account_role": true
  }
}

CURL

  curl -X 'POST'

        -H
        'Accept: application/json'
      
        -H
        'Content-Type: application/json'
      
          -H
          'Authorization: authorization_example'
          -H
          'x-xdr-auth-id: xXdrAuthId_example'
      
      'https://api-yourfqdn/public_api/v1/authentication-settings/create'
    
      -d
      ''

Responses

Body

replyBoolean

RESPONSE

{
  "reply": true
}

Bad Request. Got an invalid JSON.

Body

err_codeString

HTTP response code.

err_msgString

Error message.

Example:"{\"line\": 1, \"column\": 19, \"message\": \"no viable alternative at input '|alter2'\"}"

err_extraString

Additional information describing the error.

RESPONSE

{
  "err_code": "err_code_example",
  "err_msg": "{\"line\": 1, \"column\": 19, \"message\": \"no viable alternative at input '|alter2'\"}",
  "err_extra": "err_extra_example"
}

Unauthorized access. An issue occurred during authentication. This can indicate an incorrect key, id, or other invalid authentication parameters.

Body

err_codeString

HTTP response code.

err_msgString

Error message.

Example:"{\"line\": 1, \"column\": 19, \"message\": \"no viable alternative at input '|alter2'\"}"

err_extraString

Additional information describing the error.

RESPONSE

{
  "err_code": "err_code_example",
  "err_msg": "{\"line\": 1, \"column\": 19, \"message\": \"no viable alternative at input '|alter2'\"}",
  "err_extra": "err_extra_example"
}

Unauthorized access. User does not have the required license type to run this API.

Body

err_codeString

HTTP response code.

err_msgString

Error message.

Example:"{\"line\": 1, \"column\": 19, \"message\": \"no viable alternative at input '|alter2'\"}"

err_extraString

Additional information describing the error.

RESPONSE

{
  "err_code": "err_code_example",
  "err_msg": "{\"line\": 1, \"column\": 19, \"message\": \"no viable alternative at input '|alter2'\"}",
  "err_extra": "err_extra_example"
}

Forbidden access. The provided API Key does not have the required RBAC permissions to run this API.

Body

err_codeString

HTTP response code.

err_msgString

Error message.

Example:"{\"line\": 1, \"column\": 19, \"message\": \"no viable alternative at input '|alter2'\"}"

err_extraString

Additional information describing the error.

RESPONSE

{
  "err_code": "err_code_example",
  "err_msg": "{\"line\": 1, \"column\": 19, \"message\": \"no viable alternative at input '|alter2'\"}",
  "err_extra": "err_extra_example"
}

Internal server error. A unified status for API communication type errors.

Body

err_codeString

HTTP response code.

err_msgString

Error message.

Example:"{\"line\": 1, \"column\": 19, \"message\": \"no viable alternative at input '|alter2'\"}"

err_extraString

Additional information describing the error.

RESPONSE

{
  "err_code": "err_code_example",
  "err_msg": "{\"line\": 1, \"column\": 19, \"message\": \"no viable alternative at input '|alter2'\"}",
  "err_extra": "err_extra_example"
}