SAML Quickstart

This guide walks you through adding BlokSec as a SAML 2.0 Identity Provider (IdP) to your Service Provider (SP) application.

Prerequisites

• Admin access to the BlokSec admin console
• A SAML-compatible application (your Service Provider)
• Your SP’s Entity ID and ACS URL

Step 1: Create a SAML application in BlokSec

1. In the admin console, go to Applications > Add Application
2. Enter a name for your application
3. Select SAML as the application type
4. Enter your SP’s Entity ID — a unique identifier for your application (usually a URL like https://yourapp.com/saml/metadata)
5. Choose the NameID Source:
   • Account Name — uses the user’s account identifier as the NameID
   • User Email — uses the user’s email address as the NameID
6. Add at least one ACS URL — the endpoint where BlokSec sends the SAML response (e.g., https://yourapp.com/saml/acs)
7. Optionally configure:
   • NameID Format (default: emailAddress)
   • Single Logout URL for SLO support
   • Require Signed Requests if your SP signs AuthnRequests
8. Click Create

Screenshot pending

/screenshots/developer/saml-quickstart/create-app.png

SAML application creation form in the admin console

Creating a SAML application

Step 2: Configure your SP with BlokSec IdP metadata

After creating the application, download the BlokSec IdP metadata from the application detail page. The metadata XML is also available at:

https://api.bloksec.io/sso/metadata/{applicationId}

Where {applicationId} is the application’s DID shown on the detail page.

The metadata includes:

Field	Value
IdP Entity ID	The BlokSec issuer URL
SSO Service URL	https://api.bloksec.io/sso/SingleSignOnService/{applicationId} (POST binding)
SLO Service URL	https://api.bloksec.io/sso/SingleLogoutService/{applicationId} (POST binding)
Signing Certificate	X.509 certificate for verifying assertion signatures

Import this metadata into your SP. Most SAML-compatible applications have a metadata import feature.

Step 3: Initiate a SAML login

There are two ways to start a SAML authentication:

SP-initiated (recommended)

Your application redirects the user to BlokSec with a SAML AuthnRequest. Most SAML libraries handle this automatically once configured with the IdP metadata.

The user arrives at the BlokSec login screen, authenticates using their phone, and is redirected back to your ACS URL with a signed SAML response.

IdP-initiated

The user starts at BlokSec and chooses your application from a list. BlokSec generates an unsolicited SAML response and posts it to your ACS URL. Not all SPs support this mode.

Step 4: Parse the SAML response

BlokSec posts a SAML response to your ACS URL via HTTP POST. The response contains a signed assertion with:

• NameID — the user’s identifier (email or account name, based on your configuration)
• Conditions — audience restriction (your SP Entity ID) and time validity (5-minute window)
• Attributes — any custom attributes you configured
• AuthnStatement — confirmation that the user authenticated, with a session index

Your SAML library should:

1. Validate the XML signature using BlokSec’s signing certificate (from the metadata)
2. Check that the audience restriction matches your SP Entity ID
3. Verify the assertion is within its validity window
4. Extract the NameID and attributes for your application

What’s next

• SAML Reference — complete specification of assertion format, NameID formats, attribute mapping, and signing details
• Authentication Flow — understand how BlokSec’s passwordless authentication works under the hood