See mobile Menu

Code SSO for Your Android App Using NAPPS

Use the OneLogin NAPPS (native apps) toolkit to help you enable single sign-on (SSO) for your Android app when used in conjunction with a token agent, such as OneLogin Mobile.

NAPPS is an OpenID Connect 1.0 standard for enabling SSO for native apps installed on devices. The NAPPS standard is being profiled by the Native Applications Working Group.

Note: Our NAPPS toolkits are intended to work with any identity provider. We will test it with more identity providers over time.

Best Practices for Working with the Test Token Agent

As you build out your app, we recommend that you test as you go, using the Test Token Agent as described in Step 5. Test Your App with the Test Token Agent.

Use the Test Token Agent delivered in the toolkit to simulate the integration between your app and OneLogin Mobile without having to communicate with the OneLogin NAPPS service. The Test Token Agent has the same interfaces as OneLogin Mobile.

By developing your app in close conjunction with the Test Token Agent, you can ensure that all interfaces are properly configured. This means that when you go live and swap out the Test Token Agent with OneLogin Mobile, all connections you developed using the Test Token Agent are still valid with OneLogin Mobile and the OneLogin NAPPS service in place.

1. Get the OneLogin NAPPS Toolkit

  Download the toolkit

If you’d like to learn more about the OneLogin NAPPS program, contact napps-info@onelogin.com.

Expand the ZIP file to reveal the following structure. For the purposes of Android development, you’ll be working with the contents of the Android directory only.

/napps-master  
      /Android  
            /Demos Contains sample projects that demonstrate how to integrate NAPPS into your application.
                  /Signal A sample client-side application that displays tweets upon successful user authentication.
                  /Test Token Agent

A slimmed-down version of the OneLogin Mobile token agent. The Test Token Agent has the same interfaces OneLogin Mobile, but doesn’t connect to the OneLogin NAPPS service and operates as if it is successfully present.

Use the Test Token Agent to simulate the integration between your app and OneLogin Mobile.

            /SDK Contains the NAPPS SDK .jar file that you’ll add to your app project.
      /iOS  
      /PhoneGap  
      README.md  

2. Add the NAPPS SDK to Your App Project

These instructions were written based on Android Studio 1.3.2. The toolkit may not work as designed using an earlier release.

  1. Copy napps_sdk.jar from napps-master/Android/SDK and add it to the app/libs directory for your app.

  2. With your app project open in Android Studio, go to File > Project Structure.

  3. In the pane on the left, under Modules, select app.

  4. In the pane on the right, go to the Dependencies tab.

  5. Click the + (Add) icon in the lower left and select 2 File dependency.

  6. In the Select Path dialog, in the libs folder, select napps_sdk.jar. Click OK.

  7. The napps.sdk.jar file now displays as a dependency in the Project Structure dialog. Click OK.

3. Define Custom URL Scheme and Host Values for Your App

Define a custom URL scheme. This can be the name of your app, or any value. This is the name that the NAPPS SDK will use to call your app. For example, once the token agent has successfully retrieved a NAPPS token at your app’s request, it will deliver the NAPPS token, or an error, to your app via the endpoint defined by its custom URL scheme.

Define custom URL scheme and host values for your app in its Android.Manifest.xml file. See example host and custom URL scheme values shown in bold below.

Code sample from napps-master/Android/Demos/Signal/app/src/main/AndroidManifest.xml:

<activity
    android:name="onelogin.com.signal.Signal"
    android:label="Tweets"
    android:screenOrientation="portrait">
    <intent-filter>
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />
        <data
            android:host="onelogin.com.signal.Signal"
            android:scheme="SIGNAL" />
    </intent-filter>
</activity>

4. Code Your App to Request and Receive a NAPPS Token

You’ll need to code your app to request a NAPPS token, also known as a secondary token, from the token agent, as well as receive the NAPPS token from the token agent, as highlighted in blue in the URL scheme invocation flow below:

Here are a few more details of the URI scheme invocation:

  • Token Agent request URI scheme:

    olta://secondarytokenrequestforapp?returnRoute=url_scheme_of_app

  • Token Agent response URI scheme:

    url_scheme_of_app://message_content?t=string_which_is_the_token&e=error_code_as_int

The OneLogin NAPPS Toolkit includes the Signal demo app to help illustrate how to implement NAPPS. It includes code snippets that you can reuse in your app to accomplish these four primary tasks that are a part of requesting and receiving a NAPPS token:

Let’s take a look at the code snippets, what they do, and where to use them in your code.

a. Toggle Test Mode On and Off

See lines 33-48 in EntryActivity.java in napps-master/android/Demos/Signal/app/src/main/java/onelogin/com/signal/entry.

Required?

No.

Purpose

Enables you to easily toggle test mode on and off in your app code.

To have your app run in test mode and look for and interact with the Test Token Agent, leave these lines (33-48) as-is. The setTokenAgentPackageName and setTokenAgentURLScheme values are set to point to the Test Token Agent (mockta). Then simply add setTestMode(); at line 29 as shown below:

To toggle test mode off and run in production mode, simply comment out the setTestMode(); line you added as shown below:

Warning: Be sure to turn off test mode in the final, shipped version of your app.

Where to Put It

Place this up front in your app flow. It should be one of the first, if not the first, properties you set if your app is set to run in debug mode.

b. Check for a Token Agent

See lines 50-90 in EntryActivity.java in napps-master/android/Demos/Signal/app/src/main/java/onelogin/com/signal/entry.

Required?

Yes.

Purpose

Have your app check for the presence of a token agent. If your app is set to run in test mode, it will check for the Test Token Agent. If your app is set to run in production mode, it will check for OneLogin Mobile.

If a token agent is present, the code enables the app to subsequently make the actual request for a NAPPS token.

For example, use this code to develop a login flow in which you give your user the choice of logging in with a token agent or via your normal login flow even if a token agent is installed. Use this code to check for a token agent and if one is present, display both login options. If not, display your normal login flow.

Alternatively, you can use this code to provide one login flow or the other. For example, if a token agent is installed, provide the token agent login flow. If not, display your normal login flow.

Where to Put It

Use it when you display your login screen and you need to determine whether to display the token agent login flow.

c. Request a NAPPS Token

See lines 92-103 in EntryActivity.java in napps-master/android/Demos/Signal/app/src/main/java/onelogin/com/signal/entry.

Required?

Yes.

Purpose

Have your app request a NAPPS token from the token agent, as well as provide the URI to which the token agent should return the token.

If token retrieval fails, display your normal login flow.

Where to Put It

Use it when you display your login screen and you need to determine whether to display the token agent login flow. Use it when you need to request a NAPPS token.

d. Receive and Decode NAPPS Token from Token Agent

See lines 47-86 in Signal.java in napps-master/android/Demos/Signal/app/src/main/java/onelogin/com/signal.

Required?

Yes.

Purpose

Receive and extract the NAPPS token from the incoming callback URI request from the token agent.

Note that if your app already responds to various schema requests, such requests to open a web page or launch an app, code your app to first determine if it is a NAPPS request or one of the schemas your app already handles.

If it is a NAPPS request, use this code to extract the token from it.

Your app code takes over at this point, receiving either the NAPPS token or the error object as input to your app.

It is up to your app server to validate the token and create a session for the user if the token is valid, or to do whatever is necessary for your app. For more information, see NAPPS App Server Reference.

Where to Put It

Use this code wherever the URL schema for your app is invoked.

5. Test Your App with the Test Token Agent

The Test Token Agent works just like the OneLogin Mobile token agent, except that it doesn’t call the OneLogin NAPPS service and the token it issues is just a random string.

You can configure the Test Token Agent to issue different error codes to help you code your app to respond appropriately. If you’ve configured the Test Token Agent to send an error, it will send the error and no token. The NAPPS SDK you added to your app in Step 2. Add the SDK to Your App Project will decode the error and display it in your app.

The following flow describes how to use the Test Token Agent to test NAPPS SSO with your app. In this flow, we’ll use the Signal app delivered in the SDK as a stand-in for your app.

  1. Load the Test Token Agent app and Signal app onto your device or emulator.

  2. Launch the Test Token Agent.

  3. Touch the + icon to add an app.

  4. In this test case, you’ll add the Signal app. In the App Name field, enter a name for your app. In the App URI field, enter the android:host value your entered in your Android.Manifest.xml file in Step 3. Define a Custom URL Scheme for Your App.

    For our Signal sample app, the android:host value is onelogin.com.signal.Signal, as shown in the Test Token Agent app UI below:

  5. Touch SAVE.

  6. Slide the switch for the app definition into the “on,” or green, position.

  7. Touch the settings icon to select the error condition that you want the Test Token Agent to simulate.

  8. The Test Token Agent can simulate the following errors. For example, let’s start a test by selecting the IDP did not respond (1100) error.

  9. Launch the Signal app.

  10. Signal will detect the presence of the Test Token Agent:

  11. Touch Continue. The selected error displays. If you select any error in the Test Token Agent, the Signal app will display that error.

  12. Now, select no errors in the Test Token Agent and launch the Signal app.

       

    In a production context, this interaction would mean that your app has successfully requested a NAPPS token, received a NAPPS token from the token agent, and was able to authenticate the user.

Troubleshooting

  • I’m getting a Use a different app message.

    If you are seeing this message, as shown below, the custom URL scheme android:scheme value that you coded in your Android.Manifest.xml is conflicting with the custom URL scheme set for your browser, for example. Thus, the app being opened is unclear about how it should be opened: via the app listed or via the browser.

       

  • I’m getting Error: 1201, but I selected a different error in the Test Token Agent

    This may mean that you’ve entered an incorrect App URI value in the Test Token Agent and/or your Android.Manifest.xml file.

Token Agent Errors

Code Message Description
1000 OLNAPPSErrorNetworkNotAvailable

Network is not available.

1100 OLNAPPSErrorIDPDidNotRespond

Request timed out or the server is down.

Suggested messaging to the end user: The app could not connect to the server. Please try again.

1201 OLNAPPSErrorRequestingAppDoesNotHavePermission

Requesting app is not on the OneLogin AppInfo list.

For example, the user has an app on her device, but her system administrator has not put the app on the OneLogin AppInfo list, so her request was denied.

Suggested messaging to end user: You have been denied access to the app. If you believe this is an error, please contact your system administrator.

1202 OLNAPPSErrorSecondaryTokenRequestRejected

The server responded with an error after requesting an updated OneLogin AppInfo List or a NAPPS token.

The app has been confirmed to be on the OneLogin AppInfo list, but between the time of that confirmation and the time when the app requested the NAPPS token, the user has been denied access.

Suggested messaging to end user: You have been denied access to the app. If you believe this is an error, please contact your system administrator.

1203 OLNAPPSErrorAppInfoListRefreshFailed

Couldn’t retrieve the OneLogin AppInfo list. The request to refresh the OneLogin AppInfo list failed.

This error is not exposed to the end user.

1204 OLNAPPSErrorBearerTokenExpired

Primary/bearer token has expired.

A user logged in initially with a username and password and presented a primary token. There is a timeframe in which this primary token exists. This error means that the primary token has expired and the token agent will refresh it, if possible.

This error is not exposed to the end user.

1205 OLNAPPSErrorBearerTokenRevoked

The bearer token has been revoked.

Suggested messaging to end user: You are not a valid user in the system. If you believe this is an error, please contact your system administrator.

1206 OLNAPPSErrorUserDisabled

User has been disabled.

Suggested messaging to end user: You are not a valid user in the system. If you believe this is an error, please contact your system administrator.

1207 OLNAPPSErrorCouldNotFindBearerToken

Bearer token could not be found. Force a re-login to the token agent.

1300 OLNAPPSErrorTokenAgentNotInstalled

Token agent is not installed on the device.

Suggested messaging to the end user: You must have a token agent installed to be able to access this app. Contact your system administrator for more information.

1500 OLNAPPSErrorNoSessionActive

The token agent does not have the information necessary to begin a session.

There is no primary token present. Display a login screen so that the user can authenticate himself in the system.

1600 OLNAPPSErrorDeviceCouldNotBeEnrolled

Device could not be enrolled with the server.

Suggested messaging to end user: Your device cannot be enrolled. If you believe this is an error, please contact your system administrator.

Primarily, you just need to understand the following three error codes and what your app needs to do in each case:

  • OneLogin doesn’t know your app (1201)

  • OneLogin doesn’t know your user (1206)

  • The OneLogin Token Agent doesn’t work (1300)

Generally speaking, there is not much more you can do for additional error codes other than let OneLogin know for debugging purposes.

6. Register Your App with OneLogin

Contact napps-support@onelogin.com to have us register your app. When contacting us to register your app, please include the following information about your app:

  • URL to an icon for your app that may be used for a future launcher app (optional)

Registering your app with OneLogin means that we’ll create a connector that meets two requirements of your NAPPS implementation:

  • Puts your app on the OneLogin AppInfo list. When authorizing a user to access your app, the token agent will verify that your app is on the OneLogin AppInfo list.

  • Provides you with a resource server key. Your resource server key is generated when OneLogin creates the connector for your app.

    • Use the resource server key and an OAuth 2.0 library to validate and decrypt the NAPPS token passed to your app.

    • Use the resource server key to authorize your app server to call the OneLogin NAPPS API endpoint to verify NAPPS tokens. In general, it validates that your app server is properly registered and that your app server and the NAPPS token are both still valid.

7. Set Up Your App Server to Verify NAPPS Tokens (optional)

If applicable, prepare your app server (also known as a third-party resource server) to verify the validity of NAPPS tokens that it receives from your NAPPS-enabled app.

For details, see App Server Reference.

8. Go live

As recommended at the start of this document, if you built out your app leveraging the toolkit and testing SSO along the way using the Test Token Agent delivered in the toolkit, the process of going live can be quite seamless, at least in terms of SSO enablement.

Once you are satisfied with your SSO testing results, go live with your SSO feature by just removing the Test Token Agent and replacing it with OneLogin Mobile.


Have a Question?

Have a how-to question? Seeing a weird error? Ask us about it on StackOverflow.

Found a bug? Submit a support ticket.

Have a product idea or request? Share it with us in our Ideas Portal.