See mobile Menu

Code SSO for Your iOS App Using NAPPS

Use the OneLogin NAPPS (native apps) toolkit to help you enable single sign-on (SSO) for your iOS 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. Download 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 iOS development, you’ll be working with the contents of the iOS directory only.

/napps-master  
      /Android  
      /iOS  
            /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 via token agent.
                  /Test Token Agent

A slimmed-down version of the OneLogin Mobile token agent. The Test Token Agent has the same interfaces as 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 OneLoginSDK.framework file that you’ll add to your app project.
      /PhoneGap  
      README.md  
      /Server  

2. Add the NAPPS SDK to Your App Project

In Xcode:

These instructions were written based on Xcode 6.4. The toolkit may not work as designed using an earlier release.

  1. With your app target selected, go to the Build Phases tab.

  2. Expand the Link Binary With Libraries area to view the frameworks in your app.

  3. Click the Add items icon (+).

  4. Click Add Other… and select the OneLoginSDK.framework file in the napps-master/iOS/SDK/ directory in the NAPPS toolkit you downloaded.

    Once you’ve added the SDK, your Build Phases tab will look something like this:

3. Set the Custom URL Scheme for Your App

In Xcode:

These instructions were written based on Xcode 6.4. The toolkit may not work as designed using an earlier release.

  1. With your app target selected, go to the Info tab.

  2. Expand the URL Types section.

  3. Click the Add items icon (+).

  4. Enter a URL Schemes value. 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, here is the URL Schemes value for the Signal sample app highlighted near the bottom of the screen:

    While you are on the Info tab, make a note of the Bundle identifier value highlighted near the top of the screen. You’ll use it with the Test Token Agent in Step 5. Test Your App with the Test Token Agent.

  5. The URL Schemes value you enter on the Info tab is autopopulated to your app’s Info.plist file, and vice versa. Typically, you can find Info.plist in this directory:/Supporting Files/Info.plist. To open it, right-click Info.plist and select Open As > Source Code. Here is a snippet of code from the file that reflects the URL Schemes value entered in the screenshot above:

    <key>CFBundleURLTypes</key>
    <array>
       <dict>
          <key>CFBundleTypeRole</key>
          <string>Editor</string>
          <key>CFBundleURLName</key>
          <string></string>
          <key>CFBundleURLSchemes</key>
          <array>
             <string>SIGNAL</string>
          </array>
       </dict>
    </array>

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://tokenRequest?a=url_scheme&s=bundle_identifier

  • Token Agent response URI scheme:

    url_scheme://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 19-33 in AppDelegate.m in napps-master/iOS/Demos/Signal/Signal.

Required?

No.

Purpose

Easily toggle test mode on and off in your app code.

Use the setTestMode property to tell the NAPPS SDK to look for and interact with either the Test Token Agent or OneLogin Mobile.

  • Set to YES to tell the NAPPS SDK to look for and interact with the Test Token Agent.

  • Set to NO to tell the NAPPS SDK to look for and interact with OneLogin Mobile.

Warning: If you use this code, ensure that this property is set to setTestMode:NO 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. Whitelist OneLogin Mobile in Your App

Add the following entry to your app’s Info.plist file:

<key>LSApplicationQueriesSchemes</key>
<array>
    <string>olta</string>
</array>

Required?

Yes.

Purpose

Adding this entry to your app’s Info.plist file addresses changes to the canOpenURL method in iOS 9 as described in Privacy and Your App.

Per the changes, you must code your app to declare, or whitelist, the URL schemes of any apps that your app needs to be able to find on the device. This check for the presence of an app is performed using the canOpenURL method.

In the case of NAPPS, your app must be able to check for the presence of OneLogin Mobile on the user’s device. To do this, you must whitelist OneLogin Mobile using its URL scheme olta, as shown in the code sample above.

If you are testing your app using the Test Token Agent, you must also include an entry for the Test Token Agent, which has the URL scheme value of oltta. For example:

<key>LSApplicationQueriesSchemes</key>
<array>
    <string>oltta</string>
    <string>olta</string>
</array>

Important: Be sure to remove the oltta value before shipping your app’s production version.

If a URL scheme is declared in Info.plist, the canOpenURL(urlscheme) method will return one of the following responses:

  • YES, if an app with that URL scheme is installed on the device.

  • NO, if no app with the URL scheme is installed on the device. The syslog will contain:

    canOpenURL: failed for URL: “urlscheme://: - error: “(null)”

If a URL scheme is not declared in Info.plist, the canOpenURL(urlscheme) method will return NO, whether or not an app with the URL scheme is installed on the device. The syslog will contain:

canOpenURL: failed for URL: “urlscheme://: - error: “This app is not allowed to query for scheme urlscheme”

c. Check for a Token Agent

See lines 47-65 of NAPPSVerifyViewController.m in napps-master/iOS/Demos/Signal/Signal/Controllers/Verification Controller.

Required?

No, but you may want to use it if you want to separate the call to check for a token agent from the call to request a NAPPS token.

Purpose

Check for a token agent in a call that is separate from the call to request 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.

Use the -verifyTokenAgentIsInstalledWithBlock: method to check if a token agent is installed on the current device.

  • If setTestMode is set to YES, it looks for the Test Token Agent and reports back on whether it is installed.

  • If setTestMode is set to NO or is not set, it looks for OneLogin Mobile and reports back on whether it is installed.

If you want to check for a token agent and request a NAPPS token in a single method, use c. Check for a Token Agent and Request a Token instead.

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.

d. Check for a Token Agent and Request a NAPPS Token

See lines 35-53 of TokenManager.m in napps-master/iOS/Demos/Signal/Signal/Managers.

Required?

Yes.

Note: If you are using 2. Check for a Token Agent to check for a token agent, you must still use this call to request the NAPPS token. The token agent check that this call does will just serve as a second check.

Purpose

Use a single method to check for a token agent and request a NAPPS token from it.

Use the -requestTokenByCheckingIfTokenAgentIsInstalled: method to do the same thing as the -verifyTokenAgentIsInstalledWithBlock: method (see 2. Check for a Token Agent), but without requiring the call to report back on whether a token agent is installed. If this call finds a token agent, it will proceed to request a NAPPS token from it.

For example, you can use this code to implement a login flow in which you check for a token agent and if one is present, you request a NAPPS token—all in one step. If token retrieval fails, you then display your normal login flow.

If there was a problem with the request, the NSError value passed to the block provides details. Errors could include things like the user does not have access to the app or perhaps there was no active session on the app. It could also convey a problem with the request itself. However, this error will not be about whether a NAPPS token was actually retrieved.

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.

e. Receive and Decode the NAPPS Token from the Token Agent

See lines 43-60 in AppDelegate.m in napps-master/iOS/Demos/Signal/Signal.

Required?

Yes.

Purpose

Receive and extract the NAPPS token from the incoming callback URL 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.

Implement the -application:openURL:sourceApplication:annotation: method in AppDelegate.m. Inside the method’s implementation, pass the URL object to the NAPPS SDK as in line 50.

The -handleURL: success:failure: method uses the NAPPS SDK to decode the NSURL object passed to it:

  • If a NAPPS token is retrieved successfully, the success: block executes with the NSString* object representing the token passed to it.

  • If the token agent reported an error back to the requesting app, the failure: block executes with the NSError* object passed to it

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

Where to Put It

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

f. Call Back Your App Server with the NAPPS Token

See lines 32-48 in TweetManager.m in napps-master/iOS/Demos/Signal/Signal/Managers.

Required?

No, but we strongly recommend using it.

Purpose

The NAPPS token that your app receives from the token agent is signed, includes the user’s email address, and identifies the user as successfully validated. When your app makes a login request back to your app server, use this code to include the NAPPS token in the request.

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 it where your app makes login requests back to your app server.

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 using the Signal app delivered in the SDK as a stand-in for your own app.

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

  2. Launch the Test Token Agent.

  3. Select Add App.

  4. In this test case, you’ll add the Signal app. In the App Name field, enter Signal. In the App Scope (Bundle ID) field, enter com.onelogin.SignalInternal.

    Note that the App Scope (Bundle ID) value used to test your own app would be the value of the Bundle Identifier field set on the Info tab you worked with in Step 2. Add the SDK to Your App Project.

  5. Select SAVE.

  6. Slide the switch for the app definition into the “on,” or green, position. Select Settings to select the error condition that you want the Test Token Agent to simulate.

  7. The Test Token Agent can simulate the following error conditions.

    Note: This screen will be updated with more error codes in the future. For a full list of error codes to be supported, see Token Agent Errors.

  8. Let’s start a test by selecting Network not available (1000). Then select Enabled Apps.

  9. Launch the Signal app.

  10. The Signal app confirms that a token agent (the Test Token Agent, in this case) is installed on the device.

  11. Select 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. The app displays tweets to the authenticated user.

    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.

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 (coming to Test Token Agent) 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 (coming to Test Token Agent) 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 (coming to Test Token Agent) 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 (coming to Test Token Agent) 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 (coming to Test Token Agent) OLNAPPSErrorCouldNotFindBearerToken

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

1300 (coming to Test Token Agent) 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)

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:

  • App type: iOS

  • Backend URL that your app talks to

  • Name of your app to be used in the OneLogin App Catalog

  • Bundle identifier and URL Schemes values set in 3. Set the Custom URL Scheme for 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.