End-user SSO (SAML)

End-user SSO lets the people who fill your forms sign in with your organization’s identity provider (IdP), using SAML, instead of an OTP or a password. Cellosign checks that the person who signed in is the person the form was created for: the user ID that your IdP returns must match the identity you set when you created the session.

End-user SSO is different from SSO, which signs in Cellosign users:

	SSO	End-user SSO
Who signs in	Cellosign users (staff and managers)	The people who fill your forms
Type in the SAML2 integration	SSO	SSO End User
User accounts	Created in Cellosign, with roles	None
Identity	Comes from your IdP	Set by you when the session is created, and checked against your IdP
Used in the template	Requires authentication	End user sso

How it works

Your system creates the form session through API v3 or a BPMN workflow, and sets the recipient’s identity, for example the customer’s ID number.
The client receives the form link and opens it.
Cellosign redirects the client’s browser to your IdP’s sign-in page. Cellosign does not send a SAML request or the session ID to your IdP.
The client signs in at your IdP.
Your IdP sends a signed SAML response, through the client’s browser, to the Cellosign ACS. The response contains the client’s user ID and the session ID of the form.
Cellosign validates the response and checks that:
- the session requires end-user SSO with this integration;
- the user ID matches the identity set in step 1 exactly;
- the session has not been submitted, deleted or expired.
If all checks pass, the form opens. Otherwise, the client sees “This page is unavailable.”

Before you start

Only organization (company) managers can create, edit or delete end-user SSO integrations. Project managers and implementers can view them.
Sessions must be created through API v3 or a BPMN workflow, because the client’s identity is set when the session is created. Templates with an end-user SSO recipient can’t be started from the dashboard or the agent screen.
Check with your Cellosign account team that end-user SSO is enabled for your company.
Your IdP must be able to:
- send an IdP-initiated (unsolicited) SAML response to the Cellosign ACS, using the HTTP-POST binding;
- sign the assertion;
- include the session ID as an attribute, and the user ID as an attribute or as the NameID;
- publish a sign-in address (SingleSignOnService with the HTTP-POST binding) in its metadata. Cellosign redirects clients to this address.

Step 1 — Create the end-user SSO integration

On the Integrations page, in SSO Integrations, locate the SAML2 pane and click Add.
Fill in the form:

Field	What it’s for
Alias	A name for the integration. You select the integration by this name in the template.
Type	Select SSO End User.
IdP Metadata	Your IdP’s metadata. Enter the Metadata URL, or upload the metadata `.xml` file.
User ID	The SAML attribute that holds the client’s user ID. Default: `com.cellosign.sso.enduser.userid`. If you leave it empty, the user ID is taken from the SAML Subject NameID. For better privacy and flexibility, use an attribute and a transient NameID.
Session ID	The SAML attribute that holds the session ID. Default: `com.cellosign.sso.enduser.sessionid`. Required.

Click Save. If you don’t have your IdP’s metadata yet, click Save without IdP metadata and add it later.

After the first save, the form stays open and shows what your IdP needs: EntityId, ACS and Download SP metadata. You use them in step 2.

The metadata URL must use HTTPS with a valid host name, and must not include a port, a user name or password, or a fragment. IP addresses, localhost and .local host names are not allowed.

Under Organization sharing, select Share with other projects in the organization. Other projects in your organization can then select this integration for end-user SSO, but only this project can edit it. In the other projects, the integration appears under Shared from other projects, marked Read-only.

Because all the projects use the same integration, you register Cellosign in your IdP only once.

If you stop sharing the integration or delete it, the other projects can no longer create sessions with it, and their clients can no longer sign in with it.

Step 2 — Register Cellosign in your IdP

In your IdP, add Cellosign as a SAML application (service provider). The simplest way is to import the SP metadata file from Download SP metadata. To configure it manually, use:

Setting	Value
Entity ID (Audience)	The EntityId value from step 1
ACS (Reply URL)	The ACS value from step 1, with the HTTP-POST binding
Assertion signing	Required
NameID format	Transient, when the user ID is sent as an attribute. If you use the NameID as the user ID, its value must equal the client’s identity.
Session ID attribute	Attribute name: the Session ID value from step 1. Value: the session ID of the form being opened.
User ID attribute	Attribute name: the User ID value from step 1. Value: exactly the identity you set when you created the session.

The EntityId and ACS both have the form https://<forms domain>/a/saml/<integration ID>/.

Also note:

An assertion can be valid for at most 15 minutes, and its issue time can’t be in the future (5 seconds’ tolerance). Keep your IdP’s clock in sync.
Each SAML response can be used only once.
Cellosign’s certificate is included in the SP metadata. When it is renewed, import the updated SP metadata into your IdP.

Step 3 — Require end-user SSO in the template

Open the template and go to Configuration > Workflow. Turn on Turn workflow on.
In the recipient’s card, select the integration under End user sso. Integrations shared from other projects appear as “name (shared from project)”.
Save the template.

Also note:

Each recipient can use one integration. Different recipients can use different integrations.
End-user SSO replaces the other sign-in options for that recipient. Selecting an integration clears Requires authentication, Activate OTP and Require password, and turning on one of those clears End user sso.
If the selected integration is no longer available (deleted or no longer shared), the card shows Selected integration is no longer available.
Templates with an end-user SSO recipient don’t appear in the dashboard’s New transaction list, and Show Agent is disabled for them.

Step 4 — Create sessions with the client’s identity

API v3

When you create a session or start a workflow through API v3, set identity on each recipient that requires end-user SSO. The value can be up to 300 characters, and it must exactly match the user ID your IdP will return. For example, POST /api/v3/{project_name}/session/:

{
  "template": { "id": "<template ID>" },
  "recipient": { "identity": "<client user ID>" }
}

If a recipient requires end-user SSO and identity is missing, the request fails with user with order <n>, must have sso identity.

The API returns require_sso and identity for each recipient, and webhook and archive payloads include recipient.identity. Values received from your IdP are not stored or passed into the form.

BPMN workflow

In the session node, set Role identity to a value, or Role identity reference to map it from the process input. If the identity is missing, no session is created and the process logs Missing value for "role Identity" can not generate transaction.

What the client sees

Opening the form link takes the client straight to your IdP’s sign-in page.
After signing in, the form opens.
Refreshing the form sends the client back to your IdP to sign in again.
If a check fails, or the session was submitted, deleted or has expired, the client sees “This page is unavailable.” with “We’re sorry — access may be restricted or the page may no longer exist.”
Cellosign ties the sign-in to the client’s IP address. If the IP address changes during sign-in (for example, when switching from Wi-Fi to mobile data), the client is sent back to the IdP to sign in again.

Test your setup

Create a session with a known identity, open the link, and sign in as that user: the form opens.
Sign in as a different user: “This page is unavailable.”
Open the link of a submitted or deleted session: “This page is unavailable.”
Refresh an open form: the client is sent back to your IdP.
Create a session without identity: the API returns an error.

Troubleshooting

What you see	What to check
“This page is unavailable.” after signing in	The user ID from your IdP exactly matches the session’s `identity`. The session ID attribute is present and correct. The assertion is signed, not expired and not reused. The Entity ID and ACS in your IdP match the integration. The session is not submitted, deleted or expired. The integration is active, and still shared if it belongs to another project.
The client keeps returning to the IdP	The client’s IP address changed during sign-in.
API error `must have sso identity`	Add `identity` to the recipient.
`end-user SAML integration is not available` when creating a session	The integration was deleted, or is no longer shared with this project.
The metadata URL is rejected	The URL must use HTTPS with a valid host name, and no port, user name, password or fragment.