Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 21 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -547,6 +547,27 @@ _This technique used in the [example](https://github.com/go-pkgz/auth/blob/maste
The process can be simplified by doing all checks directly in `Validator`, but depends on particular case such solution
can be too expensive because `Validator` runs on each request as a part of auth middleware. In contrast, `ClaimsUpdater` called on token creation/refresh only.

### Linking an anonymous user after login

An app that lets users start anonymously (a direct provider, see [Direct authentication](#direct-authentication)) may want to move what they created to the account they log in with later. The library keeps no users, so the move is the app's job, and it must not happen automatically right after login: the email confirmation link and the Telegram token work from any browser, so an attacker can send his own confirmation link to a user who is in the middle of linking, that browser gets logged into the attacker's account, and an automatic merge would move the anonymous data there.

A flow that moves the data only after the user confirms the account, implemented and tested in [`v2/linking_example_test.go`](v2/linking_example_test.go). How much the confirmation protects depends on the provider, see the end of this section.

1. Make anonymous ids unguessable. With `AddDirectProvider` the id is a hash of the name, so anyone typing the same name gets the same id. Use `AddDirectProviderWithUserIDFunc` and add a random part:

```go
service.AddDirectProviderWithUserIDFunc("anonymous",
provider.CredCheckerFunc(func(string, string) (bool, error) { return true, nil }), // any name, no password
func(user string, _ *http.Request) string { return user + "::" + rand.Text() }) // crypto/rand
```

2. Before redirecting to `/auth/<provider>/login`, call your own endpoint with POST, behind `Middleware().Auth` and with the XSRF header (`Opts.XSRFHeaderKey`, `X-XSRF-TOKEN` by default). It checks that the current user is anonymous, stores a pending record server-side (a random nonce, the anonymous id, the provider the user is about to log in with, for email the address they are about to confirm, an expiration) and sets the nonce in an `HttpOnly`, `SameSite=Lax` cookie, `Secure` when `Opts.SecureCookies` is set. Take `Secure` from `Opts.SecureCookies` like the JWT cookie does, not from `r.TLS`, which is nil behind a TLS-terminating proxy: for a link without an address, whoever reads the nonce can log into his own account on that provider and confirm. An app framed by another site sets and clears the nonce cookie with `Opts.SameSiteCookie` and `Opts.PartitionedCookies` like the JWT cookie, otherwise confirm never gets the nonce back; this covers the logins that happen inside the frame (direct, Telegram, email), not oauth popups, and the XSRF header check stays on. The record must outlive the login it waits for: the email confirmation token is valid for 30 minutes after it is sent, so a link with an address lives that long plus time to confirm. Call start again right before every letter request, resends included: the user is still anonymous then, and the address binding keeps an earlier letter working. A link without an address can keep a short window, since its nonce alone is enough to move the data; a login slower than that leaves the data with the anonymous id. Take the record's expiration and the cookie's `MaxAge` from one value. Don't read the anonymous token inside the login flow itself: the oauth providers replace the JWT cookie with a handshake token at the start of the login. Reject a start for email without the address.
3. After the login, if the request carries the nonce cookie and the pending record is still alive, check the current user. Refuse a user who is still anonymous: the move would append the data to the same user and then delete it. Refuse a user of another provider than the one stored, and for email any id other than `"<verify provider name>_" + token.HashID(sha1.New(), address)`, with the name passed to `AddVerifProvider`; keep it in one constant, so the check cannot drift from the registration. The example tells the provider by the `<provider>_<hash>` form of the user id, which the built-in oauth, Apple, Telegram, direct and verify providers set, and compares the whole part before the last `_`, since a provider name may contain `_` itself. The dev provider, `NewCustomServer` with its default mapper, a custom `MapUserFn` and `AddCustomHandler` can return ids without it, and an `Opts.ClaimsUpd` can rewrite the id, so with those the app needs its own way to tell the provider. Then show `Move your anonymous data to <account>?` and remember the exact user id shown. Only a confirmation POST (with the same XSRF header) moves the data. The POST carries the user id the screen showed, and the move happens only when it equals both the current user id and the last id shown, so an old screen cannot confirm after the browser was logged into another account. Move the data and delete the pending record in one transaction, so the move cannot run twice.

Only an email login can be bound to a known identity. The display name proves nothing (for email it comes from the `user` query parameter), and for Telegram, the oauth providers and a direct provider with a password the app cannot know the user id in advance, while the name and avatar can be copied from the victim. An attacker who gets the user's browser to open his own login link for the same provider passes every check above, so for those providers the move rests on the user recognizing the account on the confirmation screen. If that is not enough, offer linking only through email.

The endpoints of steps 2 and 3 must reject a token passed in the query parameter named by `Opts.JWTQuery` (`token` by default) or in the header named by `Opts.JWTHeaderKey` (`X-JWT` by default). An option left unset stays empty in your `Opts`, so fall back to the default name. The middleware accepts those before the cookie and does not check the XSRF header for them. The flow relies on that XSRF check, so it does not work with `Opts.DisableXSRF` or with POST in `Opts.XSRFIgnoreMethods`.

### Multi-tenant services and support for different audiences

For complex systems a single authenticator may serve multiple distinct subsystems or multiple set of independent users. For example some SaaS offerings may need to provide different authentications for different customers and prevent use of tokens/cookies made by another customer.
Expand Down
Loading
Loading