Skip to main content

Production OAuth Flows

This guide describes the two production integration modes supported by WispHive Networks for SMEs, Educational Institutes, and ISPs.

Deployment model note:

  • Captive portals are hosted locally on the client's own network gateway.

OAuth-first integration rule​

Complete OAuth integration before pointing your captive portal at WispHive.

  1. Complete OAuth setup (hosted or AAA handoff).
  2. Validate redirect and callback behavior.
  3. Point your captive portal at the returned WispHive login and callback URLs.

1. WispHive-hosted OAuth entry​

Use this mode when you want captive portal logins to start on a WispHive-owned auth domain while keeping user lifecycle ownership inside your identity provider.

What you provide​

  • Your entity registration ID (sme_*, edu_*, or isp_*)
  • Provider metadata: authorize URL, token URL, JWKS URL
  • OAuth client credentials issued by your provider
  • The captive portal URL users should ultimately return to

What WispHive returns​

  • hosted_login_url
  • oauth_callback_url
  • derived_name, derived_email_domain, and a derived username format prefix
  • An integration ID for operational support and rotation workflows

Browser flow​

sequenceDiagram
    participant Browser
    participant Portal as Captive Portal
    participant WH as WispHive Auth Domain
    participant IdP as OAuth Provider

    Portal->>Browser: Link to hosted_login_url
    Browser->>WH: GET /oauth/start/{integration_id}
    WH->>IdP: Redirect to authorize URL
    IdP->>WH: Redirect back to oauth_callback_url
    WH->>Browser: Redirect to signed short-lived redirect URL

2. AAA handoff callback​

Use this mode when the entity keeps its own login UX and OAuth domain, then POSTs only derived, non-sensitive user identifiers back to WispHive using a signed callback contract.

What you provide​

  • Your entity registration ID
  • client_oauth_entry_url used in the captive portal
  • The captive portal URL the user should return to

What WispHive returns​

  • callback_url in the form https://auth.samwifi.site/cp/rdt/{slug}/{token}
  • wisphive_token for signing callback requests
  • derived_name, derived_email_domain, and a username format prefix for privacy-safe identifiers
  • A redirect base URL used for the short-lived redirect handoff

Callback contract​

Your backend POSTs to the returned callback_url with:

  • Content-Type: application/json
  • Idempotency-Key header
  • wisphive_token in the body (or X-WispHive-Token header)
  • userid as a UUID
  • entity_name
  • derived_username
  • derived_email
  • user_session_id
{
  "entity_name": "Acme SME",
  "userid": "4d57d5f0-b73f-4d84-b5d2-a06d7701f931",
  "derived_username": "acme-sme-cd45ef-user-94a7c1",
  "derived_email": "acme-sme-cd45ef-user-94a7c1@acme-sme-cd45ef.id.wisphive.net",
  "user_session_id": "sess_01J2Y8M92XH6Q3W6C2P9R4A7NN",
  "wisphive_token": "WH_Oid-a67d39t78sqcaRedsWte9_Kl90klhgyr37gHgfw-uiDlc35j9yUfa"
}

WispHive response​

{
  "success": true,
  "integration_id": "ah_8fa31d4c1b92d0",
  "event_id": "1722487101867-0",
  "redirect_url": "https://auth.samwifi.site/openid/cp/gAAAAABo...",
  "expires_in_seconds": 300
}

The redirect_url is short-lived and is intended to be used immediately by the captive portal flow.