SAML Assertion Callback

Endpoint for handling SAML assertion callback from IdP

Handle SAML Callback

cURL

curl -X POST https://your-domain.com/recipe/saml/callback \
  -H "Content-Type: application/json" \
  -d '{
    "samlResponse": "base64-encoded-saml-response",
    "relayState": "state-from-login-request"
  }'

200 OK

{
  "status": "OK",
  "redirectURI": "https://myapp.com/auth/callback?code=auth-code&state=state-value"
}

samlResponse · string · required

Base64-encoded SAML response from the Identity Provider

relayState · string

Optional relay state parameter passed during login initiation

status · string

“OK”, “INVALID_RELAY_STATE_ERROR”, “INVALID_CLIENT_ERROR”, “SAML_RESPONSE_VERIFICATION_FAILED_ERROR”, or “IDP_LOGIN_DISALLOWED_ERROR”

redirectURI · string

The URI to redirect the user back to your application, including any authentication tokens or codes

Response Status Codes

OK

SAML assertion was successfully validated. The redirectURI contains the callback URL with authentication information.

INVALID_RELAY_STATE_ERROR

The relay state parameter is invalid or doesn’t match the expected format.

INVALID_CLIENT_ERROR

The SAML client configuration referenced in the assertion is not found or invalid.

SAML_RESPONSE_VERIFICATION_FAILED_ERROR

The SAML assertion failed signature verification or validation. This could indicate:

• Invalid signature
• Expired assertion
• Assertion conditions not met
• Certificate mismatch

IDP_LOGIN_DISALLOWED_ERROR

IdP-initiated login was attempted but is not enabled for this client.

Usage

This endpoint is typically called automatically when the Identity Provider redirects back to your application after authentication. The SAML response is usually sent via HTTP POST from the IdP to your Assertion Consumer Service (ACS) URL.

HTML Form Example

<!-- IdP sends this form via POST -->
<form method="POST" action="https://your-domain.com/recipe/saml/callback">
  <input type="hidden" name="SAMLResponse" value="base64-encoded-response" />
  <input type="hidden" name="RelayState" value="state-value" />
  <input type="submit" value="Continue" />
</form>

Backend Processing

// Your backend should extract the SAML response and call this endpoint
const samlResponse = req.body.SAMLResponse;
const relayState = req.body.RelayState;

const result = await fetch('https://your-domain.com/recipe/saml/callback', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    samlResponse: samlResponse,
    relayState: relayState
  })
});

const data = await result.json();
if (data.status === 'OK') {
  res.redirect(data.redirectURI);
}