Authentication
How to authenticate to an atServer
Dart
Package Installation
In Dart we provide the at_onboarding_cli package which handles onboarding to the atServer via files stored in the ~/.atsign/keys directory
Add the package to your project automatically using pub:
dart pub add at_onboarding_cliUsage
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
Finally wait to be onboarded, this returns true once complete.
This can be wrapped to check that the onboard was successful with the code snippet below.
Flutter
If you followed the Get Started guide for Flutter, then you should already have onboarding setup in your app. Feel free to skip this section and move on.
Package Installation
In Flutter, we provide the at_onboarding_flutter package which handles secure management of these secret keys.
Add the package to your project automatically using pub:
Usage
Simply call the onboard method whenever you want your app to open the onboarding widget.
API Key setup
To get an API key for your app, first head to the registrar website, then click manage under one of your atSigns:
Then open the Advanced settings drop down and click Generate New API Key:
C
Find the full example on our GitHub.
1. Fetch your atServer's address from the production atDirectory
First, include atclient_utils.h and #include <atclient/constants.h> at the top of you program.
Next, initialize variables that will hold the host and port of our atServer. We will pass pointers to these variables to the function that will populate these values for us.
Lastly, use the atclient_utils_find_atserver_address function to populate our atserver_host and atserver_port variables. This function returns an int for error handling. A non-zero exit code indicates an error.
Don't forget to free the atserver_host variable! It is mentioned in the documentation of the atclient_utils_find_atserver_address function that it is the responsibility of the caller to free this variable.
2. Load your atSign's atKeys
First, include atkeys.h.
Next, allocate memory for the atclient_atkeys struct. In this scenario, we are statically allocating. We need to call the atclient_atkeys_init function and pass a pointer to our atclient_atkeys struct. You will find this to be a common pattern when working with C structs. This is our method of mimicking object-oriented methodology in our C SDK.
Finally, call the atclient_utils_populate_atkeys_from_homedir function which will look for your ATSIGN's keys in your $HOME/.atsign/keys/ directory.
For example, if my atSign was @alice, I would have my @alice keys set up such that this file exists: $HOME/.atsign/keys/@alice_key.atKeys.
This function returns an int for error handling purposes. A non-zero exit code indicates that an error has occurred.
Don't forget to run atclient_atkeys_freeat the end of your application. You will see it as a common pattern that for every *_init function that we call, we must have a corresponding *_free function.
3. PKAM Authenticate
If your atSign's keys exist and your atSign's atServer is already activated, then this is known as pkam authentication.
First include atclient.h at the top of your application.
Secondly, we will create our atclient object. This variable holds data necessary for doing various operations on our atServer later on (such as CRUD or Events).
Thirdly, call the atclient_pkam_authenticate function.
This function connects to the atServer (if necessary) and uses your atSign's atKeys file to generate a special pkam command by signing a challenge sent from the atServer. Once pkam authentication is successful, your connection will be authenticated and your client will be free to make various operations on the atServer.
This function will return an int for error handling, in which a non-zero exit code indicates an error.
Lastly, do not forget to call atclient_free at the end of your application.
Example Application
Here is an example application that authenticates my atSign @jeremy_0.
This code is also available on our GitHub.
Last updated