Onboarding

Authenticate the atClient with the atServer

Overview

Onboarding is the process of authenticating to the atServer using it's associated atSign. Instead of the traditional username and password, this process uses the atSign's secret cryptographic keys to perform authentication.

Setup Process

Depending on the SDK you are using, the process for onboarding varies.

Dart

Dart

In Dart we provide the at_onboarding_cli package which handles onboarding to the atServer via files stored in the ~/.atsign/keys directory

Manual Configuration

Installation

First add the package to your project

dart pub add at_onboarding_cli

Or add the package to your pubspec.yaml manually:

dependencies:
  at_onboarding_cli: ^1.3.0

Usage

Set up the preferences to onboard to the atServer.

 AtOnboardingPreference atOnboardingConfig = AtOnboardingPreference()
    ..hiveStoragePath = '$homeDirectory/.$nameSpace/$fromAtsign/storage'
    ..namespace = nameSpace
    ..downloadPath = '$homeDirectory/.$nameSpace/files'
    ..isLocalStoreRequired = true
    ..commitLogPath = '$homeDirectory/.$nameSpace/$fromAtsign/storage/commitLog'
    ..rootDomain = rootDomain
    ..fetchOfflineNotifications = true
    ..atKeysFilePath = atsignFile
    ..atProtocolEmitted = Version(2, 0, 0);

Next get the onBoardingService

  AtOnboardingService onboardingService = AtOnboardingServiceImpl(
      fromAtsign, atOnboardingConfig,
      atServiceFactory: atServiceFactory);

Finally wait to be onboarded, this returns true once complete.

await onboardingService.authenticate();

This can be wrapped to check that the onboard was successful with the code snippet below.

bool onboarded = false;
  Duration retryDuration = Duration(seconds: 3);
  while (!onboarded) {
    try {
      stdout.write('\r\x1b[KConnecting ... ');
      await Future.delayed(Duration(
          milliseconds:
          1000)); // Pause just long enough for the retry to be visible
      onboarded = await onboardingService.authenticate();
    } catch (exception) {
      stdout.write(
          '$exception. Will retry in ${retryDuration.inSeconds} seconds');
    }
    if (!onboarded) {
      await Future.delayed(retryDuration);
    }
  }
  stdout.writeln('Connected');

Flutter

Flutter

In Flutter, we provide the at_onboarding_flutter package which handles secure management of these secret keys.

If you are developing a new Flutter app, we recommend that you use at_app to generate an app skeleton with the at_onboarding_flutter package preconfigured.

Manual Configuration

Installation

First add the package to your project:

flutter pub add at_onboarding_flutter

Or add the package to your pubspec.yaml manually:

pubspec.yaml

dependencies:
  flutter:
    sdk: flutter
  at_client_mobile: ^3.2.9
  at_onboarding_flutter: ^6.0.3

Usage

Simply call the onboard method whenever you want your app to open the onboarding widget.

AtOnboarding.onboard(
  context: context, // BuildContext
  config: AtOnboardingConfig(
    atClientPreference: AtClientPreference()
      ..rootDomain = AtEnv.rootDomain // access AtEnv from the `at_app_flutter` package
      ..namespace = AtEnv.appNamespace
      ..hiveStoragePath = dir.path
      ..commitLogPath = dir.path
      ..isLocalStoreRequired = true,
    rootEnvironment: AtEnv.rootEnvironment,
    domain: AtEnv.rootDomain,
    appAPIKey: AtEnv.appApiKey,
  ),
);

dir is a variable from holding data retrieved from the path_provider package: var dir = await getApplicationSupportDirectory();

AtEnv comes from at_app_flutter which also comes in the preconfigured app skeleton from at_app.

API Docs

You can find the API reference for the entire package available on pub.

The AtOnboarding class API reference is available here.