SSO: OpenID Connect and SAML
Trowyn can be the identity provider for your apps and for Okta, Microsoft Entra ID and Google Workspace. Your users sign in by approving a push on their phone: they type their username, Trowyn shows a number, they tap the same number in Trowyn and confirm with Face ID. No passwords are involved, and there's no long-lived Trowyn session: every sign-in is a fresh approval.
SSO is part of the Business plan. Like everything else, it's free during early access. See pricing.
Okta
Trowyn as an OpenID Connect or SAML identity provider, or as an MFA factor.
Microsoft Entra ID
Federate a custom domain to Trowyn with SAML 2.0.
Google Workspace
A third-party SAML SSO profile for your users.
Any OIDC or SAML app
Your own app, or any product with "Sign in with SSO".
Before you start
- Link your users' phones the usual way (quickstart). For SSO, link each user with
the username they'll type at sign-in as the
external_user_id, normally their work email (for examplealice@acme.example). Matching is exact, with a second try in lower case. - In the console, open SSO and add an app. Test apps work right away and only reach phones linked in test mode; live apps need an approved organization.
Your identity provider URLs
Each organization has one issuer per environment. The console's SSO page shows yours with copy buttons.
| URL | |
|---|---|
| Issuer / SAML Entity ID | https://trowyn.com/sso/<org id>/<live or test> |
| OIDC discovery | <issuer>/.well-known/openid-configuration |
| Authorization endpoint | <issuer>/authorize |
| Token endpoint | <issuer>/token |
| Userinfo endpoint | <issuer>/userinfo |
| JWKS | <issuer>/jwks |
| SAML SSO URL (HTTP-Redirect and HTTP-POST) | <issuer>/saml |
| SAML metadata | <issuer>/saml/metadata |
| SAML signing certificate (PEM) | <issuer>/saml/certificate.pem |
| IdP-initiated sign-in | <issuer>/saml/idp/<app id> (optional ?RelayState=…) |
OpenID Connect
- Flow: authorization code, with PKCE (
S256).response_type=code;response_modequery(default) orform_post. Scopes:openid(required),profile,email. - Clients: confidential (server apps; client secret with
client_secret_basicorclient_secret_post; PKCE optional, or required if you tick it) or public (single-page and mobile apps; no secret; PKCE always required). - Codes are single-use and expire after 60 seconds. Reusing a code fails and revokes the access
token issued for it. Access tokens last 10 minutes and only work at
userinfo. There are no refresh tokens: start a new sign-in when you need one. - ID token (RS256, 5 minutes):
iss,sub(the user'sexternal_user_id),audandazp(your client ID),iat,exp,auth_time(when the phone approved),nonce(if you sent one),amr(["hwk","mfa","user"], or withoutuserif your policy doesn't require Face ID),at_hash,jti, plus the mapped claims below. Test apps add"trowyn_environment": "test". - Signing keys rotate automatically every 90 days. The next key appears in the JWKS a week before
it's used, and old keys stay published for 7 days. Use the
kidand refresh the JWKS when you see a new one, as every OIDC library does. prompt=nonealways returnslogin_required: Trowyn asks the phone for every sign-in.- Redirect URIs are matched exactly (no wildcards, no prefix matching).
https://only;http://localhostis allowed for test apps.
GET https://trowyn.com/sso/<org>/<env>/authorize?response_type=code
&client_id=trw_oidc_test_…&redirect_uri=https%3A%2F%2Fapp.example%2Fcallback
&scope=openid%20email%20profile&state=…&nonce=…
&code_challenge=…&code_challenge_method=S256&login_hint=alice%40acme.example
SAML 2.0
- SP-initiated (HTTP-Redirect or HTTP-POST binding for the AuthnRequest) and IdP-initiated (unsolicited) sign-in. Responses go to the ACS URL with the HTTP-POST binding.
- The assertion is always signed; the response is signed too unless you turn that off (RSA-SHA256, SHA-256 digests, exclusive canonicalization). AuthnRequest signatures aren't required or checked; instead, the SP's Entity ID and ACS URL must exactly match what you registered.
- Assertions are valid for 5 minutes, carry
InResponseTo,Recipientand anAudienceRestriction, and each sign-in produces exactly one response. An AuthnRequest ID can only be used once. - NameID formats:
unspecified(default),emailAddress,persistent. IsPassive="true"requests can't succeed (the phone must approve), and are refused.- Certificate: one per organization and environment, valid 10 years. To rotate, choose New certificate in the console: it's added to your metadata straight away, so you can add it to each service provider, then choose Make active.
- Single logout isn't supported. Trowyn keeps no sign-in session to end.
Attribute mapping
Each app has an optional mapping. Values are text with placeholders:
| Placeholder | Value |
|---|---|
{user} |
The user's external_user_id, for example alice@acme.example |
{user_local} |
The part before @ (alice) |
{label} |
The link label you set when linking the phone |
{org} |
Your organization name |
Without a mapping, OIDC sends preferred_username = {user}, email = {user} (if it contains @)
and name = {label}; SAML sends NameID = {user} and the attributes email and name the same way.
Standard OIDC claims follow the scopes (email, email_verified need email; name,
preferred_username and the like need profile); custom claims are always sent. email_verified
is only sent if you map it to true, so only do that if you verify emails before linking.
{
"nameid": "{user}",
"authn_context": "urn:oasis:names:tc:SAML:2.0:ac:classes:unspecified",
"attributes": { "email": "{user}", "displayName": "{label}", "department": "Engineering" }
}
nameid and authn_context apply to SAML only. Claims Trowyn sets itself (iss, sub, aud, exp,
nonce, amr and so on) can't be mapped.
What the user sees
- The app sends them to Trowyn's sign-in page (
trowyn.com/signin), which names the app and your organization (with [TEST] for test apps). - They enter their username (pre-filled from
login_hintor the SAML Subject). - Their phone gets the push. The page shows the number to tap (if number matching is on).
- They approve in Trowyn with Face ID. The page sends them back to the app.
If they deny it or it times out, they can try again (up to 5 tries per sign-in) or cancel, which
returns access_denied (OIDC) or a signed AuthnFailed response (SAML) to the app. For a username
with no linked phone, the page behaves exactly like a real request and simply times out, so it can't
be used to discover who has Trowyn.
Security
- Sign-in sessions are bound to the browser that started them by a first-party,
HttpOnly,SameSite=Laxcookie, and expire after 10 minutes. A link copied to another browser doesn't work. stateis returned unchanged;nonceis put in the ID token; both are limited in size.- Rate limits per IP address, per app and per user (the same 5-pushes-a-minute limit as the API).
- Every step is in your audit log:
sso_authorize,sso_signin_started,sso_signin_approved,sso_signin_denied,sso_signin_expired,sso_signin_cancelled,sso_token_issued,sso_code_replay,sso_redirect_uri_rejected,sso_acs_rejectedandconsole_sso_*changes. - SSO sign-ins are normal approvals: they appear under Approvals, fire your
approval.*webhooks (withcontext.source = "sso") and count towards monthly active users. - Client secrets are shown once and stored as SHA-256 hashes. Signing keys are kept in an encrypted secret store; only public keys and certificates are published.