> For the complete documentation index, see [llms.txt](https://cortex-docs.paloaltonetworks.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://cortex-docs.paloaltonetworks.com/xsoar-8-api/cortex-xsoar-8.x-apis/authentication-settings.md).

# Authentication Settings

APIs for authentication settings, such as IdP and SSO

## Create authentication settings for IdP SSO or metadata URL

> 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.

```json
{"openapi":"3.0.1","info":{"title":"Cortex XSOAR 8 API","version":"XSOAR 8 Cloud"},"tags":[{"name":"Authentication settings","description":"APIs for authentication settings, such as IdP and SSO"}],"servers":[{"url":"https://api-yourfqdn","description":""}],"paths":{"/public_api/v1/authentication-settings/create":{"post":{"summary":"Create authentication settings for IdP SSO or metadata URL","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"reply":{"type":"boolean"}}}}}},"400":{"description":"Bad Request. Got an invalid JSON.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/reply"}}}},"401":{"description":"Unauthorized access. An issue occurred during authentication. This can indicate an incorrect key, id, or other invalid authentication parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/reply"}}}},"402":{"description":"Unauthorized access. User does not have the required license type to run this API.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/reply"}}}},"403":{"description":"Forbidden access. The provided API Key does not have the required RBAC permissions to run this API.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/reply"}}}},"500":{"description":"Internal server error. A unified status for API communication type errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/reply"}}}}},"operationId":"post-public_api-v1-authentication-settings-create","parameters":[{"schema":{"type":"string"},"in":"header","name":"Authorization","description":"{api_key}","required":true},{"schema":{"type":"string"},"in":"header","name":"x-xdr-auth-id","description":"{api_key_id}","required":true}],"description":"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`.\n\nYou must have **Instance Administrator** permissions to run this endpoint.","tags":["Authentication settings"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["request_data"],"properties":{"request_data":{"type":"object","required":["name","mappings"],"properties":{"name":{"type":"string","description":"The name of the SSO integration."},"default_role":{"type":"string","description":"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.\n\nIf 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_role":{"type":"boolean","default":false,"description":"Whether the role was created in Cortex Gateway or in the tenant. When the value is `true`, the role was created in Cortex Gateway."},"domain":{"type":"string","description":"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. \nFor additional SSOs, specify this IdP with an email domain (user@<domain>). When logging in, users are redirected to the IdP associated with their email domain or to the default IdP if no association exists."},"mappings":{"type":"object","description":"These IdP attribute mappings are dependent on your organization's IdP.","required":["email","firstname","lastname","group_name"],"properties":{"email":{"type":"string","description":"The IdP attribute mapped to the user's email address in the Syslog server."},"firstname":{"type":"string","description":"The IdP attribute mapped to the user's first name."},"lastname":{"type":"string","description":"The IdP attribute mapped to the user's last name."},"group_name":{"type":"string","description":"The IdP attribute mapped to the user's group membership for authorization.\n\n**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_settings":{"type":"object","description":"The advanced settings are optional to configure and some are specific for a particular IdP.","properties":{"relay_state":{"type":"string","description":"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_url":{"type":"string","description":"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_cert":{"type":"string","description":"The Syslog server's public X.509 certificate in PEM format for IdP validation."},"service_provider_private_key":{"type":"string","description":"The Syslog server's private key in PEM format for signing SAML responses. (This is mostly required for ADFS)"},"authn_context_enabled":{"type":"boolean","default":false,"description":"Whether to remove the `RequestedAuthnContext` parameter from SAML requests.\nIf `true`, allows users to log in by using additional authentication methods."},"force_authn":{"type":"boolean","default":false,"description":"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_url":{"type":"string","description":"The login URL of your IdP and should be copied from your SAML integration configuration on the IdP.\nFor example:\n- Okta: https://cortex-test.okta.com/app/cortex-test/eacbt6b2jj08CasdUQ7sdf15d7/sso/SAML\n- Microsoft Azure: https://login.microsoftonline.com/6a5a9780-96a4-41ef-bf45-0535d8a70025/saml2"},"idp_certificate":{"type":"string","description":"The Idp's public X.509 digital certificate in PEM format for verification, which is copied from your organization's IdP."},"idp_issuer":{"type":"string","description":"The unique identifier of the IdP issuing SAML assertions, which is copied from your organization's IdP."},"metadata_url":{"type":"string","description":"The metadata URL provides information about hte IdP's capabilities, endpoints, keys, and more. \nFor example: \n- Okta: https://cortex-test.okta.com/app/exkbuuzw77Bh04V6M6b8/sso/saml/metadata\n- Microsoft Azure: https://login.microsoftonline.com/6a5a9780-96a4-41ef-bf45-0535d8a70025/saml2/metadata"}}}}}}}}}}},"components":{"schemas":{"reply":{"title":"reply","type":"object","properties":{"err_code":{"type":"string","description":"HTTP response code."},"err_msg":{"type":"string","description":"Error message."},"err_extra":{"type":"string","description":"Additional information describing the error."}},"description":"The query result upon error."}}}}
```

## Update authentication settings

> Update existing authentication settings. To update the default domain, include empty value for both \`current\_domain\_value\` and \`new\_domain\_value\`.\
> \
> You must have \*\*Instance Administrator\*\* permissions to run this endpoint.

```json
{"openapi":"3.0.1","info":{"title":"Cortex XSOAR 8 API","version":"XSOAR 8 Cloud"},"tags":[{"name":"Authentication settings","description":"APIs for authentication settings, such as IdP and SSO"}],"servers":[{"url":"https://api-yourfqdn","description":""}],"paths":{"/public_api/v1/authentication-settings/update":{"post":{"summary":"Update authentication settings","tags":["Authentication settings"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["request_data"],"properties":{"request_data":{"type":"object","required":["name","mappings"],"properties":{"name":{"type":"string","description":"The name of the SSO integration."},"default_role":{"type":"string","description":"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.\n\nIf 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_role":{"type":"boolean","default":false,"description":"Whether the role was created in Cortex Gateway or in the tenant. When the value is `true`, the role was created in Cortex Gateway."},"current_domain_value":{"type":"string","description":"The domain whose authentication settings you want to update."},"new_domain_value":{"type":"string","description":"If you want to update the domain value, include a new unique domain."},"mappings":{"type":"object","description":"These IdP attribute mappings are dependent on your organization's IdP.","required":["email","firstname","lastname","group_name"],"properties":{"email":{"type":"string","description":"The IdP attribute mapped to the user's email address in the Syslog server."},"firstname":{"type":"string","description":"The IdP attribute mapped to the user's first name."},"lastname":{"type":"string","description":"The IdP attribute mapped to the user's last name."},"group_name":{"type":"string","description":"The IdP attribute mapped to the user's group membership for authorization.\n\n**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_settings":{"type":"object","description":"The advanced settings are optional to configure and some are specific for a particular IdP.","properties":{"relay_state":{"type":"string","description":"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_url":{"type":"string","description":"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_cert":{"type":"string","description":"The Syslog server's public X.509 certificate in PEM format for IdP validation."},"service_provider_private_key":{"type":"string","description":"The Syslog server's private key in PEM format for signing SAML responses. (This is mostly required for ADFS)"},"authn_context_enabled":{"type":"boolean","default":false,"description":"Whether to remove the `RequestedAuthnContext` parameter from SAML requests.\nIf `true`, allows users to log in by using additional authentication methods."},"force_authn":{"type":"boolean","default":false,"description":"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_url":{"type":"string","description":"The URL of your IdP's SSO, which is a fixed, read-only value based on your tenant's URL. If you are using this parameter, you must also specify: `idp_certificate` and `idp_issuer`."},"idp_certificate":{"type":"string","description":"The Idp's public X.509 digital certificate in PEM format for verification, which is copied from your organization's IdP."},"idp_issuer":{"type":"string","description":"The unique identifier of the IdP issuing SAML assertions, which is copied from your organization's IdP."},"metadata_url":{"type":"string","description":"Specify your IdP SSO URL, which is a fixed, read-only value based on your tenant's URL."}}}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"reply":{"type":"boolean"}}}}}},"400":{"description":"Bad Request. Got an invalid JSON.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/reply"}}}},"401":{"description":"Unauthorized access. An issue occurred during authentication. This can indicate an incorrect key, id, or other invalid authentication parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/reply"}}}},"402":{"description":"Unauthorized access. User does not have the required license type to run this API.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/reply"}}}},"403":{"description":"Forbidden access. The provided API Key does not have the required RBAC permissions to run this API.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/reply"}}}},"500":{"description":"Internal server error. A unified status for API communication type errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/reply"}}}}},"operationId":"post-public_api-v1-authentication-settings-update","parameters":[{"schema":{"type":"string"},"in":"header","name":"Authorization","description":"{api_key}","required":true},{"schema":{"type":"string"},"in":"header","name":"x-xdr-auth-id","description":"{api_key_id}","required":true}],"description":"Update existing authentication settings. To update the default domain, include empty value for both `current_domain_value` and `new_domain_value`.\n\nYou must have **Instance Administrator** permissions to run this endpoint."}}},"components":{"schemas":{"reply":{"title":"reply","type":"object","properties":{"err_code":{"type":"string","description":"HTTP response code."},"err_msg":{"type":"string","description":"Error message."},"err_extra":{"type":"string","description":"Additional information describing the error."}},"description":"The query result upon error."}}}}
```

## Delete authentication settings by domain

> Delete all authentication settings for the specified domain. \
> \
> \*\*Note:\*\* The first configuration on the tenant is the default configuration and cannot be deleted.\
> \
> You must have \*\*Instance Administrator\*\* permissions to run this endpoint.

```json
{"openapi":"3.0.1","info":{"title":"Cortex XSOAR 8 API","version":"XSOAR 8 Cloud"},"tags":[{"name":"Authentication settings","description":"APIs for authentication settings, such as IdP and SSO"}],"servers":[{"url":"https://api-yourfqdn","description":""}],"paths":{"/public_api/v1/authentication-settings/delete":{"post":{"summary":"Delete authentication settings by domain","tags":["Authentication settings"],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"reply":{"type":"boolean"}}}}}},"400":{"description":"Bad Request. Got an invalid JSON.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/reply"}}}},"401":{"description":"Unauthorized access. An issue occurred during authentication. This can indicate an incorrect key, id, or other invalid authentication parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/reply"}}}},"402":{"description":"Unauthorized access. User does not have the required license type to run this API.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/reply"}}}},"403":{"description":"Forbidden access. The provided API Key does not have the required RBAC permissions to run this API.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/reply"}}}},"500":{"description":"Internal server error. A unified status for API communication type errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/reply"}}}}},"operationId":"post-public_api-v1-authentication-settings-delete","parameters":[{"schema":{"type":"string"},"in":"header","name":"Authorization","description":"{api_key}","required":true},{"schema":{"type":"string"},"in":"header","name":"x-xdr-auth-id","description":"{api_key_id}","required":true}],"description":"Delete all authentication settings for the specified domain. \n\n**Note:** The first configuration on the tenant is the default configuration and cannot be deleted.\n\nYou must have **Instance Administrator** permissions to run this endpoint.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"request_data":{"type":"object","properties":{"domain":{"type":"string","description":"The domain whose authentication settings you want to delete."}}}}}}}}}}},"components":{"schemas":{"reply":{"title":"reply","type":"object","properties":{"err_code":{"type":"string","description":"HTTP response code."},"err_msg":{"type":"string","description":"Error message."},"err_extra":{"type":"string","description":"Additional information describing the error."}},"description":"The query result upon error."}}}}
```

## Get authentication settings for all configured domains

> Get all the authentication settings for every configured domain in the tenant.\
> \
> You must have \*\*Instance Administrator\*\* permissions to run this endpoint.<br>

```json
{"openapi":"3.0.1","info":{"title":"Cortex XSOAR 8 API","version":"XSOAR 8 Cloud"},"tags":[{"name":"Authentication settings","description":"APIs for authentication settings, such as IdP and SSO"}],"servers":[{"url":"https://api-yourfqdn","description":""}],"paths":{"/public_api/v1/authentication-settings/get/settings":{"post":{"summary":"Get authentication settings for all configured domains","tags":["Authentication settings"],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"reply":{"type":"array","items":{"type":"object","properties":{"tenant_id":{"type":"string"},"name":{"type":"string"},"domain":{"type":"string"},"idp_enabled":{"type":"boolean"},"default_role":{"type":"null"},"is_account_role":{"type":"null"},"idp_certificate":{"type":"string"},"idp_issuer":{"type":"string"},"idp_sso_url":{"type":"string"},"metadata_url":{"type":"string"},"mappings":{"type":"object","properties":{"email":{"type":"string"},"firstname":{"type":"string"},"group_name":{"type":"string"},"lastname":{"type":"string"}}},"advanced_settings":{"type":"object","properties":{"authn_context_enabled":{"type":"boolean"},"force_authn":{"type":"null"},"idp_single_logout_url":{"type":"string"},"relay_state":{"type":"string"},"service_provider_private_key":{"type":"string"},"service_provider_public_cert":{"type":"string"}}},"sp_entity_id":{"type":"string"},"sp_logout_url":{"type":"string"},"sp_url":{"type":"string"}}}}}}}}},"400":{"description":"Bad Request. Got an invalid JSON.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/reply"}}}},"401":{"description":"Unauthorized access. An issue occurred during authentication. This can indicate an incorrect key, id, or other invalid authentication parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/reply"}}}},"402":{"description":"Unauthorized access. User does not have the required license type to run this API.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/reply"}}}},"403":{"description":"Forbidden access. The provided API Key does not have the required RBAC permissions to run this API.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/reply"}}}},"500":{"description":"Internal server error. A unified status for API communication type errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/reply"}}}}},"operationId":"post-public_api-v1-authentication-settings-get-settings","parameters":[{"schema":{"type":"string"},"in":"header","name":"Authorization","description":"{api_key}","required":true},{"schema":{"type":"string"},"in":"header","name":"x-xdr-auth-id","description":"{api_key_id}","required":true}],"description":"Get all the authentication settings for every configured domain in the tenant.\n\nYou must have **Instance Administrator** permissions to run this endpoint.\n","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"request_data":{"type":"object","properties":{}}}}}}}}}},"components":{"schemas":{"reply":{"title":"reply","type":"object","properties":{"err_code":{"type":"string","description":"HTTP response code."},"err_msg":{"type":"string","description":"Error message."},"err_extra":{"type":"string","description":"Additional information describing the error."}},"description":"The query result upon error."}}}}
```

## Get IdP metadata

> Get the metadata for all IdPs.\
> \
> You must have \*\*Instance Administrator\*\* permissions to run this endpoint.

```json
{"openapi":"3.0.1","info":{"title":"Cortex XSOAR 8 API","version":"XSOAR 8 Cloud"},"tags":[{"name":"Authentication settings","description":"APIs for authentication settings, such as IdP and SSO"}],"servers":[{"url":"https://api-yourfqdn","description":""}],"paths":{"/public_api/v1/authentication-settings/get/metadata":{"post":{"summary":"Get IdP metadata","tags":["Authentication settings"],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"reply":{"type":"object","properties":{"sp_entity_id":{"type":"string"},"sp_logout_url":{"type":"string"},"sp_url":{"type":"string"},"tenant_id":{"type":"string"}}}}}}}},"400":{"description":"Bad Request. Got an invalid JSON.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/reply"}}}},"401":{"description":"Unauthorized access. An issue occurred during authentication. This can indicate an incorrect key, id, or other invalid authentication parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/reply"}}}},"402":{"description":"Unauthorized access. User does not have the required license type to run this API.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/reply"}}}},"403":{"description":"Forbidden access. The provided API Key does not have the required RBAC permissions to run this API.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/reply"}}}},"500":{"description":"Internal server error. A unified status for API communication type errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/reply"}}}}},"operationId":"post-public_api-v1-authentication-settings-get-metadata","parameters":[{"schema":{"type":"string"},"in":"header","name":"Authorization","description":"{api_key}","required":true},{"schema":{"type":"string"},"in":"header","name":"x-xdr-auth-id","description":"{api_key_id}","required":true}],"description":"Get the metadata for all IdPs.\n\nYou must have **Instance Administrator** permissions to run this endpoint.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"request_data":{"type":"object","properties":{}}}}}}}}}},"components":{"schemas":{"reply":{"title":"reply","type":"object","properties":{"err_code":{"type":"string","description":"HTTP response code."},"err_msg":{"type":"string","description":"Error message."},"err_extra":{"type":"string","description":"Additional information describing the error."}},"description":"The query result upon error."}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://cortex-docs.paloaltonetworks.com/xsoar-8-api/cortex-xsoar-8.x-apis/authentication-settings.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.