SAML IdP App Validation

The SAML IdP App Canarytoken can optionally validate incoming requests using a metadata file generated by the IdP. These endpoints enable/disable this validation, and allow for uploading the metadata file.

Endpoints

POST /api/v1/canarytokens/idp-app/validation/disable

POST /api/v1/canarytokens/idp-app/validation/enable

POST /api/v1/canarytokens/idp-app/metadata/save

Disable Validation

POST /api/v1/canarytokens/idp-app/validation/disable

Disable the validation for a specific SAML IdP App token.

Required Parameters

auth_token string

A valid auth token

canarytoken string

A valid Canarytoken

Response

A JSON structure with result indicator.

Example

curl https://EXAMPLE.canary.tools/api/v1/canarytokens/idp-app/validation/disable \
  -d auth_token=EXAMPLE_AUTH_TOKEN \
  -d canarytoken=EXAMPLE_CANARYTOKEN

import requests

url = 'https://EXAMPLE.canary.tools/api/v1/canarytokens/idp-app/validation/disable'

payload = {
  'auth_token': 'EXAMPLE_AUTH_TOKEN',
  'canarytoken': 'EXAMPLE_CANARYTOKEN'
}

r = requests.post(url, data=payload)

print(r.json())

Response

{
  "result": "success"
}

Enable Validation

POST /api/v1/canarytokens/idp-app/validation/enable

Enable the validation for a specific SAML IdP App token.

Required Parameters

auth_token string

A valid auth token

canarytoken string

A valid Canarytoken

Response

A JSON structure with result indicator.

Example

curl https://EXAMPLE.canary.tools/api/v1/canarytokens/idp-app/validation/enable \
  -d auth_token=EXAMPLE_AUTH_TOKEN \
  -d canarytoken=EXAMPLE_CANARYTOKEN

import requests

url = 'https://EXAMPLE.canary.tools/api/v1/canarytokens/idp-app/validation/enable'

payload = {
  'auth_token': 'EXAMPLE_AUTH_TOKEN',
  'canarytoken': 'EXAMPLE_CANARYTOKEN'
}

r = requests.post(url, data=payload)

print(r.json())

Response

{
  "result": "success"
}

Save Metadata File

POST /api/v1/canarytokens/idp-app/metadata/save

Save a new validation metadata file for a specific SAML IdP App token.

Required Parameters

auth_token string

A valid auth token

canarytoken string

A valid Canarytoken

Optional Parameters

metadata string

An XML file containing IdP metadata. Request must be multipart/form-data encoded if parameter is present.

TIP

Sending through a request without metadata will delete the existing file.

Response

A JSON structure with result indicator.

Example

curl "https://EXAMPLE.canary.tools/api/v1/canarytokens/idp-app/metadata/save" \
  -X POST \
  -F auth_token=EXAMPLE_AUTH_TOKEN \
  -F canarytoken=EXAMPLE_CANARYTOKEN \
  -F metadata=@/path/to/metadata.xml

import requests

url = 'https://EXAMPLE.canary.tools/api/v1/canarytokens/idp-app/metadata/save'

payload = {
  'auth_token': 'EXAMPLE_AUTH_TOKEN',
  'canarytoken': 'EXAMPLE_CANARYTOKEN',
}

with open('metadata.xml', 'rb') as file:
    files = {'metadata': file}
    r = requests.post(url, files=files, data=payload)

print(r.json())

Response

{
  "metadata_entity_id": "<IdP entity ID>",
  "result": "success"
}