API Documentation - SAML SSO Service

POST /api/saml/validate-saml-response API: Validate SAML Response

Validates a SAML Response against provided SP and/or IdP configuration, with optional metadata XML. Supports both config objects and metadata XML inputs (mutually exclusive). Returns validation results including errors if any.

Request Parameters (JSON)

Parameter Type Description

samlResponse string The SAML Response XML string (base64 encoded) to validate

spConfig object The Service Provider configuration

Field	Type	Description
`entityId`	`string`	The unique Entity ID (issuer identifier) for the Service Provider
`spPrivateKey`	`string`	The Service Provider's private key (PEM string)
`spCertificate`	`string`	The Service Provider's X.509 certificate (PEM string)
`acsUrl`	`string`	The Assertion Consumer Service URL where SAML responses are sent
`sloUrl`	`string`	The Single Logout Service URL for logout requests
`wantAssertionsSigned`	`NIL`	Whether the Service Provider requires signed assertions

idpConfig object The Identity Provider configuration

Field	Type	Description
`entityId`	`string`	The unique Entity ID (issuer identifier) for the Identity Provider
`idpPrivateKey`	`string`	The Identity Provider's private key (PEM string)
`idpCertificate`	`string`	The Identity Provider's X.509 certificate (PEM string)
`ssoUrl`	`string`	The Single Sign-On URL for SAML authentication requests
`sloUrl`	`string`	The Single Logout Service URL for logout requests

idpMetadataXml string The Identity Provider metadata XML string

spMetadataXml string The Service Provider metadata XML string

Response Fields

Field	Type	Description
`valid`	`boolean`	Whether the SAML response is valid
`responseId`	`string`	The unique identifier of the SAML response
`issuer`	`string`	The issuer of the SAML response
`status`	`string`	The status code of the SAML response
`assertions`	`integer`	The number of assertions in the SAML response
`responseError`	`string`	The error message if SAML response validation failed
`validationErrors`	`object`	A list of validation errors from the SAML response validation
`nameId`	`string`	The NameID from the assertion subject, identifying the authenticated user
`nameIdFormat`	`string`	The NameID format URI (e.g., urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress)
`authnContextClassRef`	`string`	The authentication context class reference URI
`authnInstant`	`string`	The timestamp of when the authentication occurred
`sessionIndex`	`string`	The session index from the AuthnStatement
`inResponseTo`	`string`	The InResponseTo attribute, correlating to the original AuthnRequest ID
`destination`	`string`	The Destination URL the response was sent to
`issueInstant`	`string`	The IssueInstant timestamp of the SAML response
`audience`	`string`	The intended audience (Service Provider entity ID)
`notBefore`	`string`	The NotBefore condition timestamp (validity window start)
`notOnOrAfter`	`string`	The NotOnOrAfter condition timestamp (validity window end)
`attributes`	`object`	A list of SAML attribute statements extracted from the assertion
`signatureValid`	`boolean`	Whether the SAML response/assertion signature was verified successfully

POST /api/saml/create-saml-response API: Create SAML Response

Creates a signed SAML Response from JSON configuration. Supports optional signing, configurable timestamps, and custom status codes.

Request Parameters (JSON)

Parameter Type Description

spConfig object The Service Provider configuration

Field	Type	Description
`entityId`	`string`	The unique Entity ID (issuer identifier) for the Service Provider
`spPrivateKey`	`string`	The Service Provider's private key (PEM string)
`spCertificate`	`string`	The Service Provider's X.509 certificate (PEM string)
`acsUrl`	`string`	The Assertion Consumer Service URL where SAML responses are sent
`sloUrl`	`string`	The Single Logout Service URL for logout requests
`wantAssertionsSigned`	`NIL`	Whether the Service Provider requires signed assertions

idpConfig object The Identity Provider configuration

Field	Type	Description
`entityId`	`string`	The unique Entity ID (issuer identifier) for the Identity Provider
`idpPrivateKey`	`string`	The Identity Provider's private key (PEM string)
`idpCertificate`	`string`	The Identity Provider's X.509 certificate (PEM string)
`ssoUrl`	`string`	The Single Sign-On URL for SAML authentication requests
`sloUrl`	`string`	The Single Logout Service URL for logout requests

idpMetadataXml string The Identity Provider metadata XML string

spMetadataXml string The Service Provider metadata XML string

relayState string The relay state URL to redirect to after SAML authentication

config object Configuration for SAML response creation (signing, timestamps, status)

Field Type Description

encodeResponseToBase64 boolean Whether to encode SAML response to base64

signResponse boolean Whether to sign the SAML Response

signAssertions boolean Whether to sign the assertions in the SAML Response

nameId string The name-id for SAML response subject

nameIdFormat string The NameID format URI (e.g. urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress)

responseIssuedAt string The SAML Response issue instant (SAML time format string)

assertionValidUntil string The SAML assertion validity end time (SAML time format string)

status string The SAML Response status code (default: urn:oasis:names:tc:SAML:2.0:status:Success)

inResponseTo string The InResponseTo attribute for the SAML Response (correlates to original AuthnRequest ID)

audience string The audience URI for the SAML Assertion conditions (the intended recipient SP entity ID)

attributes object List of SAML attributes to include in the assertion.

Field	Type	Description
`attributeName`	`string`	Name of the attribute.
`attributeValues`	`object`	List of the attribute values. Example: ["group-1", "group-2"]

authnContextClassRef string The AuthnContextClassRef URI (e.g. urn:oasis:names:tc:SAML:2.0:ac:classes:Password)

recipient string The Recipient for SubjectConfirmationData (typically the SP ACS URL)

destination string The Destination attribute on the SAML Response (overrides default ACS URL)

sessionIndex string The SessionIndex for the AuthnStatement

notBefore string The NotBefore condition timestamp (SAML time format string; overrides response-issued-at for conditions)

Response Fields

Field Type Description

samlResponse string The generated SAML Response as XML string, can be base64 encoded

config object The configuration used to generate the SAML response

Field Type Description

encodeResponseToBase64 boolean Whether to encode SAML response to base64

signResponse boolean Whether to sign the SAML Response

signAssertions boolean Whether to sign the assertions in the SAML Response

nameId string The name-id for SAML response subject

nameIdFormat string The NameID format URI (e.g. urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress)

responseIssuedAt string The SAML Response issue instant (SAML time format string)

assertionValidUntil string The SAML assertion validity end time (SAML time format string)

status string The SAML Response status code (default: urn:oasis:names:tc:SAML:2.0:status:Success)

inResponseTo string The InResponseTo attribute for the SAML Response (correlates to original AuthnRequest ID)

audience string The audience URI for the SAML Assertion conditions (the intended recipient SP entity ID)

attributes object List of SAML attributes to include in the assertion.

Field	Type	Description
`attributeName`	`string`	Name of the attribute.
`attributeValues`	`object`	List of the attribute values. Example: ["group-1", "group-2"]

authnContextClassRef string The AuthnContextClassRef URI (e.g. urn:oasis:names:tc:SAML:2.0:ac:classes:Password)

recipient string The Recipient for SubjectConfirmationData (typically the SP ACS URL)

destination string The Destination attribute on the SAML Response (overrides default ACS URL)

sessionIndex string The SessionIndex for the AuthnStatement

notBefore string The NotBefore condition timestamp (SAML time format string; overrides response-issued-at for conditions)

responseError string The error message if SAML response creation failed

POST /api/saml/create-sp-metadata API: Create SP Metadata

Creates Service Provider metadata XML from JSON parameters.

Request Parameters (JSON)

Parameter Type Description

spConfig object The Service Provider configuration

Field	Type	Description
`entityId`	`string`	The unique Entity ID (issuer identifier) for the Service Provider
`spPrivateKey`	`string`	The Service Provider's private key (PEM string)
`spCertificate`	`string`	The Service Provider's X.509 certificate (PEM string)
`acsUrl`	`string`	The Assertion Consumer Service URL where SAML responses are sent
`sloUrl`	`string`	The Single Logout Service URL for logout requests
`wantAssertionsSigned`	`NIL`	Whether the Service Provider requires signed assertions

Response Fields

Field	Type	Description
`metadataXml`	`string`	The generated SAML metadata XML string
`responseError`	`string`	The error message if metadata generation failed

POST /api/saml/create-idp-metadata API: Create IdP Metadata

Creates Identity Provider metadata XML from JSON parameters.

Request Parameters (JSON)

Parameter Type Description

idpConfig object The Identity Provider configuration

Field	Type	Description
`entityId`	`string`	The unique Entity ID (issuer identifier) for the Identity Provider
`idpPrivateKey`	`string`	The Identity Provider's private key (PEM string)
`idpCertificate`	`string`	The Identity Provider's X.509 certificate (PEM string)
`ssoUrl`	`string`	The Single Sign-On URL for SAML authentication requests
`sloUrl`	`string`	The Single Logout Service URL for logout requests

Response Fields

Field	Type	Description
`metadataXml`	`string`	The generated SAML metadata XML string
`responseError`	`string`	The error message if metadata generation failed

POST /api/saml/create-authn-request API: Create AuthnRequest

Creates a SAML AuthnRequest from a JSON configuration object. Returns the AuthnRequest XML string.

Request Parameters (JSON)

Parameter Type Description

spConfig object The Service Provider configuration

Field	Type	Description
`entityId`	`string`	The unique Entity ID (issuer identifier) for the Service Provider
`spPrivateKey`	`string`	The Service Provider's private key (PEM string)
`spCertificate`	`string`	The Service Provider's X.509 certificate (PEM string)
`acsUrl`	`string`	The Assertion Consumer Service URL where SAML responses are sent
`sloUrl`	`string`	The Single Logout Service URL for logout requests
`wantAssertionsSigned`	`NIL`	Whether the Service Provider requires signed assertions

spMetadataXml string The Service Provider metadata XML string

config object Configuration for creation

Field	Type	Description
`encodeToBase64`	`boolean`	Whether to encode to base64

Response Fields

Field	Type	Description
`xml`	`string`	The generated authn request XML string
`responseError`	`string`	The error message if metadata generation failed

POST /api/saml/create-logout-request API: Generate LogoutRequest

Generates a SAML LogoutRequest from a JSON configuration object. Returns the LogoutRequest XML string.

Request Parameters (JSON)

Parameter Type Description

spConfig object The Service Provider configuration

Field	Type	Description
`entityId`	`string`	The unique Entity ID (issuer identifier) for the Service Provider
`spPrivateKey`	`string`	The Service Provider's private key (PEM string)
`spCertificate`	`string`	The Service Provider's X.509 certificate (PEM string)
`acsUrl`	`string`	The Assertion Consumer Service URL where SAML responses are sent
`sloUrl`	`string`	The Single Logout Service URL for logout requests
`wantAssertionsSigned`	`NIL`	Whether the Service Provider requires signed assertions

spMetadataXml string The Service Provider metadata XML string

config object Configuration for creation

Field	Type	Description
`nameId`	`string`	Which user's session to terminate
`sessionId`	`string`	Identifies a specific SAML session for that user

Response Fields

Field	Type	Description
`xml`	`string`	The generated authn request XML string
`responseError`	`string`	The error message if metadata generation failed

POST /api/saml/create-logout-response API: Create LogoutResponse

Create a SAML LogoutResponse XML from a JSON configuration object.

Request Parameters (JSON)

Parameter Type Description

idpConfig object The Identity Provider configuration

Field	Type	Description
`entityId`	`string`	The unique Entity ID (issuer identifier) for the Identity Provider
`idpPrivateKey`	`string`	The Identity Provider's private key (PEM string)
`idpCertificate`	`string`	The Identity Provider's X.509 certificate (PEM string)
`ssoUrl`	`string`	The Single Sign-On URL for SAML authentication requests
`sloUrl`	`string`	The Single Logout Service URL for logout requests

idpMetadataXml string The Identity Provider metadata XML string

config object Configuration for SAML logout response creation

Field	Type	Description
`signResponse`	`boolean`	Whether to sign the SAML Logout Response
`inResponseTo`	`string`	The InResponseTo attribute for the SAML Logout Response (correlates to original AuthnRequest ID)
`status`	`string`	The SAML Logout Response status code (default: urn:oasis:names:tc:SAML:2.0:status:Success)

Response Fields

Field	Type	Description
`xml`	`string`	The created LogoutResponse XML string
`responseError`	`string`	The error message if processing failed