Skip to content

Android SDK Integration#

This quickstart guide serves as an integration example for our trusted partners so that you will be able to test and/or evaluate LoginID’s authentication service for your own needs.

This document assumes that you are using Java/Kotlin in your development environment. Additional independent configuration options and integration mechanisms will be described in additional API Documentation that is still under development.

Info

This document is for LoginID Android SDK version 0_90_1X.

Create your client API keys#

The first step to onboard yourself with LoginID is to create your client credentials.

Credentials

This allows your servers to call LoginID services in an authenticated fashion. You will need to provide your Android package name and Android signing certificate fingerprint (sha256) to LoginID as part of the initial configuration setup. You will be able to find more information on fingerprint signing on the official android documentation page.

Field Name Value
Android Package Name com.example.myapplication
Android Signing Fingerprint (sha256) 72:90:77:A4:F1:6C:61:9F:4E:1F:11:94:0F:3B:8D:FC:3E:53:1F:FE:94:19:BF:FD:BD:4A:8D:90:05:32:B0:42
clientId 6fcd5bdd-bd51-4e26-9cd6-14f6e41b5862
baseUrl 060ce487-b934-43d0-a925-b66e80c7532f.sandbox.loginid.io

Note

Android signing fingerprint is a sha256 value of the signing certificate that used to sign your app.

Install LoginID SDK for your build environment#

This instruction is for configuring your Android Studio environment. The LoginID SDK requires min Android 5+ (API 21+) for compatibility. However, the core Fido2 Client of LoginID SDK will only work with Android 7+ (API 24+) devices.

First add LoginID maven repository and credential to your Android main project build.gradle. This will let you add the configuration to the code.

allprojects {
  repositories{
    google()
    jcenter()
    // ADD maven repository to download LoginSDK
    maven {
       url "https://sdk.dev.loginid.io/repository/maven-releases"
    }
}
Finally add the following packages to your Android app module build.gradle dependencies

implementation 'login.api.native:android-sdk:0.90.15'
implementation 'com.google.android.gms:play-services-fido:18.1.0'
implementation 'com.squareup.okhttp3:okhttp:4.2.1'

Getting started with LoginID API SDK:#

The following diagram illustrates how the different API functions of the LoginID SDK interact with your application and the Android platform. The API functions that you are responsible for are described in steps below and is marked by the blue arrows in the diagram.

image

Configure LoginID API#

LoginApi.client().configure(Context context, String clientId, String baseURL)

First you need to configure the SDK with your client API key and baseURL obtained from LoginID's developer console. This API must call before any other apis. You should call this API within your custom Application's onCreate() method. You can find more information on the process of creating a custom applicaiton on Understanding the Android Application Class.

class MyApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        // clientId example 032690b3-9bc4-4602-87c1-60c1fae782f2
        val clientId = "<your client api key>"
        // baseURL example https://060ce487-b934-43d0-a925-b66e80c7532f.sandbox.loginid.io
        val baseURL = "<your base url>"
        LoginApi.client().configure(this,clientId,baseURL)

        // any other configurations
        ...
        ...
    }
}
public class MyApplication extends Application {
    @Override
    public void onCreate() {
        super.onCreate();
        // clientId example 032690b3-9bc4-4602-87c1-60c1fae782f2
        final String clientId="<your client api key>";
        // baseURL example https://060ce487-b934-43d0-a925-b66e80c7532f.sandbox.loginid.io
        final String baseURL="<your base url>";
        LoginApi.client().configure(this,clientId,baseURL);

        // any other configurations
        ...
        ...
    }
}

Configure Android activity's onActivityResult#

Most of LoginID API core functionalities require access to the biometrics prompt. In order to handle the result from the biometrics, LoginID requires you to call LoginApi.client().handleIntentResult(int requestCode, int resultCode, Intent data) from your current Activity by overriding the onActivityResult() method.

    override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
        // register handle intent result from Android biometrics and such
        LoginApi.client().handleIntentResult(requestCode,resultCode,data)
        ...
        ...
    }
    @Override
    protected void onActivityResult(int requestCode, int resultCode, @Nullable Intent data) {
        // register handle intent result from Android biometrics and such
        LoginApi.client().handleIntentResult(requestCode,resultCode,data);

        ...
        ...
    }

Getting user account information#

Here is a set of functions for retrieving user information and login status.

  • check if user has existing registered account
    // return true or false
    val result = LoginApi.client().hasAccount()
    // return true or false
    boolean result = LoginApi.client().hasAccount();
  • get current username
    // return username in string value
    val username = LoginApi.client().getCurrentUsername()
    // return username in string value
    String username = LoginApi.client().getCurrentUsername();
  • check if user has active login session
    // return true or false
    val result = LoginApi.client().isLoggedIn()
    // return true or false
    boolean result = LoginApi.client().isLoggedIn();
  • get current access token which is the latest JWT token returned by the server after a successful registered or verified api called
    // return jwt in string value
    val token = LoginApi.client().getCurrentAccessToken()
    // return jwt in string value
    String token = LoginApi().client().getCurrentAccessToken();

Here are an example on how to use the above functionalities:

    if(LoginApi.client().hasAccount()){
      // get current username example
      val username = LoginApi.client().getCurrentUsername()
      // check if user has active login session
      if(LoginApi.client().isLoggedIn()){
          // get current token example
          val token = LoginApi.client().getCurrentAccessToken()
          ...
      } else {
          //present login option here
          ...
      }
      ...
    } else {
      // user has no account so can setup register user logic here
      ...
    }
    if(LoginApi.client().hasAccount()){
      // get current username example
      String username = LoginApi.client().getCurrentUsername();
      // check if user has active login session
      if(LoginApi.client().isLoggedIn()){
          // get current token example
          String token = LoginApi.client().getCurrentAccessToken();
          ...
      } else {
          //present login option here
          ...
      }
      ...
    } else {
      // user has no account so can setup register user logic here
      ...
    }

Register user account#

The registration flow of the api is shown in the following diagram

image

Register an account with username specified#

LoginApi.client().registerWithUsername(
    Activity activity,
    String username,
    RegisterCallback callback);
  • This api allows user to create new credential with username via a FIDO2 registration. Having username registered will allow user to login by username from multiple platforms.
val registerCallback= object: RegisterCallback {
    override fun onComplete(response: RegisterResponse) {
        if (response.success) {
            // example handle success case here
            Toast.makeText(
                this@MainActivity,
                "Register Success!!! " + response.jwt,
                Toast.LENGTH_LONG
            ).show()
        } else {
            // example handle failed case here
            Toast.makeText(this@MainActivity, "Register Failed!!! " + response.errorMessage, Toast.LENGTH_LONG)
                .show()
        }
    }
}
LoginApi.client().registerWithUsername(this@MainActivity,username,registerCallback)
final RegisterCallback registerCallback=new RegisterCallback() {
    @Override
    public void onComplete(RegisterResponse response) {
        if(response.success){
            // handle success case here
        } else {
            // handle error case here
            Log.e(TAG,response.errorMessage);
        }
    }
};
LoginApi.client().registerWithUsername(this, username, registerCallback);    

Login or re-authenticate an registered account#

Once the user has successfully registered, LoginID will assigned a JWT token to the response field. The token has a timestamp associate with it. You can ask the user to re-authenticate at anytime afterward based on your business logic or if the token expired.

LoginApi.client().login(
    Activity activity,
    LoginCallback callback);
  • This api allows user to authenticate or re-authenticate via a FIDO2 login operation. Should be called when previous access token is expired or invalid.
val loginCallback= object : LoginCallback {
    override fun onComplete(response: LoginResponse) {
        if(response.success){
            // sample handling success case
            Toast.makeText(this@MainActivity,"Verify Success!!!" + response.jwt, Toast.LENGTH_LONG).show()
        } else{
            //handle error case here
            Toast.makeText(this@MainActivity,"Verify Failed!!! - " + response.errorMessage, Toast.LENGTH_LONG).show()
        }
    }
}
LoginApi.client().login(this@MainActivity,loginCallback)
final LoginCallback loginCallback=new LoginCallback() {
    @Override
    public void onComplete(LoginResponse response) {
        if(response.success){
            // handle success case here
            ...
            ...
        } else {
            // handle error case here
            NSLog(TAG,response.errorMessage);
            ...
            ...
        }
    }

};
LoginApi.client().login(MainActivity.this,loginCallback);

Logout#

Call logout operation to invalidate the current access token.

LoginApi.client().logout()
LoginApi.client().logout();