Tagl ID integration guide

Use this page when adding Sign in with Tagl ID to a website or service. Tagl ID is an OpenID Connect provider. Your application is an external relying party (RP): it authenticates users through the public OIDC contract and keeps its own application session and permissions.

1. Create an application

1. Unlock your tagl and open the Developers tab.
2. Select New app.
3. Enter the name users should see on the consent screen and at least one callback URL.
4. Copy the generated client_id into your application's server configuration.

Redirect URLs are exact. Use https:// in a deployed service. The only HTTP exception is literal loopback development: http://localhost[:port] or http://127.0.0.1[:port]. A LAN URL such as http://192.168.x.x is rejected on purpose — do not weaken it; put the service behind HTTPS instead.

For loopback development, open your application at the same host as its registered callback. For example, a callback on http://localhost:9120 means start the browser at http://localhost:9120, not at a LAN IP. Login transaction cookies are host-specific.

2. Configure your OIDC library

Configure the issuer/discovery URL:

https://id.tagls.com

Read endpoints and signing keys from discovery rather than hard-coding them:

https://id.tagls.com/.well-known/openid-configuration

Use Authorization Code flow with PKCE S256 and scope openid. A normal server-side application does not need CORS or browser token exchange. Choose the Browser SPA option only when the browser must exchange the code itself; tokens in JavaScript increase the impact of an XSS bug.

3. Implement the login flow

On every login, generate CSPRNG values for state, nonce and the PKCE verifier. Keep them in a short-lived server-side transaction. Give the browser only an opaque, HttpOnly, Secure, SameSite=Lax one-shot transaction handle — never trust plain mutable OIDC values copied back from a cookie.

Redirect the browser to the discovered authorization endpoint with:

client_id, redirect_uri, response_type=code, scope=openid,
state, nonce, code_challenge, code_challenge_method=S256

On the callback, validate state before exchanging the code. Exchange the code server-to-server at the token endpoint with the same redirect_uri, your client_id and the saved PKCE verifier. Tagl ID public clients have no client secret.

4. Verify before creating a session

Verify the returned ID token before your application signs anyone in:

• pin the signing algorithm to EdDSA and verify its signature through JWKS;
• validate issuer, audience, expiry, nonce and expected token use;
• use the non-empty sub claim as the stable Tagl ID identity;
• map that verified sub to your own roles and permissions.

Do not grant permissions merely because a token is valid. Tagl ID confirms an identity; your service owns authorization.

5. Protect the integration

• Do not ask users for their tagl file, PIN, private key, recovery words or TOTP codes. An integrating app never needs them.
• Do not log callback URLs, authorization codes, tokens, verifier, state or nonce. Set Referrer-Policy: no-referrer on auth responses.
• Create a fresh opaque application session only after validation; rotate it on successful login and revoke it on local logout.
• Cache JWKS keys by kid. For an unknown key, re-fetch once and then use a short negative cache so invalid tokens cannot amplify requests to Tagl ID.

6. Test before release

Prove a successful login, cancellation, wrong state, wrong nonce, expired or wrong-audience token, invalid signature, exact callback mismatch, a user with no local role, and logout/session revocation.

For a machine-readable contract suitable for coding agents, use /llms.txt. The complete technical reference is maintained with the Tagl ID source under docs/taglid/.