local_auth 0.2.1

  • README.md
  • CHANGELOG.md
  • Example
  • Installing
  • Versions
  • 97

local_auth

This Flutter plugin provides means to perform local, on-device authentication of the user.

This means referring to biometric authentication on iOS (Touch ID or lock code) and the fingerprint APIs on Android (introduced in Android 6.0).

Usage in Dart

Import the relevant file:

import 'package:local_auth/local_auth.dart';

We have default dialogs with an 'OK' button to show authentication error messages for the following 2 cases:

  1. Passcode/PIN/Pattern Not Set. The user has not yet configured a passcode on iOS or PIN/pattern on Android.
  2. Touch ID/Fingerprint Not Enrolled. The user has not enrolled any fingerprints on the device.

Which means, if there's no fingerprint on the user's device, a dialog with instructions will pop up to let the user set up fingerprint. If the user clicks 'OK' button, it will return 'false'.

Use the exported APIs to trigger local authentication with default dialogs:

var localAuth = new LocalAuthentication();
bool didAuthenticate =
    await localAuth.authenticateWithBiometrics(
    localizedReason: 'Please authenticate to show account balance');

If you don't want to use the default dialogs, call this API with 'useErrorDialogs = false'. In this case, it will throw the error message back and you need to handle them in your dart code:

bool didAuthenticate =
    await localAuth.authenticateWithBiometrics(
        localizedReason: 'Please authenticate to show account balance',
        useErrorDialogs: false);

You can use our default dialog messages, or you can use your own messages by passing in IOSAuthMessages and AndroidAuthMessages:

import 'package:local_auth/auth_strings.dart';

const iosStrings = const IOSAuthMessages(
    cancelButton: 'cancel',
    goToSettingsButton: 'settings',
    goToSettingsDescription: 'Please set up your Touch ID.',
    lockOut: 'Please reenable your Touch ID');
await localAuth.authenticateWithBiometrics(
    localizedReason: 'Please authenticate to show account balance',
    useErrorDialogs: false,
    iOSAuthStrings: iosStrings);

Exceptions

There are 4 types of exceptions: PasscodeNotSet, NotEnrolled, NotAvailable and OtherOperatingSystem. They are wrapped in LocalAuthenticationError class. You can catch the exception and handle them by different types. For example:

import 'package:flutter/services.dart';
import 'package:local_auth/error_codes.dart' as auth_error;

try {
  bool didAuthenticate = await local_auth.authenticateWithBiometrics(
      localizedReason: 'Please authenticate to show account balance');
} on PlatformException catch (e) {
  if (e.code == auth_error.notAvailable) {
    // Handle this exception here.
  }
}

iOS Integration

Note that this plugin works with both TouchID and FaceID. However, to use the latter, you need to also add:

<key>NSFaceIDUsageDescription</key>
<string>Why is my app authenticating using face id?</string>

to your Info.plist file. Failure to do so results in a dialog that tells the user your app has not been updated to use TouchID.

Android Integration

Update your project's AndroidManifest.xml file to include the USE_FINGERPRINT permissions:

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
          package="com.example.app">
  <uses-permission android:name="android.permission.USE_FINGERPRINT"/>
<manifest>

Sticky Auth

You can set the stickyAuth option on the plugin to true so that plugin does not return failure if the app is put to background by the system. This might happen if the user receives a phone call before they get a chance to authenticate. With stickyAuth set to false, this would result in plugin returning failure result to the Dart app. If set to true, the plugin will retry authenticating when the app resumes.

Getting Started

For help getting started with Flutter, view our online documentation.

For help on editing plugin code, view the documentation.

0.2.1

  • Updated Gradle tooling to match Android Studio 3.1.2.

0.2.0

  • Breaking change. Set SDK constraints to match the Flutter beta release.

0.1.2

  • Fixed Dart 2 type error.

0.1.1

  • Simplified and upgraded Android project template to Android SDK 27.
  • Updated package description.

0.1.0

  • Breaking change. Upgraded to Gradle 4.1 and Android Studio Gradle plugin 3.0.1. Older Flutter projects need to upgrade their Gradle setup as well in order to use this version of the plugin. Instructions can be found here.

0.0.3

  • Add FLT prefix to iOS types

0.0.2+1

  • Update messaging to support Face ID.

0.0.2

  • Support stickyAuth mode.

0.0.1

  • Initial release of local authentication plugin.

example/lib/main.dart

// Copyright 2017 The Chromium Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
import 'dart:async';

import 'package:flutter/material.dart';
import 'package:flutter/services.dart';
import 'package:local_auth/local_auth.dart';

void main() {
  runApp(new MyApp());
}

class MyApp extends StatefulWidget {
  @override
  _MyAppState createState() => new _MyAppState();
}

class _MyAppState extends State<MyApp> {
  String _authorized = 'Not Authorized';

  Future<Null> _authenticate() async {
    final LocalAuthentication auth = new LocalAuthentication();
    bool authenticated = false;
    try {
      authenticated = await auth.authenticateWithBiometrics(
          localizedReason: 'Scan your fingerprint to authenticate',
          useErrorDialogs: true,
          stickyAuth: false);
    } on PlatformException catch (e) {
      print(e);
    }
    if (!mounted) return;

    setState(() {
      _authorized = authenticated ? 'Authorized' : 'Not Authorized';
    });
  }

  @override
  Widget build(BuildContext context) {
    return new MaterialApp(
        home: new Scaffold(
      appBar: new AppBar(
        title: const Text('Plugin example app'),
      ),
      body: new ConstrainedBox(
          constraints: const BoxConstraints.expand(),
          child: new Column(
              mainAxisAlignment: MainAxisAlignment.spaceAround,
              children: <Widget>[
                new Text('Current State: $_authorized\n'),
                new RaisedButton(
                  child: const Text('Authenticate'),
                  onPressed: _authenticate,
                )
              ])),
    ));
  }
}

Use this package as a library

1. Depend on it

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


dependencies:
  local_auth: ^0.2.1

2. Install it

You can install packages from the command line:

with Flutter:


$ flutter packages get

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

3. Import it

Now in your Dart code, you can use:


import 'package:local_auth/local_auth.dart';
  
Version Uploaded Documentation Archive
0.2.1 Jun 1, 2018 Go to the documentation of local_auth 0.2.1 Download local_auth 0.2.1 archive
0.2.0 Mar 9, 2018 Go to the documentation of local_auth 0.2.0 Download local_auth 0.2.0 archive
0.1.2 Feb 28, 2018 Go to the documentation of local_auth 0.1.2 Download local_auth 0.1.2 archive
0.1.1 Jan 12, 2018 Go to the documentation of local_auth 0.1.1 Download local_auth 0.1.1 archive
0.1.0 Dec 20, 2017 Go to the documentation of local_auth 0.1.0 Download local_auth 0.1.0 archive
0.0.3 Dec 3, 2017 Go to the documentation of local_auth 0.0.3 Download local_auth 0.0.3 archive
0.0.1 Aug 17, 2017 Go to the documentation of local_auth 0.0.1 Download local_auth 0.0.1 archive
Popularity:
Describes how popular the package is relative to other packages. [more]
93
Health:
Code health derived from static analysis. [more]
100
Maintenance:
Reflects how tidy and up-to-date the package is. [more]
100
Overall:
Weighted score of the above. [more]
97
Learn more about scoring.

We analyzed this package on Oct 10, 2018, and provided a score, details, and suggestions below. Analysis was completed with status completed using:

  • Dart: 2.0.0
  • pana: 0.12.4
  • Flutter: 0.9.5

Platforms

Detected platforms: Flutter

References Flutter, and has no conflicting libraries.

Dependencies

Package Constraint Resolved Available
Direct dependencies
Dart SDK >=2.0.0-dev.28.0 <3.0.0
flutter 0.0.0
intl ^0.15.1 0.15.7
meta ^1.0.5 1.1.6
Transitive dependencies
collection 1.14.11
path 1.6.2
sky_engine 0.0.99
typed_data 1.1.6
vector_math 2.0.8