SAML Reference

Complete reference for BlokSec’s SAML 2.0 Identity Provider implementation. For a step-by-step integration guide, see the SAML Quickstart.

Base URL

https://api.bloksec.io

IdP metadata

GET /sso/metadata/{applicationId}
Content-Type: text/xml

Returns the SAML 2.0 IdP metadata XML for the specified application. The {applicationId} is the application’s DID, shown on the application detail page in the admin console.

The metadata includes:

Element	Value
EntityID	BlokSec issuer URL
SingleSignOnService	POST binding to /sso/SingleSignOnService/{applicationId}
SingleLogoutService	POST binding to /sso/SingleLogoutService/{applicationId}
KeyDescriptor (signing)	X.509 certificate for assertion signature verification
NameIDFormat	Configured formats for this application

SSO endpoint

GET|POST /sso/SingleSignOnService/{applicationId}

The SAML Single Sign-On endpoint. Accepts both SP-initiated (with AuthnRequest) and IdP-initiated flows.

SP-initiated flow

1. Your SP generates a SAML AuthnRequest and redirects (or posts) the user to this endpoint
2. BlokSec renders the login page
3. The user authenticates using their BlokSec app
4. BlokSec generates a signed SAML response and posts it to your ACS URL

IdP-initiated flow

If the user navigates directly to BlokSec and selects your application, BlokSec generates an unsolicited SAML response and posts it to your ACS URL.

SLO endpoint

GET|POST /sso/SingleLogoutService/{applicationId}

The SAML Single Logout endpoint. Accepts logout requests to terminate the user’s BlokSec session.

Assertion format

BlokSec generates SAML 2.0 assertions with the following structure:

Subject

<saml:Subject>
  <saml:NameID Format="{configured format}">{NameID value}</saml:NameID>
  <saml:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
    <saml:SubjectConfirmationData
      NotOnOrAfter="{issue time + 5 minutes}"
      Recipient="{your ACS URL}"
      InResponseTo="{AuthnRequest ID}" />
  </saml:SubjectConfirmation>
</saml:Subject>

Conditions

<saml:Conditions NotBefore="{issue time}" NotOnOrAfter="{issue time + 5 minutes}">
  <saml:AudienceRestriction>
    <saml:Audience>{your SP Entity ID}</saml:Audience>
  </saml:AudienceRestriction>
</saml:Conditions>

Assertions are valid for a 5-minute window from the time of issue.

AuthnStatement

<saml:AuthnStatement AuthnInstant="{auth time}" SessionIndex="{session ID}">
  <saml:AuthnContext>
    <saml:AuthnContextClassRef>
      urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport
    </saml:AuthnContextClassRef>
  </saml:AuthnContext>
</saml:AuthnStatement>

AttributeStatement

If custom attributes are configured, they are included as:

<saml:AttributeStatement>
  <saml:Attribute Name="{attribute name}"
                  NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
    <saml:AttributeValue xsi:type="xs:string">{value}</saml:AttributeValue>
  </saml:Attribute>
</saml:AttributeStatement>

Supported NameID formats

Format	URI
Email Address	urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
Persistent	urn:oasis:names:tc:SAML:2.0:nameid-format:persistent
Transient	urn:oasis:names:tc:SAML:2.0:nameid-format:transient
Unspecified	urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified

The default format is emailAddress.

NameID source

The NameID value comes from the NameID Source configured on the application:

Source	Value
Account Name	The user’s account name (identifier within the application)
User Email	The user’s email address

Signing

All SAML responses and assertions are signed by BlokSec using the application’s signing certificate. The certificate is included in the IdP metadata.

Request signing

If Require Signed Requests is enabled on the application, BlokSec will reject any AuthnRequest that is not signed by the SP. This provides additional assurance that the request came from the legitimate SP.

Assertion encryption

Assertion encryption is not currently enabled. Assertions are signed but transmitted in plaintext within the SAML response. Use HTTPS to protect assertions in transit.

Error handling

If authentication fails, BlokSec returns a SAML response with a non-success status code:

<samlp:Status>
  <samlp:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Responder" />
</samlp:Status>

Common failure reasons:

• User denied the authentication request
• Authentication request timed out (120-second default)
• User’s account is suspended or terminated