People sign in to the dashboard with your identity provider and get the role their claims map to. This page is for the person who runs the control plane and has access to the identity provider. You will set up OIDC or SAML, and people will sign in with the company account they already use.
Set it up
- Choose a short org name, for example
acme. It appears in the sign-in links. - At your identity provider, register the control plane. For OIDC, register
https://<control-plane>/sso/<org>/callbackas the redirect URI. For SAML, openhttps://<control-plane>/saml/<org>/metadataand give the entity id and ACS URL to the provider. - Store the client secret (OIDC) as a Worker secret and set
SSO_ORGS(OIDC) orSAML_ORGS(SAML), as shown below. - Open
https://<control-plane>/sso/<org>/start(or/saml/<org>/start). After you sign in, both OIDC and SAML return{ "ok": true, "org": ..., "role": ..., "email": ..., "expires_at": ... }.
Routes
GET /sso/<org>/startredirects to the provider withstate,nonceand a PKCE challenge (S256).GET /sso/<org>/callbackchecks the state, exchanges the code, verifies the ID token, maps the claims to a role and creates a session.
The session is an HTTP-only sv_sso cookie that lasts 8 hours. The response is { ok, org, role, email, expires_at }.
Each sign-in link works once. A reused link, a mismatched state, an unknown org, a wrong audience or a person with no mapped role gets a plain message and no session.
Configuration
Set SSO_ORGS on the control plane to a JSON object keyed by org:
{
"acme": {
"issuer": "https://idp.acme.com",
"clientId": "shipvo",
"jwksUri": "https://idp.acme.com/jwks",
"authorizationEndpoint": "https://idp.acme.com/authorize",
"tokenEndpoint": "https://idp.acme.com/token",
"secretRef": "ACME_SSO_SECRET",
"mapping": { "groups": { "shipvo-admins": "admin" }, "emailDomains": { "acme.com": "viewer" } }
}
}secretRef names a Worker secret that holds the client secret. The secret is never in SSO_ORGS, logs or responses. Register https://<control-plane>/sso/<org>/callback as the redirect URI at the provider.
SAML
Companies that sign in with a SAML identity provider use the same sessions and roles.
GET /saml/<org>/startsends the person to the identity provider with an AuthnRequest. The request id works once and expires after 10 minutes.POST /saml/<org>/acstakes the signed response, checks it against the request, maps the attributes to a role and creates the samesv_ssosession as the OIDC login.GET /saml/<org>/metadatareturns the entity id (https://<control-plane>/saml/<org>) and the ACS URL (https://<control-plane>/saml/<org>/acs). Give both to the identity provider.
Set SAML_ORGS on the control plane to a JSON object keyed by org:
{
"acme": {
"issuer": "https://idp.acme.com/metadata",
"audience": "https://<control-plane>/saml/acme",
"certificate": "-----BEGIN CERTIFICATE-----...",
"ssoUrl": "https://idp.acme.com/sso",
"mapping": { "groupClaim": "groups", "groups": { "shipvo-admins": "admin" } }
}
}certificate is the identity provider's signing certificate. The mapping works as in the OIDC section. A response with the wrong issuer or audience, an expired or reused assertion, a bad signature, or an unknown or missing request id gets a plain message and no session.
Troubleshooting
- "Single sign-on is not set up for this organization" (or the SAML version): the org name in the link is not a key in
SSO_ORGSorSAML_ORGS. Check the spelling. - "Your account has no role in Shipvo. Ask an admin.": no group or email domain in
mappingmatches this person. Add the group or domain, then sign in again. - "The sign-in state does not match" or "already used or has expired": each sign-in link works once, and a SAML request lasts 10 minutes. Start again from
/start. - "The identity provider refused the sign-in code": the code was used already, or the redirect URI at the provider is not exactly the callback URL above.
- "The ID token was not accepted (...)" or "The sign-in response was not accepted (...)": the reason in brackets names the check that failed, such as the issuer, the audience, the expiry or the signature. Compare
issuer,audienceandcertificatewith the provider's values. - "Start the sign-in from Shipvo, not from the identity provider" (SAML): open
/saml/<org>/startrather than the tile in the provider's app list.
Next steps
- Self-hosting to deploy the control plane.
- Threat model for how sessions and tokens are protected.