The sign-in flow

Most triauth operations follow the same three stages. Your application starts it, the user's browser carries it to the authenticator, and your application finishes it.

The same three stages apply to every request type, from sign-in to signatures and attestations.

Stage 1: Request

Call Triauth.authenticate with the user's identifier and your callback URL. The library reads the user's DNS records and returns two strings.

• challenge is the request itself. Store it in the user's server-side session.
• redirectUrl is the address of the user's authenticator with the request attached. Redirect the browser there.

If the domain is not set up for triauth, or the identifier is malformed, you get an error with a code and a message instead.

This is also where you ask for more than a sign-in. In the same call, you can give your application's name and icon for the user's home screen, request the user's private profile, and request the tokens for later background checks, signatures, stamps, and attestations. See Extensions and tokens.

Stage 2: Redirect

The user's browser opens their authenticator. It shows your website's address and the identifier, and asks the user to approve or deny. On approval, the user's device signs the request. The authenticator then sends the browser to your callback URL with the signed response, by default as an HTTP POST with a response form field.

Keep the Referer header on the redirect. The authenticator may refuse a request that arrives without one, and it only needs your origin. Do not use rel="noreferrer", and check that security middleware does not set a no-referrer policy.

Stage 3: Verify

Read response from the callback request. Take challenge from your trusted session store. Call Triauth.authenticate with both. Then delete the challenge from the session, whatever the result.

This call returns a result object. On success, result.authenticated is true, and result.identifier is the verified identifier. On failure, result.error says why.

Upon successful authentication, the result carries the fields below. Store identifier and deviceTag with the session.

Field	Meaning
authenticated	true for a successful authentication.
identifier	The verified identifier, in lowercase. Use it as the key of the user's account.
identityDomain	The DNS name under which the identity records were read.
lookupCode	The identity's lookup code, for a private-mode domain. Empty otherwise. Needed to look the identity up again. Keep it private.
actor	The identifier of the delegate who signed in on the user's behalf. Empty for a direct sign-in. See Delegation.
actorIdentityDomain	The DNS name under which the actor's records were read. Empty for a direct sign-in.
actorLookupCode	The actor's lookup code, for a private-mode domain. Empty otherwise.
deviceName	The public name of the device that signed. For display only.
deviceTag	A fingerprint of the device, its lookup code, and the delegation used. Store it with the session and use it to re-check the session. A new value means a new device. Do not display it.
keys	The public keys of the device, as read from DNS, with their options and whether each one was verified or skipped.
groups	The identity's group names, qualified with the domain and sorted, such as admins@example.com. Empty when none are published. See Groups.
publicProfile	The name and initials the user published in DNS, if any. Escape them before you render.
secure	true when DNSSEC protected every record read. Decide what false means for you.
expires	The time until which the DNS records behind this sign-in count as fresh. A hint for when to re-check, with your own minimum interval. May be missing.
issuedAt	When you issued the challenge, by your server's clock.
signedAt	When the device signed the response, by the device's clock.
verifiedAt	When the response was verified, by your server's clock.
ext	Data from the extensions you requested, such as a private profile or tokens. See Extensions and tokens.

API reference:JavaScript

The callback URL

Choose a fixed callback URL in your configuration. The authenticator remembers your website by the base of this URL - its origin and path up to the last slash - and ties every token and permission to that base.

Account creation and new devices

Use the identifier as the account key. On the first sign-in, create the account. There is no password to set. Compare deviceTag with the devices you have seen for this account. A new device is normal, and it is also the moment to ask for a second factor if your risk profile calls for it.