Building Custom Mobile SSO Workflows (Android/iOS)

Appdome-DEV Events provide a framework to pass user details contained in an OpenID and SAML authentication response to the app developer. This framework provides flexibility to build Custom Mobile SSO Workflows inside any Android/iOS app, using industry-standard methods to retrieve and pass user details between authentication services and mobile apps. 

This Knowledge Base article explains how to build Custom Mobile SSO Workflows inside Android and iOS apps to retrieve and pass user details between authentication services and mobile apps.

We hope you find this knowledge base useful and enjoy using Appdome!

Building Custom SSO Workflows (in Android and iOS Apps)

Adding Single Sign-On (SSO) to Android and iOS apps involves several significant considerations. Perhaps the most significant consideration is “where” and “when” the SSO workflow will take place inside the app. Usually, an SSO workflow is initiated at the start of a login sequence. In this use case, the client and the server are built to handle the basic authentication sequence (User –> launches app –> enters credentials –> credentials verified by the server –> user issued a token or cookie allowing access to the app).

But, what if the app developer hasn’t built or doesn’t want to build support for basic authentication? Or, what if the app developer wants more than the username and password provided in the basic authentication workflow (e.g., access to user details available in new authentication methods)? In these cases, Appdome-DEV Events provide a framework to pass user details contained in an OpenID and SAML authentication response to the app developer. This framework allows new flexibility to create custom SSO workflows inside an app using industry-standard methods to retrieve and pass user details between authentication services and mobile apps. 

Many organizations use Identity Providers (IdPs) like Azure AD, Okta, Ping, etc. These authentication services usually connect on the backend to a store of user data and use SAML or OpenID to handle authentication requests. Using SAML and OpenID, applications have access to all the user and authentication details returned by the server backend (i.e. any data the backend implements).

This article will demonstrate how Appdome can pass these user details to an app at any point in the application logic, at launch, or otherwise. 

Prerequisites for Building Custom Mobile SSO Workflows Inside Android and iOS Apps

In order to use Appdome-DEV Events you need:

Using Appdome-DEV Events to Build Custom Mobile SSO Workflows in Android and iOS apps

With OAuth, OpenID (over OAuth) or Saml, apps can perform standard authentication and authorization flows. When using SSO, Tokens are supplied to the client upon successful authentication/authorization. These tokens contain data components that can be further used to access protected resources and gather user information such as user ID, email address and more.

A detailed description of the information that can be found in these tokens can be found here: Microsoft, Okta.

Developer’s Flow:

  1. App registers to an Appdome-DEV Event.
  2. Once the application accesses a protected resource, Appdome Mobile SSO will begin the authentication flow as described here.
  3. When the authentication flow has completed, Appdome sends a notification to the app which contains information extracted from the tokens.

Event Description:

The event sent by Appdome will be called “AuthInfoEvent” and will comprise of a dictionary that contains the following fields (all strings):

“Authenticated” A boolean value (as a string) indicating whether the authentication flow has completed successfully.
“UserName” User identifier extracted from the idToken token, this could be a username, email or any other unique user identifier.
“AccessToken” The access token incorporated in the OAuth token that was provided by the authenticating party as a result of successful authentication. This token should be used to access protected resources governed by the authenticating party.
“DecodedAccessToken” The decoded body of the access token. Includes various data on the user as well as the requested scopes.
“IdToken” The id_token is a JSON Web Token (JWT) that contains user profile information (such as the user’s name and email) which is represented in the form of claims. These claims are statements about the user.
“decodedIdToken” The decoded form of the id_token, this will hold all the claims correlating to the user’s authentication request. Content may vary between different authenticating parties.
“SamlRequest” the SSO request sent to the identity provider.
“DecodedSamlRequest” the inflated and decoded SAML request.
“SamlResponse” the SSO response that contains the assertions.
“DecodedSamlResponse” the decoded SAML response.

In case of an error, another event, denoted by “AuthErrorEvent”, will be sent with the following fields (all strings):

“DeveventDetailedErrorMessage” If an error occurred this will hold the error description.
“RESOURCE_URL” the URL that was to trigger an authentication process, but failed.

How To Add Custom Single Sign-On Workflows to Your App

In order for an app to receive the information above, the app will need to listen for notifications on the event and set a callback routine that will handle the data received in the event.  The code snippets below will register the app to receive a notification when authentication is complete and sets a callback routine that will extract all the keys above from the event data.

To receive an Appdome-DEV Event on iOS:

[[NSNotificationCenter defaultCenter] addObserverForName: @"AuthInfoEvent" object:nil queue:[NSOperationQueue mainQueue] usingBlock:^(NSNotification *note) {
    NSLog(@"Received Appdome DEV-Events™ AuthInfoEvent event with value: %@", [note userInfo]);
    
    NSString *authenticated = [note userInfo][@"Authenticated"];
    NSString *userName = [note userInfo][@"UserName"];
    NSString *accessToken = [note userInfo][@"AccessToken"];
    NSString *decodedAccessToken = [note userInfo][@"DecodedAccessToken"];
    NSString *idToken = [note userInfo][@"IdToken"];
    NSString *decodedIdToken = [note userInfo][@"DecodedIdToken"];
    NSString *samlRequest = [note userInfo][@"SamlRequest"];
    NSString *decodedSamlRequest = [note userInfo][@"DecodedSamlRequest"];
    NSString *samlResponse = [note userInfo][@"SamlResponse"];
    NSString *decodedSamlResponse = [note userInfo][@"DecodedSamlResponse"];
}];
[[NSNotificationCenter defaultCenter] addObserverForName: @"AuthErrorEvent" object:nil queue:[NSOperationQueue mainQueue] usingBlock:^(NSNotification *note) {
    NSLog(@"Received Appdome DEV-Events™ AuthErrorEvent event with value: %@", [note userInfo]);
    
    NSString *resourceUrl = [note userInfo][@"RESOURCE_URL"];
    NSString *error = [note userInfo][@"DeveventDetailedErrorMessage"];
}];

To receive an event on Android, simply create a BroadcastReciever and register it for events you need to receive:

BroadcastReceiver eventsReceiver = new BroadcastReceiver() {
    private static final String TAG = "AuthEventRcvr";

    @Override
    public void onReceive(Context context, Intent intent) {
        Bundle extras = intent.getExtras();
        String event = intent.getAction();

        if (event.compareTo("AuthErrorEvent") == 0) {
            Log.i(TAG, "found AuthErrorEvent: " + extras.toString());
            String resourceUrl = extras.getString("RESOURCE_URL");
            String error = extras.getString("DeveventDetailedErrorMessage");
        }
        if (event.compareTo("AuthInfoEvent") == 0) {
            Log.i(TAG, "found AuthInfoEvent: " + extras.toString());
            String authenticated = extras.getString("Authenticated");
            String userName = extras.getString("UserName");
            String accessToken = extras.getString("AccessToken");
            String decodedAccessToken = extras.getString("DecodedAccessToken");
            String idToken = extras.getString("IdToken");
            String decodedIdToken = extras.getString("DecodedIdToken");
            String samlRequest = extras.getString("SamlRequest");
            String decodedSamlRequest = extras.getString("DecodedSamlRequest");
            String samlResponse = extras.getString("SamlResponse");
            String decodedSamlResponse = extras.getString("DecodedSamlResponse");
        }
    }
};

private void registerReceiver(Context context) {
    IntentFilter intentFilter = new IntentFilter();
    intentFilter.addAction("AuthInfoEvent");
    intentFilter.addAction("AuthErrorEvent");

    context.registerReceiver(eventsReceiver, intentFilter);
    or
    LocalBroadcastManager.getInstance(context).registerReceiver(eventsReceiver, intentFilter);
}

How To Trigger Single Sign-On In Your App using Appdome-DEV Events

To trigger an Appdome to start an SSO flow on iOS, you can send an Appdome-DEV Event like so:

NSString *resourceUrl = @"https://my_resource/path";
NSLog(@"sending Appdome DEV-Events™ StartSSOFlow with url [%@]", resourceUrl);
NSMutableDictionary *eventInfo = [[NSMutableDictionary alloc] init];
eventInfo[@"RESOURCE_URL"] = resourceUrl;
[[NSNotificationCenter defaultCenter] postNotificationName: @"StartSSOFlow" object:nil userInfo:eventInfo];

To trigger an Appdome to start an SSO flow on Android, you can send an Appdome-DEV Event like so:

String resourceUrl = "https://my_resource/path";
Log.i(TAG, "sending Appdome DEV-Events™ StartSSOFlow with url " + resourceUrl);
Bundle data = new Bundle();
data.putString("RESOURCE_URL", resourceUrl);
Intent intent = new Intent("StartSSOFlow");
intent.putExtras(data);

sendBroadcast(intent);
or
LocalBroadcastManager.getInstance(this).sendBroadcast(intent);

How Do I Learn More?

If you have any questions regarding how to build custom SSO workflows inside mobile apps, please contact Appdome support via email at support@appdome.com or via the chat window on the Appdome platform.

Thank You and Try Appdome!

Thanks for visiting Appdome! Our mission is to make mobile integration easy and offer mobile DevOps an accelerated mobile app lifecycle workflow. We hope we’re living up to the mission with your project. If you don’t already have an account, you can sign up for free.  

Kai Kenan

Have a question?

Ask an expert

PascalMaking your security project a success!