Architecture: Asgardeo Android Core Auth Direct SDK for App Native Authentication

Asgardeo Android Core Auth Direct SDK Development Journey — Episode 3

Achintha Isuru
5 min readJun 10, 2024
Photo by Lance Anderson on Unsplash

Hi everyone, I’m back to continue our development journey of the new Asgardeo Android Core Auth Direct SDK. To recap, in episode 1, we went through our competitor analysis of similar SDKs. In the next episode, we discussed the learnings from the competitor analysis and how we plan to implement our SDK. If you haven’t read the previous episodes, you can find them here:

Episode 1: A Deep Dive into Mobile SDKs for App Native Authentication: A Competitor Analysis

Episode 2 : Building Blocks: Learnings from the Competitor Analysis

In today’s episode, I will detail the full architecture of the Asgardeo Android Core Auth Direct SDK that we are building in this journey.

Quick Overview of the Inner Workings of the Asgardeo App Native Authentication

Before diving into the architecture, it’s beneficial to have a basic understanding of app native authentication. If you are unfamiliar with app native authentication, you can find more details in our first episode.

The following diagram illustrates the high-level steps involved with app-native authentication. So let’s consider the following example and scenario:

  1. When the user clicks the login button, the app calls the /authorize endpoint, which returns the authenticators related to the first step [STEPS 1,2,3].
  2. If the user decides to authenticate with a username and password, the app will call the /authn endpoint and pass the username and password, continuing until there are no more authentication steps [STEPS 4,5,6].
  3. Finally, the necessary tokens can also be retrieved from exchanging the authorization code [STEPS 7].

Unlike the typical OIDC flow, where the user gets redirected to a browser window, this new app native authentication happens through REST APIs.

I hope you now have a good understanding of the inner workings of Asgardeo’s app native authentication. If you want to read more about app native authentication, you can do so by clicking on this link.

Architecture of the Asgardeo Android Core Auth Direct SDK

Now that we understand the inner workings of app native authentication, let’s look at the architecture of the Asgardeo Android Core Auth Direct SDK

Architecture of the Asgardeo Android Core Auth Direct SDK

The above image depicts the full-scale architecture of the Asgardeo Android Core Auth Direct SDK. This SDK can be divided into four main layers:

  1. Provider Layer
  2. Core Config Layer
  3. Core Layer
  4. Data Layer

Let’s look at each of these layers separately.

Provider Layer

This layer has all the functions needed by an Android developer to integrate app native authentication into their Android application. As shown in the diagram, the provider layer consists of three main components:

  1. Authentication Provider
  2. Token Provider
  3. Provider Managers

Both the Authentication and Token providers have wrapper functions that call functions in a provider manager, which then call the implemented functions in the core layer.

The Authentication Provider exposes functionality necessary for app native authentication, such as initializeAuthentication(), authenticateWithUsernameAndPassword(), and logout(). The Token Provider exposes functionality to handle tokens, such as getAccessToken() and validateAccessToken().

Provider Managers have manager classes that call functions in the core layer, for example, the user provider manager calls functions related to getting user information.

Core Config Layer

When using the SDK, the developer can either use the discovery endpoint or add all the necessary endpoints like authorize and token endpoints. This layer sets the SDK configurations based on the data provided by the developer. If the developer has entered the discovery endpoint of their Asgardeo organization, this layer will call it, fetch all necessary endpoints, and set them accordingly.

Core Layer

This layer contains all the implementations and is where the magic happens in the SDK. It consists of three components:

  1. Authentication Core
  2. Native Authentication Handler Core
  3. Managers

The Authentication Core and Native Authentication Handler Core are wrapper classes for functions implemented in the Managers. The provider layer interacts with these core classes without knowing the implementation details, which are encapsulated in the Managers.

The Authentication Core class holds wrapper functions for app native authentication-related functions. Additionally, the SDK provides functionality to call native authentication APIs directly, such as Google’s credential manager API. The Native Authentication Handler Core wraps those native functions, implemented in the native authentication handler managers.

The Managers handle specific unit actions; for example, the user manager handles API calls related to getting user information from Asgardeo. If you look closely in the managers component in the core layer you will see a manager called AppAuth Manager, which is responsible for calling the Android AppAuth SDK, to handle the lifecycle of the token. Since this SDK already has this logic implemented, we chose to use it directly in our SDK instead of reinventing the wheel.

Date Layer

The final layer in the SDK is the Data Layer. This layer is responsible for storing and retrieving token information in the phone memory. To store data, this SDK uses the datastore library provided by Android. This layer allows developers to skip the login interface when a user returns to their app and already has a valid token.

Why so many layers ?

Now that you have a better understanding of the architecture of the Asgardeo Android Core Auth Direct SDK, you might be wondering why there are so many layers in the Asgardeo Android Core Auth Direct SDK. The reason is to increase the maintainability of the SDK. By having multiple layers, the higher layers, such as the provider layer, are abstracted from the implementation details. This separation allows us to modify the implementation without affecting the developer’s code, ensuring a more robust and flexible SDK.


In this episode, we explored the architecture of the new Asgardeo Android Core Auth Direct SDK and briefly reviewed the inner workings of Asgardeo app native authentication. We also discussed the rationale behind the multi-layered architecture. If you found this article interesting, please share it with your colleagues and stay tuned for our next episode in this development journey.