Okta on Mobile SDK Vs Direct API
Intro (Written by Luke Simpson from appkitchen.dev)
Okta’s identity platform is an industry standard to authenticate users on mobile devices, but there are several important considerations when deciding which integration option is right for you. Firstly, Okta provides native iOS and Android SDKs to help simplify the steps needed to securely allow communication with a server based on recommended OAuth 2.0 flows. Alternatively, Okta’s REST APIs provide a more transparent and customised integration path.
Below are details of our experiences with both integration options and recommendations to avoid common issues. Many of the descriptions use Android-specific references but similar functionality is found across iOS and Android.
SDK Integration
Okta’s OpenID Connect (OIDC) SDK is the quickest way to set up authentication on your mobile app. Once the config and client are created a call to signIn triggers several network requests to get all necessary endpoints, launch a browser to obtain an authorization code, and eventually returns an access token, ID token and refresh token. We’re logged in and ready to communicate with our servers after just one call!
But if you’re building a banking, finance or other type of app that requires a custom UI for users to enter credentials rather than bouncing out of the app to a browser, Okta also provides its Java Authentication (AuthN) SDK to facilitate login using a session token.
SDK Gotchas
Min Android OS version
One important thing to note when using the AuthN SDK on Android is that while it states support for devices running Android 7 the SDK uses several Java 8 features that aren’t bundled with Android 7 and require the use of desugaring APIs. You should consider a direct API integration if you need to support down to Android 7 or below.
Token validation and storage
One very confusing aspect of using the OIDC SDK is that you might have a user successfully authenticate in Okta only to have the SDK subsequently generate an error on the client, so everything appears fine in the Okta console but the user can’t get past login!
One example of this is the way the SDK validates the ID token when it is returned from Okta: it uses device time and throws an error if there is a difference of 10 minutes or more between that and the time the token was created. This is problematic for users that set their device time ahead or behind for various reasons – we were surprised to find out how many users do this!
Okta has since introduced a way to add a synchronised time source such as TrueTime to help overcome this problem. It’s an improvement but please note that it does not completely eliminate the issue.
Also, there is a known issue with the OIDC SDK’s storage mechanism, especially on Samsung devices. Again, Okta has provided a way for us to implement our own encrypted storage solution but with each of these additional steps the appeal of using the SDK is reduced.
Error handling
The errors mentioned above can be confusing to debug due to the way they are presented by the SDK. Each of these errors might use the same error code and type – usually “0” – with a different description attached. This means we have to rely on string matching to handle different types of errors coming from the SDK.
Breaking changes
One update to the iOS OIDC SDK did contain breaking changes that were not clearly communicated in the release notes. It’s much less likely for these types of breaking changes to occur when using a direct API integration as we have better visibility into how the various calls are orchestrated and handled.
Nearing end-of-life
Okta recently released an early glimpse of new libraries designed to replace its “legacy” SDKs. It doesn’t appear that these are yet production ready, but one of the GitHub READMEs states a goal of “building a platform to support the development of many SDKs, allowing application developers to choose which SDKs they need.”
Direct API Integration
Using Okta’s REST API we take on responsibility for chaining the required calls, storing tokens and any client-side validations. It also becomes easier to create new flows that address common authentication issues.
Take the scenario where a user doesn’t know they are already registered. By using the authentication endpoint and having them simply enter their user ID – usually email – we can detect whether their account exists and direct them to enter/reset their password or, if they don’t yet exist in Okta, follow the registration flow.
We can also leverage any two-factor authentication (2FA) associated with users’ accounts and trigger an email or preferably SMS containing a one-time password (OTP). Okta also supports the use of two authenticator apps to generate an OTP: Google’s Authenticator and its own Okta Verify app.
The Verdict
The Android and iOS platforms provide developers with great tools for chaining together API calls and mapping the results according to business rules and security/validation requirements. As such it was not much more effort to re-create the series of calls made by the SDKs. With that moderate amount of work we open up the ability to completely control all the areas that caused us issues in the past: token storage, error handling and validation.
We also decouple the relationship between our supported iOS and Android platforms and those supported by Okta: any device with an internet connection is supported!
While the direct API integration clearly worked better for us, you may find that an iterative approach is right for you: start with the SDK to get up and running and move to direct API when you can, or check out the new SDKs when they’re available.
TL;DR
When deciding to use either Okta’s SDK or direct API integration for mobile authentication, there are several important considerations. The SDK provides a quick and easy way to set up authentication, but there are some gotchas to be aware of, such as the requirement for Java 8 features and confusing error handling. Additionally, Okta’s OIDC SDK has some known issues with token validation and storage, which can be problematic for users.
On the other hand, direct API integration offers greater control over token storage, error handling, and validation, as well as the ability to create custom flows and better leverage two-factor authentication. While the direct API integration requires more effort upfront, it offers greater flexibility and can decouple the relationship between the supported platforms of the app and Okta.
Image Credit Freepix
If you want more content from Identity XP please follow us at
LinkedIn : LinkedIn
Twitter : IdentityXP (@IdentityXP) / Twitter
If you want to her more from Luke please find him at
web: appkitchen.dev
LinkedIn Company Page : https://www.linkedin.com/company/app-kitchen-dev
LinkedIn: https://www.linkedin.com/in/lukesimpson/
Twitter: @Luke_Simmo & @AppKitchenDev