Connectors

SAML 2.0 Connector

The SAML 2.0 connector enables Single Sign-On (SSO) via any SAML 2.0-compliant Identity Provider — including Okta, Microsoft ADFS, Azure AD SAML, Shibboleth, and others. Employees log in once to their corporate identity provider and receive WiFi access without a separate Kiwire password.

'alt' => 'Dashboard overview', 'caption' => 'The default Kiwire dashboard layout', 'screenshot' => true, 'class' => '', ]) Drop images into: public/assets/img/docs/{page}/{filename} --}}

Image not uploaded yet public/assets/img/docs/connector-saml/overview.png

The SAML connector — SP settings are generated by Kiwire; IdP settings come from your identity provider.

Use Case

In enterprise environments, IT departments manage identity through a central Identity Provider (IdP). The SAML connector bridges Kiwire to that IdP so staff do not need a separate WiFi account. When an employee clicks Login with SSO on the captive portal or enterprise WiFi page, they are redirected to the corporate login page. After authenticating there (including any MFA enforced by the IdP), they are returned to Kiwire and granted WiFi access automatically.

SAML connector supports multiple instances. You can configure separate SAML IdPs for different departments or partner organisations — each instance has its own ACS URL and Entity ID.

Authentication Flow

User connects to WiFi and is shown the captive portal (or enterprise login page).
User clicks Login with SSO. Kiwire generates a SAML AuthnRequest and redirects the user to the IdP's SSO endpoint.
The user authenticates at the IdP — username/password, MFA, smartcard, etc. as configured by the IdP administrator.
The IdP generates a SAML assertion (XML) containing the user's identity attributes and posts it to Kiwire's Assertion Consumer Service (ACS) URL.
Kiwire validates the assertion signature using the IdP's X.509 certificate, checks the audience restriction and expiry, and extracts the user's identity.
Kiwire creates or updates the user's WiFi account and grants network access.

'alt' => 'Dashboard overview', 'caption' => 'The default Kiwire dashboard layout', 'screenshot' => true, 'class' => '', ]) Drop images into: public/assets/img/docs/{page}/{filename} --}}

Image not uploaded yet public/assets/img/docs/connector-saml/flow-diagram.png

SAML SSO flow — user → IdP login page → SAML assertion posted to Kiwire ACS → WiFi access granted.

SP Settings (Set in Kiwire)

Kiwire acts as the Service Provider (SP). The following values are generated by Kiwire and must be registered in your Identity Provider:

Field	Description
`entity_id`	Kiwire's SP Entity ID — a unique URI identifying this Kiwire instance as a SAML service provider. Copy this to your IdP.
`acs_url`	Assertion Consumer Service URL — the endpoint where the IdP posts the SAML response after authentication. Copy this to your IdP.
`name_id_format`	The NameID format requested: `emailAddress` (default, recommended) or `persistent`

Use the Download SP Metadata XML button on the connector form to get a standard SAML metadata file. Most IdPs (Okta, Azure, Shibboleth) can import this file directly, automatically filling in the Entity ID and ACS URL.

IdP Settings (From Your Identity Provider)

Copy the following values from your IdP's configuration or metadata XML into Kiwire:

Field	Description
`idp_entity_id`	The IdP's Entity ID — found in the IdP's SAML metadata XML as the `entityID` attribute
`idp_sso_url`	The IdP's SSO endpoint URL — where Kiwire sends the AuthnRequest. Found in IdP metadata as the `SingleSignOnService` location (HTTP-Redirect binding).
`idp_certificate`	The IdP's X.509 signing certificate in PEM format — used by Kiwire to verify the signature on SAML assertions. Found in IdP metadata as the `KeyDescriptor` element.

IdP signing certificates expire. When your IdP rotates its certificate, update the idp_certificate field in Kiwire immediately — an outdated certificate will cause all SAML logins to fail with a signature validation error.

SP Metadata XML

Kiwire generates a standard SAML 2.0 SP metadata XML document for each connector instance. Access it by clicking Download SP Metadata on the connector settings page, or via the direct URL shown in the UI. Import this file into your IdP to automatically configure the SP trust relationship.

Attribute Mapping

SAML assertions contain attributes that describe the authenticated user. Kiwire maps these attributes to user account fields. Configure the attribute mapping in the connector's Advanced Configuration section:

Kiwire Field	Common SAML Attribute Name
Username / email	`email`, `mail`, `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress`
Full name	`displayName`, `cn`, `http://schemas.microsoft.com/identity/claims/displayname`
First name	`givenName`, `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname`
Department	`department`

If the NameID format is set to emailAddress, Kiwire uses the NameID value directly as the username — attribute mapping for the email field is not required in that case.

Multiple SAML Instances

You can configure more than one SAML connector instance per tenant. Each instance has its own ACS URL and can point to a different IdP. Common use cases:

Separate IdPs for staff and external partners.
Multiple Azure AD tenants (one per subsidiary or location).
Okta for employees and ADFS for legacy systems, running in parallel.

Instances are distinguished on the captive portal by the instance Name (displayed as the SSO button label) — choose descriptive names like "Staff SSO" or "Partner Login".

Required Permissions

view-connector-saml · edit-connector-saml