Skip to main content

Dashboard SSO

Prompt-free single sign-on into the Biza Consumer Dashboard from your own digital channels.

Purpose​

Dashboard SSO enables consumers to move directly from a Data Holder's digital platform to the Biza Consumer Dashboard without signing in again. The Management API mints a short-lived, HMAC-signed JWT on your behalf, so you never need to manage or access the shared HMAC secret.

This feature is feature-flagged

Dashboard SSO is enabled by the dashboard-magic-link-sso feature flag, which is disabled by default. Speak to your account manager to enable it for your Space.

The flag name preserves this feature's earlier name. Magic Link SSO and Dashboard SSO refer to the same mechanism. You may also see "Magic Link" used as the name of a specific token-signing service (for example, the HCU Gateway's Magic Link service), which implements this same contract.

The Dashboard SSO flow​

1. Request a token from the Management API​

Call POST /dashboard/sso/request with the consumer's userId and, optionally, principalId:

{
"data": {
"userId": "3f29b6a1-0e5c-4b7a-9c1d-2a6e7f8b9c0d",
"principalId": "3f29b6a1-0e5c-4b7a-9c1d-2a6e7f8b9c0d"
}
}
These identifiers must match your Data Adapter
  • userId must be the same value your Data Adapter returns from Verify Login or Get User Principals. Biza does not generate, transform, or re-map this value.
  • principalId identifies the entity who data is being shared (a person or a business). The same principalId used in every other Adapter API call (listAccounts, getUserPrincipals, etc). See Get User for the full explanation of why userId and principalId are modelled separately.
  • For an individually-owned account, userId and principalId are often the same value because the consumer is only sharing their own accounts.
  • Neither identifier should contain personally identifiable information (PII), such as an email address or phone number, as these are stored in the CDR consent store. We recommend using UUID or another opaque identifier.

If principalId is omitted, the dashboard displays a principal selector when the user first logs in. If the user has only one principal, it is selected automatically. The Management API responds with:

{
"jwt": "eyJhbGciOiJIUzUxMiJ9...<snip>"
}

2. Redirect the consumer to the dashboard​

Send the consumer to:

https://<dashboard-host>/sso?request=<jwt>&isSsoLogin=true

The dashboard forwards the JWT as the request parameter of an OIDC authorization request to your Space's dashboard auth realm.

That's the whole integration

For a standard integration, this is everything you need. The rest of this page describes the token's contract in detail. It is primarily intended for troubleshooting, such as verifying or debugging a token generated by the Management API, or for where the Management API is unavailable (see Minting your own token below).

JWT reference​

The sub claim​

The sub (subject) claim is:

<userId>

or, if principalId was supplied in the request:

<userId>:<principalId>

split on the first colon only β€” these are exactly the values you supplied when requesting the token; Biza does not transform them. To recover your userId from a sub claim, split on the first colon and take the first element. This value is authoritative, even when both halves are identical.

Claim requirements​

ClaimRequiredValueValidation
issYesbiza-dashboardMust exactly match the client_id of the authorization request. Requests with a mismatched value are rejected.
audYesThe realm issuer URI, e.g. https://auth.example.com/<space>-dashboard-authMust contain the realm issuer URI. Rejected with Audience not recognised otherwise.
subYes<userId> or <userId>:<principalId>See The sub claim above.
nbfYesUnix timestampRejected with nbf is required if the nfb claim is missing, or nbf is in the future if the value is more than 5 seconds ahead of the server time.
expYesUnix timestampRejected with exp is required if teh exp claim is missing, or par has expired if the value is more than 5 seconds behind the server time. Also rejected with exp is greater than 60 minutes after nbf if exp βˆ’ nbf > 60 minutes. See the recommendation below.
iatRecommendedUnix timestampNot validated by the auth service, but should be set for auditability and to derive nbf/exp.
jtiNot usedβ€”Not present in tokens issued by the Management API; not required or validated.

A clock skew allowance of 5 seconds is applied to both nbf and exp.

Keep nbf tight and exp short

The exp βˆ’ nbf ≀ 60 minutes rule above is a FAPI ceiling, not a recommendation. For a single sign-on link, a 60-minute lifetime is far too permissive. A leaked or logged link remains valid for the entire nbf–exp window, so keep that window as short as possible. The Management API itself mints tokens with:

  • nbf = iat βˆ’ 30s (skew allowance only)
  • exp = iat + 30s

If you are minting your own token, use the same widths, and no more than iat + 120s for exp. Do not widen this window for convenience.

JWS signing requirements​

  • Algorithm: HS512 (HMAC-SHA512). No other algorithm is accepted for the biza-dashboard client.
  • Serialization: Compact JWS (header.payload.signature).
  • Secret encoding: The shared secret is stored base64-encoded in configuration, but signing is performed over the decoded raw bytes, not over the base64 string itself. This is the most common integration mistake: if you sign over the base64 text instead of the decoded bytes, verification will fail with Unable to verify HMAC Signed JWT.
  • Secret length: HMAC-SHA512 requires a key of at least 64 bytes (512 bits). A 64-byte random secret, base64 encoded, is 88 characters. Shorter secrets are rejected outright, or (for secrets long enough for a weaker algorithm but not HS512) may fail signature verification in confusing ways.
  • Header: typ and kid are neither required nor validated.

Worked example​

Decoded header:

{
"alg": "HS512"
}

Decoded payload:

{
"iss": "biza-dashboard",
"aud": "https://auth.example.com/example-dashboard-auth",
"sub": "3f29b6a1-0e5c-4b7a-9c1d-2a6e7f8b9c0d:3f29b6a1-0e5c-4b7a-9c1d-2a6e7f8b9c0d",
"iat": 1735689600,
"nbf": 1735689570,
"exp": 1735689630
}

Minting your own token​

For the small number of deployments that cannot reach the Management API and instead run a local token-signing service using the same shared secret, for example, the HCU Gateway's Magic Link service, the following are verified, working examples of correctly-formed tokens, taken from Biza's own example integrations.

Prefer the Management API

Use the Management API where possible. Self-minting requires you to correctly construct claims and securely manage the signing secret. Calling POST /dashboard/sso/request removes that responsibility entirely. Only self-mint if you have a specific reason you cannot call the Management API.

import com.nimbusds.jose.JWSAlgorithm
import com.nimbusds.jose.JWSHeader
import com.nimbusds.jose.JWSObject
import com.nimbusds.jose.crypto.MACSigner
import com.nimbusds.jwt.JWTClaimsSet
import java.time.OffsetDateTime
import java.util.*

fun makeJwt(secretBase64: String, clientId: String, aud: String, userId: String, principalId: String): String {
val sharedSecretBytes = Base64.getDecoder().decode(secretBase64)
val signer = MACSigner(sharedSecretBytes)
val iat = OffsetDateTime.now()
val claims = JWTClaimsSet.Builder()
.audience(aud)
.issuer(clientId)
.subject("$userId:$principalId")
.expirationTime(Date.from(iat.plusSeconds(30).toInstant()))
.notBeforeTime(Date.from(iat.minusSeconds(30).toInstant()))
.issueTime(Date.from(iat.toInstant()))
.build()

val jwsObject = JWSObject(JWSHeader(JWSAlgorithm.HS512), claims.toPayload())
jwsObject.sign(signer)

return jwsObject.serialize()
}
Treat the shared HMAC secret as a master credential

Anyone holding the shared HMAC secret can mint a valid SSO token for any userId/principalId pair in your Space as it is functionally equivalent to a bearer credential that can impersonate any consumer within your Space's dashboard auth realm. Store it in a secrets manager, never commit it to source control, restrict which systems can read it, and request us to rotate it if you suspect exposure.

Troubleshooting​

ErrorCauseFix
nbf is requirednbf claim missingAlways set nbf
nbf is in the futurenbf more than 5s ahead of server timeSet nbf to iat βˆ’ 30s, check clock sync
exp is requiredexp claim missingAlways set exp
par has expiredexp more than 5s behind server timeToken has expired, or exp set too tight; mint a fresh token per click
exp is greater than 60 minutes after nbfexp βˆ’ nbf > 60 minutesUse exp = iat + 30s or similar; see the tight-window guidance above
Audience not recognisedaud doesn't contain the realm issuer URIConfirm the exact issuer URI for your Space's dashboard auth realm
Unable to verify HMAC Signed JWTWrong secret, or signed over the base64 string instead of the decoded bytesBase64-decode the secret to raw bytes before signing
Could not parse hmac secret as base64Secret is not valid base64Confirm the secret is base64-encoded, not raw or hex
Request object issuer/client_id mismatchiss does not equal biza-dashboardSet iss to biza-dashboard