SAML Rail

SAML Rail

Enterprise SAML 2.0 Single Sign-On.

Overview

The SAML Rail provides endpoints for SAML 2.0 SSO integration with enterprise identity providers.

Base URL

/api/v1/saml

Endpoints

Configure IdP

POST /api/v1/saml/idp

Configure a SAML Identity Provider.

Request Body:

{
  "name": "Corporate IdP",
  "entityId": "https://idp.corp.example.com/saml/metadata",
  "ssoUrl": "https://idp.corp.example.com/saml/sso",
  "sloUrl": "https://idp.corp.example.com/saml/slo",
  "certificate": "-----BEGIN CERTIFICATE-----\n...",
  "nameIdFormat": "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress",
  "signatureAlgorithm": "RSA_SHA256",
  "attributeMapping": {
    "email": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress",
    "name": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name",
    "roles": "http://schemas.microsoft.com/ws/2008/06/identity/claims/role"
  },
  "active": true
}

Response:

{
  "data": {
    "idpId": "idp_abc123",
    "name": "Corporate IdP",
    "status": "ACTIVE",
    "spMetadataUrl": "https://api.islamicopenfinance.com/saml/metadata/idp_abc123",
    "acsUrl": "https://api.islamicopenfinance.com/saml/acs/idp_abc123",
    "createdAt": "2025-01-15T10:00:00Z"
  }
}

Get SP Metadata

GET /api/v1/saml/metadata/:idpId

Get Service Provider metadata XML for IdP configuration.

Initiate SSO

GET /api/v1/saml/sso/:idpId

Initiate SAML SSO flow.

Query Parameters:

Parameter	Description
RelayState	Return URL after authentication

ACS (Assertion Consumer Service)

POST /api/v1/saml/acs/:idpId

Handle SAML response from IdP.

Initiate SLO

GET /api/v1/saml/slo/:idpId

Initiate Single Logout.

Get IdP

GET /api/v1/saml/idp/:idpId

Get IdP configuration.

List IdPs

GET /api/v1/saml/idp

List configured IdPs.

Update IdP

PATCH /api/v1/saml/idp/:idpId

Update IdP configuration.

Delete IdP

DELETE /api/v1/saml/idp/:idpId

Remove IdP configuration.

Test Connection

POST /api/v1/saml/idp/:idpId/test

Test IdP connection.

Response:

{
  "data": {
    "success": true,
    "metadataValid": true,
    "certificateValid": true,
    "certificateExpiry": "2026-01-15",
    "ssoEndpointReachable": true
  }
}

SP Configuration

Our Service Provider configuration:

Setting	Value
Entity ID	https://api.islamicopenfinance.com/saml/metadata
ACS URL	https://api.islamicopenfinance.com/saml/acs/{idpId}
SLO URL	https://api.islamicopenfinance.com/saml/slo/{idpId}
Name ID Format	emailAddress
Signing	RSA-SHA256

Attribute Mapping

IOF Attribute	Common IdP Attributes
email	emailaddress, mail, email
name	displayname, name, cn
firstName	givenname, firstname
lastName	surname, lastname
roles	groups, role, memberof
department	department

Name ID Formats

Format	Description
emailAddress	Email address
persistent	Persistent identifier
transient	Transient identifier
unspecified	Any format

Events

Event	Description
saml.sso.initiated	SSO flow started
saml.sso.completed	SSO successful
saml.sso.failed	SSO failed
saml.slo.initiated	Logout started
saml.idp.configured	IdP configured

See Also

• Auth Rail - Basic authentication
• OAuth2 Rail - OAuth 2.0