How to Make Custom Mobile SSO Workflows Work in Mobile Apps

Appdome-DEV Threat 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 make custom mobile SSO Workflows work in mobile 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!

How to Make Custom Mobile SSO Workflows Work in Mobile 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-Threat 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-Threat Events you need:

• Appdome account – IDEAL or Higher
• Mobile App (.ipa for iOS, or .apk or .aab for Android)
• Appdome-DEV access
• Threat Events license
• Signing Credentials (e.g., signing certificates and provisioning profile)

The Easy Steps to Make Custom Mobile SSO Workflows Work in Mobile 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-Threat 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):

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

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-Threat Event on iOS:

[[NSNotificationCenter defaultCenter] addObserverForName: @"AuthInfoEvent" object:nil queue:[NSOperationQueue mainQueue] usingBlock:^(NSNotification *note) {
    NSLog(@"Received Appdome Threat-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 Threat-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-Threat Events

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

NSString *resourceUrl = @"https://my_resource/path";
NSLog(@"sending Appdome Threat-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-Threat Event like so:

String resourceUrl = "https://my_resource/path";
Log.i(TAG, "sending Appdome Threat-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, please send them our way at support.appdome.com or via the chat window on the Appdome platform.

Thank you!

Thanks for visiting Appdome! Our mission is to secure every app on the planet by making mobile app security easy. 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.