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.
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"
}
}
userIdmust 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.principalIdidentifies the entity who data is being shared (a person or a business). The sameprincipalIdused in every other Adapter API call (listAccounts,getUserPrincipals, etc). See Get User for the full explanation of whyuserIdandprincipalIdare modelled separately.- For an individually-owned account,
userIdandprincipalIdare 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.
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β
| Claim | Required | Value | Validation |
|---|---|---|---|
iss | Yes | biza-dashboard | Must exactly match the client_id of the authorization request. Requests with a mismatched value are rejected. |
aud | Yes | The realm issuer URI, e.g. https://auth.example.com/<space>-dashboard-auth | Must contain the realm issuer URI. Rejected with Audience not recognised otherwise. |
sub | Yes | <userId> or <userId>:<principalId> | See The sub claim above. |
nbf | Yes | Unix timestamp | Rejected 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. |
exp | Yes | Unix timestamp | Rejected 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. |
iat | Recommended | Unix timestamp | Not validated by the auth service, but should be set for auditability and to derive nbf/exp. |
jti | Not 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.
nbf tight and exp shortThe 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 thebiza-dashboardclient. - 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:
typandkidare 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.
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.
- Kotlin
- TypeScript
- Python
- Go
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()
}
import jwt from "jsonwebtoken";
export interface MagicLinkConfig {
secretBase64: string;
clientId: string;
aud: string;
}
export function makeJwt(
cfg: MagicLinkConfig,
userId: string,
principalId: string
): string {
const secretBytes = Buffer.from(cfg.secretBase64, "base64");
const now = Math.floor(Date.now() / 1000);
return jwt.sign(
{
aud: cfg.aud,
iss: cfg.clientId,
sub: `${userId}:${principalId}`,
iat: now,
nbf: now - 30,
exp: now + 30,
},
secretBytes,
{ algorithm: "HS512" }
);
}
import base64
import time
import jwt
def make_jwt(secret_base64: str, client_id: str, aud: str, user_id: str, principal_id: str) -> str:
secret_bytes = base64.b64decode(secret_base64)
now = int(time.time())
payload = {
"aud": aud,
"iss": client_id,
"sub": f"{user_id}:{principal_id}",
"iat": now,
"nbf": now - 30,
"exp": now + 30,
}
return jwt.encode(payload, secret_bytes, algorithm="HS512")
package magiclink
import (
"encoding/base64"
"fmt"
"time"
"github.com/golang-jwt/jwt/v5"
)
func MakeJWT(secretBase64, clientID, aud, userID, principalID string) (string, error) {
secretBytes, err := base64.StdEncoding.DecodeString(secretBase64)
if err != nil {
return "", fmt.Errorf("decode secret: %w", err)
}
now := time.Now()
claims := jwt.MapClaims{
"aud": aud,
"iss": clientID,
"sub": fmt.Sprintf("%s:%s", userID, principalID),
"iat": jwt.NewNumericDate(now),
"nbf": jwt.NewNumericDate(now.Add(-30 * time.Second)),
"exp": jwt.NewNumericDate(now.Add(30 * time.Second)),
}
token := jwt.NewWithClaims(jwt.SigningMethodHS512, claims)
return token.SignedString(secretBytes)
}
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β
| Error | Cause | Fix |
|---|---|---|
nbf is required | nbf claim missing | Always set nbf |
nbf is in the future | nbf more than 5s ahead of server time | Set nbf to iat β 30s, check clock sync |
exp is required | exp claim missing | Always set exp |
par has expired | exp more than 5s behind server time | Token has expired, or exp set too tight; mint a fresh token per click |
exp is greater than 60 minutes after nbf | exp β nbf > 60 minutes | Use exp = iat + 30s or similar; see the tight-window guidance above |
Audience not recognised | aud doesn't contain the realm issuer URI | Confirm the exact issuer URI for your Space's dashboard auth realm |
Unable to verify HMAC Signed JWT | Wrong secret, or signed over the base64 string instead of the decoded bytes | Base64-decode the secret to raw bytes before signing |
Could not parse hmac secret as base64 | Secret is not valid base64 | Confirm the secret is base64-encoded, not raw or hex |
Request object issuer/client_id mismatch | iss does not equal biza-dashboard | Set iss to biza-dashboard |