1Kosmos

Configure 1Kosmos as a SAML identity provider (IdP) for Knocknoc. Once connected, your users authenticate against 1Kosmos — including its biometric and passwordless factors — and Knocknoc maps their group membership to access entitlements.

This example assumes your Knocknoc instance is at https://<tenant>.knoc.cloud. Substitute your own instance URL throughout (e.g. https://demo.knoc.cloud).

In this integration:

• Knocknoc is the Service Provider (SP) — it consumes the SAML assertion.
• 1Kosmos is the Identity Provider (IdP) — it authenticates the user and issues the assertion.

  ┌──────────┐   1. Access request    ┌──────────┐
  │   User   │ ─────────────────────▶ │ Knocknoc │
  └──────────┘                        │   (SP)   │
       ▲                              └────┬─────┘
       │                                   │ 2. SAML AuthnRequest
       │ 5. Assertion returned             ▼
       │    + group claims         ┌───────────────┐
       └────────────────────────── │   1Kosmos     │
                4. Authenticated   │    (IdP)      │
                                   └───────────────┘
                    3. User authenticates (biometric / passwordless)

User vs Admin SAML. Knocknoc supports SAML for the user portal and, separately, for the admin interface. The two use different endpoint paths (/api/saml/... vs /api/admin/saml/...). Configure Users first; once confirmed working, extend to Admins while keeping a local break-glass admin account.

Before you begin

You will need:

• Community administrator access to your 1Kosmos AdminX tenant.
• Administrator access to your Knocknoc instance.
• An identity provider already configured in AdminX (Settings > IdP Configuration). 1Kosmos allows one IdP per tenant.
• A directory integration (AD / LDAP) connected in AdminX if you intend to pass group membership — see Passing group membership.

A note on metadata. Unlike Entra ID — which publishes a hosted App Federation Metadata URL you paste straight into Knocknoc — 1Kosmos, when acting as the IdP, provides only a downloadable metadata XML file plus individual endpoint values. Before rollout, confirm how your Knocknoc build accepts IdP metadata (hosted URL, uploaded file, or manual endpoint entry); this determines which method you use in Step 3.

Step 1 — Gather IdP details from 1Kosmos

In AdminX, go to Settings > IdP Configuration and open your identity provider.

Value	Where to find it
IdP Entity ID	Generated from the Name field under Core Configuration
SSO URL	Service URL Endpoints → Single SignOn Service
SLO URL (optional)	Service URL Endpoints → Single Logout Service
Signing certificate	Signing Certificate → Options > View & Download Certificate (X.509 .pem)
Metadata XML	SAML Metadata → Download

Set Authentication Request to Signed (recommended). Keep these to hand — you will use them in Step 3.

Step 2: Add Knocknoc as a SAML app in 1Kosmos

In AdminX, go to Applications > Add Application. Under Custom App, select SAML 2.0 Generic and click Add Integration.

2.1 Application details

Field	Value
Application name	Knocknoc
Application access URL	https://<tenant>.knoc.cloud/

Click Next.

2.2 SAML settings

Field	Value
NameID Format	urn:oasis:names:tc:SAML:2.0:nameid-format:persistent
NameID Value	username (the user's UPN / login identifier)

2.3 Claims mapping

Knocknoc reads four specific claims. The claim names must match exactly — username, realName, sessionDuration and groups. In the Claims Mapping section, click Add new for each:

Claim name (required)	1Kosmos source	Notes
username	User.Username	The user's login identifier.
realName	display-name attribute	1Kosmos has no displayname by default — map to a full-name attribute, or create one mapped to the directory displayName.
sessionDuration	integer, e.g. 480	Login duration in minutes, whole number, no quotes. Confirm whether your 1Kosmos build can emit a fixed value or requires a session/per-user attribute.
groups	mapped group attribute	See Step 4. Customise the claim name to exactly groups.

Click Next.

2.4 Advanced options

Field	Value (Users)	Value (Admin)
Entity ID	https://<tenant>.knoc.cloud/api/saml/metadata	https://<tenant>.knoc.cloud/api/admin/saml/metadata
ACS URL	https://<tenant>.knoc.cloud/api/saml/acs	https://<tenant>.knoc.cloud/api/admin/saml/acs
ACS Method	POST	POST
Signing certificate (optional)	Upload Knocknoc's public-key .pem if Knocknoc signs its requests	same

Click Save.

Always confirm the exact Entity ID and ACS URL against your Knocknoc SAML configuration screen before going live.

Step 3: Configure Knocknoc

In Knocknoc, log in to the admin interface and open Settings.

1. Provide the 1Kosmos IdP metadata using the method your build supports (hosted metadata URL, uploaded metadata XML from Step 1, or manual entry of Entity ID + SSO URL + signing certificate).
2. Click Generate new keypair and save. (Optionally, supply your own keys/certificate manually.)
3. Click Save.

Manual-entry reference (if your build supports it):

Knocknoc field	Paste from 1Kosmos (Step 1)
IdP Entity ID	Entity ID
IdP SSO URL	Single SignOn Service
IdP SLO URL (optional)	Single Logout Service
IdP signing certificate	Signing certificate (.pem)

Step 4: Passing group membership

Knocknoc maps the groups claim to its access entitlements (ACLs). 1Kosmos does not emit a groups attribute by default — the standard session attributes are only firstname, lastname, status, username, email and phone. You must create and map it.

1. Create a session attribute Go to Settings > 1Kosmos Attributes > Add new. Name it groups.

2. Map it to your directory In your AD / LDAP directory integration, map the new attribute to the directory's group field (for example, Active Directory memberOf). Without this mapping the claim ships empty.

3. Expose it as a claim Confirm groups is present in the Knocknoc app's Claims Mapping (Step 2.3), with the claim name set to exactly groups.

Matching groups in Knocknoc. Knocknoc matches the group values it receives against the Group Name field on each Knocknoc group. Decide your scheme up front:

• By name — the claim carries human-readable group names (e.g. US-Admin-SSH); use those strings as the Group Name in Knocknoc.
• By GUID/Object ID — the claim carries directory object IDs (e.g. 6a696eec-482f-4b40-97c8-9ea3dba8ac3a); use those IDs as the Group Name in Knocknoc.

Multi-value check. Verify on a test user that 1Kosmos emits multiple groups as repeated <AttributeValue> elements rather than a single delimited string. Knocknoc expects discrete values; a delimited string is the most common cause of group-mapping failures.

Step 5: Test

1. Browse to https://<tenant>.knoc.cloud/. An SSO Login button should be present.
2. Click it. If not already authenticated to 1Kosmos, you are redirected to the 1Kosmos sign-in page.
3. Authenticate (scan the QR code with the 1Kosmos mobile app, or enter username, password and OTP).
4. Confirm you are returned to Knocknoc and that any ACLs tied to your groups now show Granted.

Once Users work, repeat for the Admin interface using the /api/admin/saml/... endpoints — and keep a local break-glass admin in case SAML breaks.

Troubleshooting

Symptom	Likely cause
Redirect loop / "invalid issuer"	Entity ID mismatch — check it ends in /api/saml/metadata (or /api/admin/saml/metadata)
Assertion rejected	Wrong or expired signing certificate; re-download from Step 1, or regenerate the Knocknoc keypair
User authenticates but lands with no access	groups claim empty (check directory mapping) or Group Name in Knocknoc doesn't match the claim value (name vs GUID)
All users land in one group	Groups arriving as a delimited string, not repeated <AttributeValue> elements
Session ends too soon / too late	sessionDuration claim missing or wrong; it is whole minutes (e.g. 480)
"NameID format" error	NameID format mismatch — confirm Persistent on both sides

Reference — value exchange

Direction	Values
1Kosmos → Knocknoc	Entity ID, SSO URL, SLO URL (optional), signing certificate, metadata XML
Knocknoc → 1Kosmos	Application access URL, SP Entity ID (/api/saml/metadata), ACS URL (/api/saml/acs, POST), SP signing cert (optional)