NAV Navigation
Shell HTTP JavaScript Node.js Ruby Python Java Go PHP

SAML Authentication Configuration API v1.0.0

Scroll down for code samples, example requests and responses. Select a language for code samples from the tabs above or the mobile navigation menu.

Base URLs:

Default

get__saml_{domain}

Code samples

# You can also use wget
curl -X GET https://mail.example.com/service/extension/zextras_admin/auth/saml/{domain} \
  -H 'Accept: application/json'

GET /saml/{domain}

Get SAML configuration for the specified domain

Used to get all or some of the SAML authentication properties for the given domain, in JSON format

Parameters

Name In Type Required Description
domain path string true domain we want the configuration of
keys query string false comma delimited list of properties
raw query boolean false if true, defaults are not applied and only stored properties are returned

Example responses

200 Response

{
  "sp.entityid": "https://samlokta.demo.zextras.io/zx/auth/samlMetadata?domain=demo.zextras.io",
  "sp.assertion_consumer_service.url": "https://samlokta.demo.zextras.io/zx/auth/saml",
  "idp.entityid": "https://zextras.okta.com/app/appID/sso/saml/metadata",
  "idp.single_sign_on_service.url": "https://zextras.okta.com/app/zextrassrl_zimbrassotest_1/appId/sso/saml",
  "idp.x509cert": "-----BEGIN CERTIFICATE-----...-----END CERTIFICATE-----",
  "sp.x509cert": "-----BEGIN CERTIFICATE-----...-----END CERTIFICATE-----",
  "sp.assertion_consumer_service.binding": "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST",
  "sp.single_logout_service.url": "string",
  "sp.single_logout_service.binding": "string",
  "sp.nameidformat": "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress",
  "sp.privatekey": "-----BEGIN PRIVATE KEY-----...-----END PRIVATE KEY-----",
  "idp.single_sign_on_service.binding": "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect",
  "idp.single_logout_service.url": "https://zextras.okta.com/app/zextrassrl_zimbrassotest_1/exk1t7tdyqj35vUF6357/slo/saml",
  "idp.single_logout_service.response.url": "string",
  "idp.single_logout_service.binding": "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect",
  "security.nameid_encrypted": false,
  "security.authnrequest_signed": false,
  "security.logoutrequest_signed": false,
  "security.logoutresponse_signed": false,
  "security.want_messages_signed": false,
  "security.want_assertions_signed": false,
  "security.sign_metadata": false,
  "security.want_assertions_encrypted": false,
  "security.want_nameid_encrypted": false,
  "security.requested_authncontext": "urn:oasis:names:tc:SAML:2.0:ac:classes:Password",
  "security.requested_authncontextcomparison": "exact",
  "security.want_xml_validation": true,
  "security.signature_algorithm": "http://www.w3.org/2000/09/xmldsig#rsa-sha1",
  "organization.name": "Zextras",
  "organization.displayname": "Zextras",
  "organization.url": "https://zextras.com",
  "organization.lang": "en",
  "contacts.technical.given_name": "OneGuy",
  "contacts.technical.email_address": "oneguy@zextras.com",
  "contacts.support.given_name": "OneGuy",
  "contacts.support.email_address": "oneguy@zextras.com"
}

Responses

Status Meaning Description Schema
200 OK successful operation SAMLProperties

put__saml_{domain}

Code samples

# You can also use wget
curl -X PUT https://mail.example.com/service/extension/zextras_admin/auth/saml/{domain} \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json'

PUT /saml/{domain}

Updates one or more SAML configuration properties for the specified domain

Used to update specific properties of the SAML authentication configuration for the given domain

Body parameter

{
  "sp.entityid": "https://samlokta.demo.zextras.io/zx/auth/samlMetadata?domain=demo.zextras.io",
  "sp.assertion_consumer_service.url": "https://samlokta.demo.zextras.io/zx/auth/saml",
  "idp.entityid": "https://zextras.okta.com/app/appID/sso/saml/metadata",
  "idp.single_sign_on_service.url": "https://zextras.okta.com/app/zextrassrl_zimbrassotest_1/appId/sso/saml",
  "idp.x509cert": "-----BEGIN CERTIFICATE-----...-----END CERTIFICATE-----",
  "sp.x509cert": "-----BEGIN CERTIFICATE-----...-----END CERTIFICATE-----",
  "sp.assertion_consumer_service.binding": "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST",
  "sp.single_logout_service.url": "string",
  "sp.single_logout_service.binding": "string",
  "sp.nameidformat": "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress",
  "sp.privatekey": "-----BEGIN PRIVATE KEY-----...-----END PRIVATE KEY-----",
  "idp.single_sign_on_service.binding": "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect",
  "idp.single_logout_service.url": "https://zextras.okta.com/app/zextrassrl_zimbrassotest_1/exk1t7tdyqj35vUF6357/slo/saml",
  "idp.single_logout_service.response.url": "string",
  "idp.single_logout_service.binding": "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect",
  "security.nameid_encrypted": false,
  "security.authnrequest_signed": false,
  "security.logoutrequest_signed": false,
  "security.logoutresponse_signed": false,
  "security.want_messages_signed": false,
  "security.want_assertions_signed": false,
  "security.sign_metadata": false,
  "security.want_assertions_encrypted": false,
  "security.want_nameid_encrypted": false,
  "security.requested_authncontext": "urn:oasis:names:tc:SAML:2.0:ac:classes:Password",
  "security.requested_authncontextcomparison": "exact",
  "security.want_xml_validation": true,
  "security.signature_algorithm": "http://www.w3.org/2000/09/xmldsig#rsa-sha1",
  "organization.name": "Zextras",
  "organization.displayname": "Zextras",
  "organization.url": "https://zextras.com",
  "organization.lang": "en",
  "contacts.technical.given_name": "OneGuy",
  "contacts.technical.email_address": "oneguy@zextras.com",
  "contacts.support.given_name": "OneGuy",
  "contacts.support.email_address": "oneguy@zextras.com"
}

Parameters

Name In Type Required Description
domain path string true domain we want to update
body body SAMLProperties false none

Example responses

200 Response

{
  "sp.entityid": "https://samlokta.demo.zextras.io/zx/auth/samlMetadata?domain=demo.zextras.io",
  "sp.assertion_consumer_service.url": "https://samlokta.demo.zextras.io/zx/auth/saml",
  "idp.entityid": "https://zextras.okta.com/app/appID/sso/saml/metadata",
  "idp.single_sign_on_service.url": "https://zextras.okta.com/app/zextrassrl_zimbrassotest_1/appId/sso/saml",
  "idp.x509cert": "-----BEGIN CERTIFICATE-----...-----END CERTIFICATE-----",
  "sp.x509cert": "-----BEGIN CERTIFICATE-----...-----END CERTIFICATE-----",
  "sp.assertion_consumer_service.binding": "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST",
  "sp.single_logout_service.url": "string",
  "sp.single_logout_service.binding": "string",
  "sp.nameidformat": "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress",
  "sp.privatekey": "-----BEGIN PRIVATE KEY-----...-----END PRIVATE KEY-----",
  "idp.single_sign_on_service.binding": "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect",
  "idp.single_logout_service.url": "https://zextras.okta.com/app/zextrassrl_zimbrassotest_1/exk1t7tdyqj35vUF6357/slo/saml",
  "idp.single_logout_service.response.url": "string",
  "idp.single_logout_service.binding": "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect",
  "security.nameid_encrypted": false,
  "security.authnrequest_signed": false,
  "security.logoutrequest_signed": false,
  "security.logoutresponse_signed": false,
  "security.want_messages_signed": false,
  "security.want_assertions_signed": false,
  "security.sign_metadata": false,
  "security.want_assertions_encrypted": false,
  "security.want_nameid_encrypted": false,
  "security.requested_authncontext": "urn:oasis:names:tc:SAML:2.0:ac:classes:Password",
  "security.requested_authncontextcomparison": "exact",
  "security.want_xml_validation": true,
  "security.signature_algorithm": "http://www.w3.org/2000/09/xmldsig#rsa-sha1",
  "organization.name": "Zextras",
  "organization.displayname": "Zextras",
  "organization.url": "https://zextras.com",
  "organization.lang": "en",
  "contacts.technical.given_name": "OneGuy",
  "contacts.technical.email_address": "oneguy@zextras.com",
  "contacts.support.given_name": "OneGuy",
  "contacts.support.email_address": "oneguy@zextras.com"
}

Responses

Status Meaning Description Schema
200 OK successful operation SAMLProperties
400 Bad Request error in operation Error

post__saml_{domain}

Code samples

# You can also use wget
curl -X POST https://mail.example.com/service/extension/zextras_admin/auth/saml/{domain} \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json'

POST /saml/{domain}

Imports the whole SAML configuration of a domain

Used to import the SAML configuration of a domain from a JSON or XML document, either embedded in the request, or referenced as an external URL

Body parameter

{
  "sp.entityid": "https://samlokta.demo.zextras.io/zx/auth/samlMetadata?domain=demo.zextras.io",
  "sp.assertion_consumer_service.url": "https://samlokta.demo.zextras.io/zx/auth/saml",
  "idp.entityid": "https://zextras.okta.com/app/appID/sso/saml/metadata",
  "idp.single_sign_on_service.url": "https://zextras.okta.com/app/zextrassrl_zimbrassotest_1/appId/sso/saml",
  "idp.x509cert": "-----BEGIN CERTIFICATE-----...-----END CERTIFICATE-----",
  "sp.x509cert": "-----BEGIN CERTIFICATE-----...-----END CERTIFICATE-----",
  "sp.assertion_consumer_service.binding": "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST",
  "sp.single_logout_service.url": "string",
  "sp.single_logout_service.binding": "string",
  "sp.nameidformat": "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress",
  "sp.privatekey": "-----BEGIN PRIVATE KEY-----...-----END PRIVATE KEY-----",
  "idp.single_sign_on_service.binding": "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect",
  "idp.single_logout_service.url": "https://zextras.okta.com/app/zextrassrl_zimbrassotest_1/exk1t7tdyqj35vUF6357/slo/saml",
  "idp.single_logout_service.response.url": "string",
  "idp.single_logout_service.binding": "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect",
  "security.nameid_encrypted": false,
  "security.authnrequest_signed": false,
  "security.logoutrequest_signed": false,
  "security.logoutresponse_signed": false,
  "security.want_messages_signed": false,
  "security.want_assertions_signed": false,
  "security.sign_metadata": false,
  "security.want_assertions_encrypted": false,
  "security.want_nameid_encrypted": false,
  "security.requested_authncontext": "urn:oasis:names:tc:SAML:2.0:ac:classes:Password",
  "security.requested_authncontextcomparison": "exact",
  "security.want_xml_validation": true,
  "security.signature_algorithm": "http://www.w3.org/2000/09/xmldsig#rsa-sha1",
  "organization.name": "Zextras",
  "organization.displayname": "Zextras",
  "organization.url": "https://zextras.com",
  "organization.lang": "en",
  "contacts.technical.given_name": "OneGuy",
  "contacts.technical.email_address": "oneguy@zextras.com",
  "contacts.support.given_name": "OneGuy",
  "contacts.support.email_address": "oneguy@zextras.com"
}
<?xml version="1.0" encoding="UTF-8" ?>
<SAMLProperties>
  <sp.entityid>https://samlokta.demo.zextras.io/zx/auth/samlMetadata?domain=demo.zextras.io</sp.entityid>
  <sp.assertion_consumer_service.url>https://samlokta.demo.zextras.io/zx/auth/saml</sp.assertion_consumer_service.url>
  <idp.entityid>https://zextras.okta.com/app/appID/sso/saml/metadata</idp.entityid>
  <idp.single_sign_on_service.url>https://zextras.okta.com/app/zextrassrl_zimbrassotest_1/appId/sso/saml</idp.single_sign_on_service.url>
  <idp.x509cert>-----BEGIN CERTIFICATE-----...-----END CERTIFICATE-----</idp.x509cert>
  <sp.x509cert>-----BEGIN CERTIFICATE-----...-----END CERTIFICATE-----</sp.x509cert>
  <sp.assertion_consumer_service.binding>urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST</sp.assertion_consumer_service.binding>
  <sp.single_logout_service.url>string</sp.single_logout_service.url>
  <sp.single_logout_service.binding>string</sp.single_logout_service.binding>
  <sp.nameidformat>urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress</sp.nameidformat>
  <sp.privatekey>-----BEGIN PRIVATE KEY-----...-----END PRIVATE KEY-----</sp.privatekey>
  <idp.single_sign_on_service.binding>urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect</idp.single_sign_on_service.binding>
  <idp.single_logout_service.url>https://zextras.okta.com/app/zextrassrl_zimbrassotest_1/exk1t7tdyqj35vUF6357/slo/saml</idp.single_logout_service.url>
  <idp.single_logout_service.response.url>string</idp.single_logout_service.response.url>
  <idp.single_logout_service.binding>urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect</idp.single_logout_service.binding>
  <security.nameid_encrypted>false</security.nameid_encrypted>
  <security.authnrequest_signed>false</security.authnrequest_signed>
  <security.logoutrequest_signed>false</security.logoutrequest_signed>
  <security.logoutresponse_signed>false</security.logoutresponse_signed>
  <security.want_messages_signed>false</security.want_messages_signed>
  <security.want_assertions_signed>false</security.want_assertions_signed>
  <security.sign_metadata>false</security.sign_metadata>
  <security.want_assertions_encrypted>false</security.want_assertions_encrypted>
  <security.want_nameid_encrypted>false</security.want_nameid_encrypted>
  <security.requested_authncontext>urn:oasis:names:tc:SAML:2.0:ac:classes:Password</security.requested_authncontext>
  <security.requested_authncontextcomparison>exact</security.requested_authncontextcomparison>
  <security.want_xml_validation>true</security.want_xml_validation>
  <security.signature_algorithm>http://www.w3.org/2000/09/xmldsig#rsa-sha1</security.signature_algorithm>
  <organization.name>Zextras</organization.name>
  <organization.displayname>Zextras</organization.displayname>
  <organization.url>https://zextras.com</organization.url>
  <organization.lang>en</organization.lang>
  <contacts.technical.given_name>OneGuy</contacts.technical.given_name>
  <contacts.technical.email_address>oneguy@zextras.com</contacts.technical.email_address>
  <contacts.support.given_name>OneGuy</contacts.support.given_name>
  <contacts.support.email_address>oneguy@zextras.com</contacts.support.email_address>
</SAMLProperties>

Parameters

Name In Type Required Description
domain path string true domain we want to update
url query string false url to fetch the JSON or XML document from, instead of the request body
allowUnsecure query boolean false if true and url is used, allow fetching from sites with and invalid (or self-signed) SSL certificates
validate query boolean false if true properties are validated before storing
body body SAMLProperties false none

Example responses

200 Response

{
  "sp.entityid": "https://samlokta.demo.zextras.io/zx/auth/samlMetadata?domain=demo.zextras.io",
  "sp.assertion_consumer_service.url": "https://samlokta.demo.zextras.io/zx/auth/saml",
  "idp.entityid": "https://zextras.okta.com/app/appID/sso/saml/metadata",
  "idp.single_sign_on_service.url": "https://zextras.okta.com/app/zextrassrl_zimbrassotest_1/appId/sso/saml",
  "idp.x509cert": "-----BEGIN CERTIFICATE-----...-----END CERTIFICATE-----",
  "sp.x509cert": "-----BEGIN CERTIFICATE-----...-----END CERTIFICATE-----",
  "sp.assertion_consumer_service.binding": "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST",
  "sp.single_logout_service.url": "string",
  "sp.single_logout_service.binding": "string",
  "sp.nameidformat": "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress",
  "sp.privatekey": "-----BEGIN PRIVATE KEY-----...-----END PRIVATE KEY-----",
  "idp.single_sign_on_service.binding": "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect",
  "idp.single_logout_service.url": "https://zextras.okta.com/app/zextrassrl_zimbrassotest_1/exk1t7tdyqj35vUF6357/slo/saml",
  "idp.single_logout_service.response.url": "string",
  "idp.single_logout_service.binding": "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect",
  "security.nameid_encrypted": false,
  "security.authnrequest_signed": false,
  "security.logoutrequest_signed": false,
  "security.logoutresponse_signed": false,
  "security.want_messages_signed": false,
  "security.want_assertions_signed": false,
  "security.sign_metadata": false,
  "security.want_assertions_encrypted": false,
  "security.want_nameid_encrypted": false,
  "security.requested_authncontext": "urn:oasis:names:tc:SAML:2.0:ac:classes:Password",
  "security.requested_authncontextcomparison": "exact",
  "security.want_xml_validation": true,
  "security.signature_algorithm": "http://www.w3.org/2000/09/xmldsig#rsa-sha1",
  "organization.name": "Zextras",
  "organization.displayname": "Zextras",
  "organization.url": "https://zextras.com",
  "organization.lang": "en",
  "contacts.technical.given_name": "OneGuy",
  "contacts.technical.email_address": "oneguy@zextras.com",
  "contacts.support.given_name": "OneGuy",
  "contacts.support.email_address": "oneguy@zextras.com"
}

Responses

Status Meaning Description Schema
200 OK successful operation SAMLProperties
400 Bad Request error in operation Error

delete__saml_{domain}

Code samples

# You can also use wget
curl -X DELETE https://mail.example.com/service/extension/zextras_admin/auth/saml/{domain} \
  -H 'Accept: application/json'

DELETE /saml/{domain}

Deletes one or more SAML configuration properties for the specified domain

Used to remove specific properties (or all of them) of the SAML authentication configuration for the given domain

Parameters

Name In Type Required Description
domain path string true domain we want to remove properties from
keys query string false comma delimited list of properties to remove, if missing all properties are deleted

Example responses

200 Response

{
  "sp.entityid": "https://samlokta.demo.zextras.io/zx/auth/samlMetadata?domain=demo.zextras.io",
  "sp.assertion_consumer_service.url": "https://samlokta.demo.zextras.io/zx/auth/saml",
  "idp.entityid": "https://zextras.okta.com/app/appID/sso/saml/metadata",
  "idp.single_sign_on_service.url": "https://zextras.okta.com/app/zextrassrl_zimbrassotest_1/appId/sso/saml",
  "idp.x509cert": "-----BEGIN CERTIFICATE-----...-----END CERTIFICATE-----",
  "sp.x509cert": "-----BEGIN CERTIFICATE-----...-----END CERTIFICATE-----",
  "sp.assertion_consumer_service.binding": "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST",
  "sp.single_logout_service.url": "string",
  "sp.single_logout_service.binding": "string",
  "sp.nameidformat": "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress",
  "sp.privatekey": "-----BEGIN PRIVATE KEY-----...-----END PRIVATE KEY-----",
  "idp.single_sign_on_service.binding": "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect",
  "idp.single_logout_service.url": "https://zextras.okta.com/app/zextrassrl_zimbrassotest_1/exk1t7tdyqj35vUF6357/slo/saml",
  "idp.single_logout_service.response.url": "string",
  "idp.single_logout_service.binding": "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect",
  "security.nameid_encrypted": false,
  "security.authnrequest_signed": false,
  "security.logoutrequest_signed": false,
  "security.logoutresponse_signed": false,
  "security.want_messages_signed": false,
  "security.want_assertions_signed": false,
  "security.sign_metadata": false,
  "security.want_assertions_encrypted": false,
  "security.want_nameid_encrypted": false,
  "security.requested_authncontext": "urn:oasis:names:tc:SAML:2.0:ac:classes:Password",
  "security.requested_authncontextcomparison": "exact",
  "security.want_xml_validation": true,
  "security.signature_algorithm": "http://www.w3.org/2000/09/xmldsig#rsa-sha1",
  "organization.name": "Zextras",
  "organization.displayname": "Zextras",
  "organization.url": "https://zextras.com",
  "organization.lang": "en",
  "contacts.technical.given_name": "OneGuy",
  "contacts.technical.email_address": "oneguy@zextras.com",
  "contacts.support.given_name": "OneGuy",
  "contacts.support.email_address": "oneguy@zextras.com"
}

Responses

Status Meaning Description Schema
200 OK successful operation SAMLProperties
400 Bad Request error in operation Error

get__saml-validate_{domain}

Code samples

# You can also use wget
curl -X GET https://mail.example.com/service/extension/zextras_admin/auth/saml-validate/{domain} \
  -H 'Accept: application/json'

GET /saml-validate/{domain}

Validate current SAML configuration for the specified domain

Used to validate the SAML authentication properties for the given domain

Parameters

Name In Type Required Description
domain path string true domain we want to validate the configuration of

Example responses

200 Response

{
  "sp.entityid": "https://samlokta.demo.zextras.io/zx/auth/samlMetadata?domain=demo.zextras.io",
  "sp.assertion_consumer_service.url": "https://samlokta.demo.zextras.io/zx/auth/saml",
  "idp.entityid": "https://zextras.okta.com/app/appID/sso/saml/metadata",
  "idp.single_sign_on_service.url": "https://zextras.okta.com/app/zextrassrl_zimbrassotest_1/appId/sso/saml",
  "idp.x509cert": "-----BEGIN CERTIFICATE-----...-----END CERTIFICATE-----",
  "sp.x509cert": "-----BEGIN CERTIFICATE-----...-----END CERTIFICATE-----",
  "sp.assertion_consumer_service.binding": "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST",
  "sp.single_logout_service.url": "string",
  "sp.single_logout_service.binding": "string",
  "sp.nameidformat": "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress",
  "sp.privatekey": "-----BEGIN PRIVATE KEY-----...-----END PRIVATE KEY-----",
  "idp.single_sign_on_service.binding": "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect",
  "idp.single_logout_service.url": "https://zextras.okta.com/app/zextrassrl_zimbrassotest_1/exk1t7tdyqj35vUF6357/slo/saml",
  "idp.single_logout_service.response.url": "string",
  "idp.single_logout_service.binding": "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect",
  "security.nameid_encrypted": false,
  "security.authnrequest_signed": false,
  "security.logoutrequest_signed": false,
  "security.logoutresponse_signed": false,
  "security.want_messages_signed": false,
  "security.want_assertions_signed": false,
  "security.sign_metadata": false,
  "security.want_assertions_encrypted": false,
  "security.want_nameid_encrypted": false,
  "security.requested_authncontext": "urn:oasis:names:tc:SAML:2.0:ac:classes:Password",
  "security.requested_authncontextcomparison": "exact",
  "security.want_xml_validation": true,
  "security.signature_algorithm": "http://www.w3.org/2000/09/xmldsig#rsa-sha1",
  "organization.name": "Zextras",
  "organization.displayname": "Zextras",
  "organization.url": "https://zextras.com",
  "organization.lang": "en",
  "contacts.technical.given_name": "OneGuy",
  "contacts.technical.email_address": "oneguy@zextras.com",
  "contacts.support.given_name": "OneGuy",
  "contacts.support.email_address": "oneguy@zextras.com"
}

Responses

Status Meaning Description Schema
200 OK successful operation SAMLProperties

post__saml-validate

Code samples

# You can also use wget
curl -X POST https://mail.example.com/service/extension/zextras_admin/auth/saml-validate \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json'

POST /saml-validate

Validates a SAML configuration

Used to validate a SAML configuration document, in JSON or XML format, either embedded in the request, or referenced as an external URL

Body parameter

{
  "sp.entityid": "https://samlokta.demo.zextras.io/zx/auth/samlMetadata?domain=demo.zextras.io",
  "sp.assertion_consumer_service.url": "https://samlokta.demo.zextras.io/zx/auth/saml",
  "idp.entityid": "https://zextras.okta.com/app/appID/sso/saml/metadata",
  "idp.single_sign_on_service.url": "https://zextras.okta.com/app/zextrassrl_zimbrassotest_1/appId/sso/saml",
  "idp.x509cert": "-----BEGIN CERTIFICATE-----...-----END CERTIFICATE-----",
  "sp.x509cert": "-----BEGIN CERTIFICATE-----...-----END CERTIFICATE-----",
  "sp.assertion_consumer_service.binding": "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST",
  "sp.single_logout_service.url": "string",
  "sp.single_logout_service.binding": "string",
  "sp.nameidformat": "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress",
  "sp.privatekey": "-----BEGIN PRIVATE KEY-----...-----END PRIVATE KEY-----",
  "idp.single_sign_on_service.binding": "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect",
  "idp.single_logout_service.url": "https://zextras.okta.com/app/zextrassrl_zimbrassotest_1/exk1t7tdyqj35vUF6357/slo/saml",
  "idp.single_logout_service.response.url": "string",
  "idp.single_logout_service.binding": "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect",
  "security.nameid_encrypted": false,
  "security.authnrequest_signed": false,
  "security.logoutrequest_signed": false,
  "security.logoutresponse_signed": false,
  "security.want_messages_signed": false,
  "security.want_assertions_signed": false,
  "security.sign_metadata": false,
  "security.want_assertions_encrypted": false,
  "security.want_nameid_encrypted": false,
  "security.requested_authncontext": "urn:oasis:names:tc:SAML:2.0:ac:classes:Password",
  "security.requested_authncontextcomparison": "exact",
  "security.want_xml_validation": true,
  "security.signature_algorithm": "http://www.w3.org/2000/09/xmldsig#rsa-sha1",
  "organization.name": "Zextras",
  "organization.displayname": "Zextras",
  "organization.url": "https://zextras.com",
  "organization.lang": "en",
  "contacts.technical.given_name": "OneGuy",
  "contacts.technical.email_address": "oneguy@zextras.com",
  "contacts.support.given_name": "OneGuy",
  "contacts.support.email_address": "oneguy@zextras.com"
}
<?xml version="1.0" encoding="UTF-8" ?>
<SAMLProperties>
  <sp.entityid>https://samlokta.demo.zextras.io/zx/auth/samlMetadata?domain=demo.zextras.io</sp.entityid>
  <sp.assertion_consumer_service.url>https://samlokta.demo.zextras.io/zx/auth/saml</sp.assertion_consumer_service.url>
  <idp.entityid>https://zextras.okta.com/app/appID/sso/saml/metadata</idp.entityid>
  <idp.single_sign_on_service.url>https://zextras.okta.com/app/zextrassrl_zimbrassotest_1/appId/sso/saml</idp.single_sign_on_service.url>
  <idp.x509cert>-----BEGIN CERTIFICATE-----...-----END CERTIFICATE-----</idp.x509cert>
  <sp.x509cert>-----BEGIN CERTIFICATE-----...-----END CERTIFICATE-----</sp.x509cert>
  <sp.assertion_consumer_service.binding>urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST</sp.assertion_consumer_service.binding>
  <sp.single_logout_service.url>string</sp.single_logout_service.url>
  <sp.single_logout_service.binding>string</sp.single_logout_service.binding>
  <sp.nameidformat>urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress</sp.nameidformat>
  <sp.privatekey>-----BEGIN PRIVATE KEY-----...-----END PRIVATE KEY-----</sp.privatekey>
  <idp.single_sign_on_service.binding>urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect</idp.single_sign_on_service.binding>
  <idp.single_logout_service.url>https://zextras.okta.com/app/zextrassrl_zimbrassotest_1/exk1t7tdyqj35vUF6357/slo/saml</idp.single_logout_service.url>
  <idp.single_logout_service.response.url>string</idp.single_logout_service.response.url>
  <idp.single_logout_service.binding>urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect</idp.single_logout_service.binding>
  <security.nameid_encrypted>false</security.nameid_encrypted>
  <security.authnrequest_signed>false</security.authnrequest_signed>
  <security.logoutrequest_signed>false</security.logoutrequest_signed>
  <security.logoutresponse_signed>false</security.logoutresponse_signed>
  <security.want_messages_signed>false</security.want_messages_signed>
  <security.want_assertions_signed>false</security.want_assertions_signed>
  <security.sign_metadata>false</security.sign_metadata>
  <security.want_assertions_encrypted>false</security.want_assertions_encrypted>
  <security.want_nameid_encrypted>false</security.want_nameid_encrypted>
  <security.requested_authncontext>urn:oasis:names:tc:SAML:2.0:ac:classes:Password</security.requested_authncontext>
  <security.requested_authncontextcomparison>exact</security.requested_authncontextcomparison>
  <security.want_xml_validation>true</security.want_xml_validation>
  <security.signature_algorithm>http://www.w3.org/2000/09/xmldsig#rsa-sha1</security.signature_algorithm>
  <organization.name>Zextras</organization.name>
  <organization.displayname>Zextras</organization.displayname>
  <organization.url>https://zextras.com</organization.url>
  <organization.lang>en</organization.lang>
  <contacts.technical.given_name>OneGuy</contacts.technical.given_name>
  <contacts.technical.email_address>oneguy@zextras.com</contacts.technical.email_address>
  <contacts.support.given_name>OneGuy</contacts.support.given_name>
  <contacts.support.email_address>oneguy@zextras.com</contacts.support.email_address>
</SAMLProperties>

Parameters

Name In Type Required Description
url query string false url to fetch the JSON or XML document from, instead of the request body
allowUnsecure query boolean false if true and url is used, allow fetching from sites with and invalid (or self-signed) SSL certificates
body body SAMLProperties false none

Example responses

200 Response

{
  "sp.entityid": "https://samlokta.demo.zextras.io/zx/auth/samlMetadata?domain=demo.zextras.io",
  "sp.assertion_consumer_service.url": "https://samlokta.demo.zextras.io/zx/auth/saml",
  "idp.entityid": "https://zextras.okta.com/app/appID/sso/saml/metadata",
  "idp.single_sign_on_service.url": "https://zextras.okta.com/app/zextrassrl_zimbrassotest_1/appId/sso/saml",
  "idp.x509cert": "-----BEGIN CERTIFICATE-----...-----END CERTIFICATE-----",
  "sp.x509cert": "-----BEGIN CERTIFICATE-----...-----END CERTIFICATE-----",
  "sp.assertion_consumer_service.binding": "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST",
  "sp.single_logout_service.url": "string",
  "sp.single_logout_service.binding": "string",
  "sp.nameidformat": "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress",
  "sp.privatekey": "-----BEGIN PRIVATE KEY-----...-----END PRIVATE KEY-----",
  "idp.single_sign_on_service.binding": "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect",
  "idp.single_logout_service.url": "https://zextras.okta.com/app/zextrassrl_zimbrassotest_1/exk1t7tdyqj35vUF6357/slo/saml",
  "idp.single_logout_service.response.url": "string",
  "idp.single_logout_service.binding": "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect",
  "security.nameid_encrypted": false,
  "security.authnrequest_signed": false,
  "security.logoutrequest_signed": false,
  "security.logoutresponse_signed": false,
  "security.want_messages_signed": false,
  "security.want_assertions_signed": false,
  "security.sign_metadata": false,
  "security.want_assertions_encrypted": false,
  "security.want_nameid_encrypted": false,
  "security.requested_authncontext": "urn:oasis:names:tc:SAML:2.0:ac:classes:Password",
  "security.requested_authncontextcomparison": "exact",
  "security.want_xml_validation": true,
  "security.signature_algorithm": "http://www.w3.org/2000/09/xmldsig#rsa-sha1",
  "organization.name": "Zextras",
  "organization.displayname": "Zextras",
  "organization.url": "https://zextras.com",
  "organization.lang": "en",
  "contacts.technical.given_name": "OneGuy",
  "contacts.technical.email_address": "oneguy@zextras.com",
  "contacts.support.given_name": "OneGuy",
  "contacts.support.email_address": "oneguy@zextras.com"
}

Responses

Status Meaning Description Schema
200 OK successful operation SAMLProperties
400 Bad Request error in operation Error

post__saml-generate_{domain}

Code samples

# You can also use wget
curl -X POST https://mail.example.com/service/extension/zextras_admin/auth/saml-generate/{domain} \
  -H 'Accept: application/json'

POST /saml-generate/{domain}

Generate and stores all is needed to self-sign requests to the IdP

Used to automatically generate an X509 certificate and the related private key that will be used to sign requests to the IdP

Parameters

Name In Type Required Description
domain path string true domain we want to configure
days query integer false days of validity of the generated certificate
organization query string false name of the organization that will be part of the certificate subject
organizationalUnit query string false name of the organizational unit that will be part of the certificate subject
country query string false name of the country that will be part of the certificate subject
state query string false name of the state/province that will be part of the certificate subject
location query string false name of the city/town that will be part of the certificate subject
digest query string false Digest alghoritm used to sign messages
encryption query string false Encryption alghoritm (and bit size) used to encrypt messages

Example responses

200 Response

{
  "sp.entityid": "https://samlokta.demo.zextras.io/zx/auth/samlMetadata?domain=demo.zextras.io",
  "sp.assertion_consumer_service.url": "https://samlokta.demo.zextras.io/zx/auth/saml",
  "idp.entityid": "https://zextras.okta.com/app/appID/sso/saml/metadata",
  "idp.single_sign_on_service.url": "https://zextras.okta.com/app/zextrassrl_zimbrassotest_1/appId/sso/saml",
  "idp.x509cert": "-----BEGIN CERTIFICATE-----...-----END CERTIFICATE-----",
  "sp.x509cert": "-----BEGIN CERTIFICATE-----...-----END CERTIFICATE-----",
  "sp.assertion_consumer_service.binding": "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST",
  "sp.single_logout_service.url": "string",
  "sp.single_logout_service.binding": "string",
  "sp.nameidformat": "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress",
  "sp.privatekey": "-----BEGIN PRIVATE KEY-----...-----END PRIVATE KEY-----",
  "idp.single_sign_on_service.binding": "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect",
  "idp.single_logout_service.url": "https://zextras.okta.com/app/zextrassrl_zimbrassotest_1/exk1t7tdyqj35vUF6357/slo/saml",
  "idp.single_logout_service.response.url": "string",
  "idp.single_logout_service.binding": "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect",
  "security.nameid_encrypted": false,
  "security.authnrequest_signed": false,
  "security.logoutrequest_signed": false,
  "security.logoutresponse_signed": false,
  "security.want_messages_signed": false,
  "security.want_assertions_signed": false,
  "security.sign_metadata": false,
  "security.want_assertions_encrypted": false,
  "security.want_nameid_encrypted": false,
  "security.requested_authncontext": "urn:oasis:names:tc:SAML:2.0:ac:classes:Password",
  "security.requested_authncontextcomparison": "exact",
  "security.want_xml_validation": true,
  "security.signature_algorithm": "http://www.w3.org/2000/09/xmldsig#rsa-sha1",
  "organization.name": "Zextras",
  "organization.displayname": "Zextras",
  "organization.url": "https://zextras.com",
  "organization.lang": "en",
  "contacts.technical.given_name": "OneGuy",
  "contacts.technical.email_address": "oneguy@zextras.com",
  "contacts.support.given_name": "OneGuy",
  "contacts.support.email_address": "oneguy@zextras.com"
}

Responses

Status Meaning Description Schema
200 OK successful operation SAMLProperties
400 Bad Request error in operation Error

Schemas

Error

{
  "ok": true,
  "error": "string"
}

Properties

Name Type Required Restrictions Description
ok boolean true none none
error string true none none

SAMLProperties

{
  "sp.entityid": "https://samlokta.demo.zextras.io/zx/auth/samlMetadata?domain=demo.zextras.io",
  "sp.assertion_consumer_service.url": "https://samlokta.demo.zextras.io/zx/auth/saml",
  "idp.entityid": "https://zextras.okta.com/app/appID/sso/saml/metadata",
  "idp.single_sign_on_service.url": "https://zextras.okta.com/app/zextrassrl_zimbrassotest_1/appId/sso/saml",
  "idp.x509cert": "-----BEGIN CERTIFICATE-----...-----END CERTIFICATE-----",
  "sp.x509cert": "-----BEGIN CERTIFICATE-----...-----END CERTIFICATE-----",
  "sp.assertion_consumer_service.binding": "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST",
  "sp.single_logout_service.url": "string",
  "sp.single_logout_service.binding": "string",
  "sp.nameidformat": "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress",
  "sp.privatekey": "-----BEGIN PRIVATE KEY-----...-----END PRIVATE KEY-----",
  "idp.single_sign_on_service.binding": "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect",
  "idp.single_logout_service.url": "https://zextras.okta.com/app/zextrassrl_zimbrassotest_1/exk1t7tdyqj35vUF6357/slo/saml",
  "idp.single_logout_service.response.url": "string",
  "idp.single_logout_service.binding": "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect",
  "security.nameid_encrypted": false,
  "security.authnrequest_signed": false,
  "security.logoutrequest_signed": false,
  "security.logoutresponse_signed": false,
  "security.want_messages_signed": false,
  "security.want_assertions_signed": false,
  "security.sign_metadata": false,
  "security.want_assertions_encrypted": false,
  "security.want_nameid_encrypted": false,
  "security.requested_authncontext": "urn:oasis:names:tc:SAML:2.0:ac:classes:Password",
  "security.requested_authncontextcomparison": "exact",
  "security.want_xml_validation": true,
  "security.signature_algorithm": "http://www.w3.org/2000/09/xmldsig#rsa-sha1",
  "organization.name": "Zextras",
  "organization.displayname": "Zextras",
  "organization.url": "https://zextras.com",
  "organization.lang": "en",
  "contacts.technical.given_name": "OneGuy",
  "contacts.technical.email_address": "oneguy@zextras.com",
  "contacts.support.given_name": "OneGuy",
  "contacts.support.email_address": "oneguy@zextras.com"
}

Properties

Name Type Required Restrictions Description
sp.entityid string true none Unique identifier for the Carbonio instance, as configured in the IdP for the carbonio instance / domain pair
sp.assertion_consumer_service.url string true none Carbonio endpoint where the IdP should send login / logout assertions
idp.entityid string true none Unique identifier of the IdP SAML configuration for this instance of Carbonio
idp.single_sign_on_service.url string true none IdP endpoint for Single Sign On requests
idp.x509cert string true none IdP X509 certificate, used to verify IdP signatures
sp.x509cert string false none Carbonio X509 certificate, used to sign requests to the IdP
sp.assertion_consumer_service.binding string false none type of requests that the IdP should send to carbonio for login / logout
sp.single_logout_service.url string false none not used
sp.single_logout_service.binding string false none not used
sp.nameidformat string false none format for the user name requested to the IdP, so that it matches with local account email
sp.privatekey string false none Carbonio X509 certificate private key, used to sign requests to the IdP
idp.single_sign_on_service.binding string false none Request type to send to the IdP Single Sign On endpoint
idp.single_logout_service.url string false none IdP Single Logout endpoint
idp.single_logout_service.response.url string false none not used
idp.single_logout_service.binding string false none Request type to send to the IdP Single Logout endpoint
security.nameid_encrypted boolean false none send account identifier in encrypted form
security.authnrequest_signed boolean false none send authentication requests with signature
security.logoutrequest_signed boolean false none send logout requests with signature
security.logoutresponse_signed boolean false none send logout response with signature
security.want_messages_signed boolean false none require signature from the IdP
security.want_assertions_signed boolean false none require signature in login / logout assertions from the IdP
security.sign_metadata boolean false none sign metadata response
security.want_assertions_encrypted boolean false none require encrypted assertions from the IdP
security.want_nameid_encrypted boolean false none require encrypted account identifier from the IdP
security.requested_authncontext string false none allows specifying the authentication context if the IdP supports more than one
security.requested_authncontextcomparison string false none authentication context comparison method
security.want_xml_validation boolean false none validates XML validity of assertions
security.signature_algorithm string false none encryption alghoritm to use
organization.name string false none Simple name of the organization
organization.displayname string false none Display name of the organization
organization.url string false none URL of the organization website
organization.lang string false none main language of the organization
contacts.technical.given_name string false none Technical contact name for the organization
contacts.technical.email_address string false none Technical contact email address for the organization
contacts.support.given_name string false none Support contact name for the organization
contacts.support.email_address string false none Support contact email address for the organization

Enumerated Values

Property Value
sp.assertion_consumer_service.binding urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST