visa 2.0.0

Visa is an OAuth 2.0 package that makes it super easy to add third party authentication to flutter apps.

visa

This is an OAuth 2.0 package that makes it super easy to add third party authentication to flutter apps. It has support for FB, Google, LinkedIn, Discord, Twitch, Github, and Spotify, auth. It also provides support for adding new OAuth providers. You can read this medium article for a brief introduction.

Demo

Reference

• Getting Started
• Basic Usage
  • Get a Provider
  • Authenticate
  • Use AuthData
  • Rejoice!
• Debugging

Getting Started

Install visa:

• Open your pubspec.yaml file and add visa: under dependencies.
• From the terminal: Run flutter pub get.
• Add the relevant import statements in the Dart code.

// Possible imports:
import 'package:visa/fb.dart';
import 'package:visa/google.dart';
import 'package:visa/github.dart';
import 'package:visa/linkedin.dart';
import 'package:visa/discord.dart';
import 'package:visa/twitch.dart';
import 'package:visa/spotify.dart';
import 'package:visa/auth-data.dart';
import 'package:visa/engine/oauth.dart';
import 'package:visa/engine/simple-auth.dart';
import 'package:visa/engine/visa.dart';

Basic Usage

Step 1 - Get a Provider.

Implementing new providers is covered under Advanced Usage. There are 7 default OAuth providers at the moment:

  FacebookAuth()
  GoogleAuth({ String personFields })
  TwitchAuth()
  DiscordAuth()
  GithubAuth()
  LinkedInAuth()
  SpotifyAuth()

Create a new instance:

FacebookAuth fbAuth = FacebookAuth();
SimpleAuth visa = fbAuth.visa;

Step 2 - Authenticate.

As shown above, each provider contains a SimpleAuth instance called visa. The SimpleAuth class has only one public function: authenticate(). It takes in all the necessary OAuth credentials and returns a WebView that's been set up for authentication.

SimpleAuth.authenticate({ params })

WebView authenticate({
  bool newSession=false // If true, user has to reenter username and password even if they've logged in before
  String clientSecret, // Some providers (GitHub for instance) require the OAuth client secret (from developer portal).
  @required String clientID, // OAuth client ID (from developer portal)
  @required String redirectUri, // OAuth redirect url (from developer portal) 
  @required String state, // OAuth state string can be whatever you want.
  @required String scope, // OAuth scope (Check provider's API docs for allowed scopes)
  @required Function onDone, // Callback function which expects an AuthData object.
});

Here's how you would use this function:

import 'package:visa/auth-data.dart';
import 'package:visa/fb.dart';

class AuthPage extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      /// Simply Provide all the necessary credentials
      body: FacebookAuth().visa.authenticate(
          clientID: '139732240983759',
          redirectUri: 'https://www.e-oj.com/oauth',
          scope: 'public_profile,email',
          state: 'fbAuth',
          onDone: done
      )
    );
  }
}

In the sample above, the named parameter onDone is a callback which recieves a single arument: an AuthData object, which contains all the authentication info. We'll look at AuthData in the next section but here's how you would pass an AuthData object to the next screen via the onDone callback.

done(AuthData authData){
  print(authData);

  /// You can pass the [AuthData] object to a 
  /// post-authentication screen. It contaions 
  /// all the user and OAuth data collected during
  /// the authentication process. In this example,
  /// our post-authentication screen is "complete-profile".
  Navigator.pushReplacementNamed(
      context, '/complete-profile', arguments: authData
  );
}

Step 3 - Use AuthData.

The AuthData object contains all the information collected throughout the authentication process. It contains both user data and authentication metadata. As shown in the code sample above, this object is passed to the "authenticate" callback function. Let's have a look at it's structure:

class AuthData {
  final String userID; // User's profile id
  final String firstName; // User's first name
  final String lastName; // User's last name
  final String email; // User's email
  final String profileImgUrl; // User's profile image url
  final Map<String, dynamic> userJson; // Full returned user json
  final Map<String, String> response; // Full returned auth response.
  final String clientID; // OAuth client id
  final String accessToken; // OAuth access token
}

It provides shortcuts to access common user properties (userId, name, email, profile image) as well as the accessToken. The complete, returned user json can be accessed through the userJson property and you can access the full authentication response (the response in which we recieved an API access token) through the response property.

Step 4 - Rejoice!

You have successfully implemented third party auth in your app! you're one step closer to launch. Rejoice!

Debugging

To get debug logs printed to the console, simply set the debug parameter on a provider to true. Like this:

var fbAuth = FacebookAuth()
fbAuth.debug = true;

Happy OAuthing!

Reference:

• Getting Started
• Basic Usage
  • Get a Provider
  • Authenticate
  • Use AuthData
  • Rejoice!
• Debugging