Angel3 Anthentication
A complete authentication plugin for Angel3. Inspired by Passport. More details in the User Guide.
Installation
In your pubspec.yaml:
dependencies:
angel3_auth: ^10.0.0
Bundled Strategies
- Local (with and without Basic Auth)
- Find other strategies (Twitter, Google, OAuth2, etc.) on pub
Usage
Ensure you have read the User Guide.
import 'package:angel3_auth/angel3_auth.dart';
import 'package:angel3_framework/angel3_framework.dart';
import 'package:angel3_framework/http.dart';
void main() async {
var app = Angel();
var auth = AngelAuth<User>(
serializer: (user) => user.id ?? '',
deserializer: (id) => fetchAUserByIdSomehow(id),
);
// Middleware to decode JWT's and inject a user object...
await app.configure(auth.configureServer);
auth.strategies['local'] = LocalAuthStrategy((username, password) {
// Retrieve a user somehow...
// If authentication succeeds, return a User object.
//
// Otherwise, return `null`.
return null;
});
app.post('/auth/local', auth.authenticate('local'));
// Each strategy of a list is tried in turn. If one succeeds, the rest are
// skipped; if the last one fails, a `401 Not Authenticated` is thrown.
app.post('/auth/any', auth.authenticate(['local', 'basic']));
var http = AngelHttp(app);
await http.startServer('127.0.0.1', 3000);
}
class User {
String? id, username, password;
}
Future<User> fetchAUserByIdSomehow(String id) async {
// Fetch a user somehow...
throw UnimplementedError();
}
Security defaults
- A JWT expires after a day (
jwtLifeSpan, in milliseconds;-1for never, which is warned about with a fixedjwtKey). POST /auth/tokenexchanges a JWT that is still valid for a new one; an expired one only withinreviveGracePeriod(default: none). The user must still exist.- The
tokencookie isHttpOnly,SecureandSameSite=Lax(cookieSameSite), and is set when a user logs in, not for requests authenticated with anAuthorization: Bearerheader.logoutexpires it. - A JWT in the query string (
?token=) is ignored unlessallowTokenInQueryistrue, as query strings end up in logs, history andRefererheaders.
Default Authentication Callback
A frequent use case within SPA's is opening OAuth login endpoints in a separate window. angel3_client provides a facility for this, which works perfectly with the default callback provided in this package.
configureServer(Angel app) async {
var handler = auth.authenticate(
'facebook',
AngelAuthOptions(callback: confirmPopupAuthentication()));
app.get('/auth/facebook', handler);
// Use a comma to try multiple strategies!!!
//
// Each strategy is run sequentially. If one succeeds, the loop ends.
// Authentication failures will just cause the loop to continue.
//
// If the last strategy throws an authentication failure, then
// a `401 Not Authenticated` is thrown.
var chainedHandler = auth.authenticate(
['basic','facebook'],
authOptions
);
}
This renders a simple HTML page that fires the user's JWT as a token event in window.opener. angel3_client exposes this as a Stream:
app.authenticateViaPopup('/auth/google').listen((jwt) {
// Do something with the JWT
});
Migrating from 9.x to 10.0.0
The breaking changes of each release are listed in the CHANGELOG. Those of 10.0.0 that may need changes in an app:
-
JWT lifetime: a JWT expires after a day by default (
AngelAuth.defaultJwtLifeSpan). PassjwtLifeSpan(in milliseconds) for another lifetime;-1, which never expires, is warned about with a fixedjwtKey. -
Reviving JWTs:
POST /auth/tokenrenews a JWT that is still valid, and an expired one only withinreviveGracePeriod(default: none), if its user still exists. Clients that revived expired JWTs must log in again, or give a grace period:var auth = AngelAuth<User>( serializer: (user) => user.id ?? '', deserializer: (id) => fetchAUserByIdSomehow(id), reviveGracePeriod: const Duration(days: 7), ); -
Cookie: the
tokencookie isSameSite=Lax(cookieSameSite), and is set only when a user logs in or a JWT is revived, not for requests with anAuthorization: Bearerheader. -
Token in the query string:
?token=is ignored unlessallowTokenInQueryistrue. Enable it for the browser WebSocket client ofangel3_websocket, which cannot send headers. -
Claims: JWTs have the standard
iatandexpclaims, in seconds. JWTs issued by 9.x are still read.
Libraries
- angel3_auth
- auth_token
- Stand-alone JWT library.