jaguar_auth 2.4.4

jaguar_auth #

Username password based authentication interceptors and helper functions for Jaguar. This package builds on Session infrastructure provided by Jaguar.

Authorization #

Authorization in jaugar_auth revolves around three basic principles:

  • User Model
    A User model that can be uniquely identified.
  • User Fetcher
    Logic to fetch the user model by its unique identity.
  • Authorizer
    Checks if the request has correct and proper user identity.

User model #

AuthorizationUser establishes an interface user models must implement to operate with Authorizer.

AuthorizationUser demands that the model implements a getter named authorizationId that uniquely identifies the user. This is usually stored in session to associate session with a user.

Typically, user id, email or username is used as authorizationId.

Example #

The user model User uses user id as authorizationId. Notice that User implements AuthorizationUser interface.

class User implements AuthorizationUser {
  String id;

  String username;

  String password;

  User(this.id, this.username, this.password);

  String get authorizationId => id;
}

User fetcher #

UserFetcher imposes an interface to fetch user model during authentication and authorization. To achieve this, two methods shall be implemented: byAuthenticationId and byAuthorizationId.

Example #

class MgoUserManager<ModelType extends PasswordUser>
    implements UserFetcher<ModelType> {
  final String collection;

  final List<String> fieldNames;

  final Serializer<ModelType> serializer;

  MgoUserManager(this.serializer,
      {this.collection: 'user', this.fieldNames: const ['username']});

  Future<ModelType> byAuthorizationId(Context ctx, String userId) async {
    final Db db = ctx.getVariable<Db>();
    final DbCollection col = db.collection(collection);
    Map map = await col.findOne(mgo.where.id(mgo.ObjectId.parse(userId)));
    return serializer.fromMap(map);
  }

  Future<ModelType> byAuthenticationId(Context ctx, String authId) async {
    final Db db = ctx.getVariable<Db>();
    final DbCollection col = db.collection(collection);

    for (String fieldName in fieldNames) {
      Map map = await col.findOne(mgo.where.eq(fieldName, authId));
      if (map == null) continue;
      return serializer.fromMap(map);
    }

    return null;
  }
}

A user fetcher can be registered using userFetchers member of Jaguar class.

main() async {
  final server = new Jaguar(port: 10000);
  server.userFetchers[User] = MgoUserManager<User>(userMgoSerializer);
  // ... Add routes here ...
  await server.serve(logRequests: true);
}

Authorizer #

Authorizer authorizes the requests. If the authorization fails, it responds with a 401 HTTP error. If the authorization succeeds, it returns the user model of the authorized user.

Example #

/// Collection of routes students can also access
@Controller(path: '/book')
@Intercept([mongoInterceptor, Authorizer<User>()])
class StudentRoutes {
  @Get(path: '/all')
  Response<String> getAllBooks(Context ctx) {
    List<Map> ret =
        _books.values.map((Book book) => bookSerializer.toMap(book)).toList();
    return Response.json(ret);
  }
}

Authentication #

Three types of authenticators are on offer:

  1. Basic auth
  2. Form auth
  3. JSON auth

Basic auth #

BasicAuth performs authentication based on basic authentication.

It expects base64 encoded "username:password" pair in "authorization" header with "Basic" scheme.

Example #

main() async {
  final server = Jaguar(port: 10000);
  server.postJson(
    '/login',
    // Authentication
    (Context ctx) async => await BasicAuth.authenticate<User>(ctx),
  );
  // ... Your routes here ...
  await server.serve();
}

Form auth #

An authenticator for standard username password form style login. It expects a application/x-www-form-urlencoded encoded body where the username and password form fields must be called username and password respectively.

Example #

@Controller()
class AuthRoutes {
  @PostJson(path: '/login')
  @Intercept(const [const FormAuth<User>()])
  User login(Context ctx) => ctx.getVariable<User>();
}

Json auth #

An authenticator for standard username password login using ajax requests. It expects a application/json encoded body where the username and password fields must be called username and password respectively.

Example #

@Controller()
class AuthRoutes {
  @PostJson(path: '/login')
  @Intercept(const [const JsonAuth<User>()])
  User login(Context ctx) => ctx.getVariable<User>();

  @Post(path: '/logout')
  Future logout(Context ctx) async {
    // Clear session data
    (await ctx.session).clear();
  }
}

Changelog #

2.2.4 #

  • Bug fix in password checking

2.2.1 #

  • Added UnauthorizedException

2.1.9 #

  • Bug fix for throwOnFail

2.1.8 #

  • Authorizer has throwOnFail to control response when authorization fails.

2.1.5 #

  • Updated README

2.1.4 #

  • Updated README

2.1.1 #

  • Simplified authenticator

1.2.14 #

  • Uses Jaguar 1.2.14 style Interceptor

0.2.1 #

  • Jaguar 1.2.x

0.12.0 #

  • Renames methods on AuthModelManager to be shorter
  • Made methods on AuthModelManager FutureOr

0.11.3 #

  • Moved to jaguar_serializer 0.5.x

0.11.0 #

  • Uses Session from jaguar package

0.0.1 #

  • Initial version, created by Stagehand

Use this package as a library

1. Depend on it

Add this to your package's pubspec.yaml file:


dependencies:
  jaguar_auth: ^2.4.4

2. Install it

You can install packages from the command line:

with pub:


$ pub get

with Flutter:


$ flutter pub get

Alternatively, your editor might support pub get or flutter pub get. Check the docs for your editor to learn more.

3. Import it

Now in your Dart code, you can use:


import 'package:jaguar_auth/jaguar_auth.dart';
  
Popularity:
Describes how popular the package is relative to other packages. [more]
18
Health:
Code health derived from static analysis. [more]
87
Maintenance:
Reflects how tidy and up-to-date the package is. [more]
99
Overall:
Weighted score of the above. [more]
55
Learn more about scoring.

We analyzed this package on Jul 17, 2019, and provided a score, details, and suggestions below. Analysis was completed with status completed using:

  • Dart: 2.4.0
  • pana: 0.12.19

Platforms

Detected platforms: Flutter, other

Primary library: package:jaguar_auth/jaguar_auth.dart with components: io.

Health suggestions

Fix lib/authenticators/form_auth.dart. (-3.93 points)

Analysis of lib/authenticators/form_auth.dart reported 8 hints, including:

line 33 col 30: Use = to separate a named parameter from its default value.

line 34 col 25: Use = to separate a named parameter from its default value.

line 35 col 18: Use = to separate a named parameter from its default value.

line 46 col 7: DO use curly braces for all flow control structures.

line 59 col 7: DO use curly braces for all flow control structures.

Fix lib/authenticators/basic_auth.dart. (-3.45 points)

Analysis of lib/authenticators/basic_auth.dart reported 7 hints, including:

line 34 col 30: Use = to separate a named parameter from its default value.

line 35 col 25: Use = to separate a named parameter from its default value.

line 36 col 18: Use = to separate a named parameter from its default value.

line 67 col 7: DO use curly braces for all flow control structures.

line 95 col 32: Use = to separate a named parameter from its default value.

Fix lib/authenticators/json_auth.dart. (-3.45 points)

Analysis of lib/authenticators/json_auth.dart reported 7 hints, including:

line 33 col 30: Use = to separate a named parameter from its default value.

line 34 col 25: Use = to separate a named parameter from its default value.

line 35 col 18: Use = to separate a named parameter from its default value.

line 58 col 7: DO use curly braces for all flow control structures.

line 76 col 32: Use = to separate a named parameter from its default value.

Fix additional 3 files with analysis or formatting issues. (-2.99 points)

Additional issues in the following files:

  • lib/authorizer/authorizer.dart (4 hints)
  • lib/authenticators/authenticators.dart (1 hint)
  • lib/hasher/hasher.dart (1 hint)

Maintenance suggestions

The package description is too short. (-1 points)

Add more detail to the description field of pubspec.yaml. Use 60 to 180 characters to describe the package, what it does, and its target use case.

Maintain an example.

None of the files in the package's example/ directory matches known example patterns.

Common filename patterns include main.dart, example.dart, and jaguar_auth.dart. Packages with multiple examples should provide example/README.md.

For more information see the pub package layout conventions.

Dependencies

Package Constraint Resolved Available
Direct dependencies
Dart SDK >=2.0.0-dev.65 <3.0.0
crypto ^2.0.3 2.0.6
jaguar ^2.4.2 2.4.36
jaguar_common ^2.1.4 2.1.4
Transitive dependencies
auth_header 2.1.4
charcode 1.1.2
collection 1.14.11
convert 2.1.1
http_server 0.9.8+3
jaguar_serializer 2.2.12
logging 0.11.3+2
meta 1.1.7
mime 0.9.6+3
path 1.6.2
path_tree 2.2.2
stack_trace 1.9.3
typed_data 1.1.6
Dev dependencies
http ^0.11.3
jaguar_client ^2.4.2
jaguar_example_session_models ^2.1.6
jaguar_reflect ^2.4.1
jaguar_resty ^2.8.5
test ^1.3.0

Admin