Authenticating with the Mobile SDK for iOS

The Mobile SDK for iOS makes it easy for your application to request an access token that can be used to make API requests to LinkedIn on behalf of the mobile user.  Follow the steps below to integrate LinkedIn into your iOS application:

Read the Getting Started guide

Before you begin, make sure that you have read the Getting Started with the Mobile SDK for iOS guide.  It contains important information to know before you will be able to successfully authenticate a LinkedIn user within your mobile application.

Step 1 - Initialize a connection to LinkedIn

The LISDKSessionManager class is the heart of the Mobile SDK for iOS.  It provides all of the necessary functionality to create and manage the session connection to LinkedIn to perform additional SDK operations with.

There are two ways to initialize a LinkedIn session:

  • Without an existing access token
  • With a previously acquired access token

Initializing by requesting a new access token

If you do not have a previously established access token for the current user to initialize a session with, a new one can be requested and returned to your application through a SDK call.

Since this call temporarily takes the user out of your application and into the official LinkedIn app to complete the authorization, there are various possible user experiences that could occur.  See Understanding the mobile authentication user experience for a breakdown of what the user might encounter during this part of the authentication process.

Access tokens returned from this call are stored as part of the application’s key chain. Subsequent calls to this method will check for the existence of a previously requested and stored access token, and use it if found.  If no access token is found, or the access token has expired, the user will be directed to the official LinkedIn application to acquire a new one.

Objective-C
createSessionWithAuth:scope:state:showGoToAppStoreDialog: successBlock:errorBlock

This variant takes four arguments:

  1. scope - An array of LinkedIn member permission objects that your application is requesting.  Possible values are defined in LISDKPermission.h.
  2. state - A value that can be used to maintain state between the request and the callback.
  3. showGoToAppStoreDialog - A boolean that determines whether the user will be directly taken to the App Store or whether they will be presented with a dialog box and given the choice to go to the App Store, if the official LinkedIn application cannot be found installed on the device.
  4. successBlock - A callback method to execute upon successful completion of the authorization process.  The state value provided in the original call is passed back as a parameter to this callback.
  5. errorBlock - A callback method to execute if there are problems during the authorization process.

Below you will find an example of what the connection initialization portion of a typical authentication process might look like:

Objective-C
[LISDKSessionManager 
createSessionWithAuth:[NSArray arrayWithObjects:LISDK_BASIC_PROFILE_PERMISSION, nil]
    state:nil
    showGoToAppStoreDialog:YES
    successBlock:^(NSString *returnState) {
        NSLog(@"%s","success called!");
        LISDKSession *session = [[LISDKSessionManager sharedInstance] session];
    }
    errorBlock:^(LISDKAuthError *error) {
        NSLog(@"%s","error called!");
    }
];

Initializing with an existing access token

f you have an access token for the current user that you have serialized from a previous interaction with your application, you can use it to create a new LinkedInSession rather than requesting a brand new one.  Serialize your access token (using AccessToken:serializedString) and provide it as an argument to the following method:

Objective-C
createSessionWithAccessToken:accessToken;

This variant takes the following argument:

  • accessToken - A valid LinkedIn access token to use when making calls to LinkedIn through the SDK.

Mobile vs. server-side access tokens

It is important to note that access tokens that are acquired via the Mobile SDK are only usable with the Mobile SDK, and cannot be used to make server-side REST API calls.  Similarly, access tokens that you already have stored from your users that authenticated using a server-side REST API call will not work with the Mobile SDK.

Presently, there is no mechanism available to exchange them.  If you require tokens that can be used in both the mobile and server-side environment, you will need to implement a traditional OAuth 2.0 solution within your iOS environment to acquire tokens that can be leveraged in both situations.

Step 2 - Handle responses from the LinkedIn mobile app

Add the following method to your AppDelegate.m source code to enable the LinkedIn App to give control back your application in situations in situations where you are brought outside of the context of your application (e.g. deeplinking)

Objective-C
- (BOOL)application:(UIApplication *)application openURL:(NSURL *)url sourceApplication:(NSString *)sourceApplication annotation:(id)annotation {
    if ([LISDKCallbackHandler shouldHandleUrl:url]) {
        return [LISDKCallbackHandler application:application openURL:url sourceApplication:sourceApplication annotation:annotation];
    }
    return YES;
}

Once your application is sending messages to and receiving messages from the LinkedIn mobile app successfully, your authentication workflow is complete.

Please refer to the sample application included in the Mobile SDK for iOS download for a complete runnable example that demonstrates a successful end-to-end LinkedIn mobile authentication process.

Localization

To support our non-English speaking members, we have localized the mobile authorization screen.  Members who use SSO with LinkedIn in the 3rd party application see the authorization screen on the LinkedIn mobile app.  This screen is now localized to match the language setting on the member’s mobile device.

  • Localized authorization screen

Understanding the mobile authentication user experience

When an authentication request that requires a new access token to be requested occurs, the SDK needs to communicate with the official LinkedIn application to generate that token for the current user.  During this process, there are several possible scenarios that could occur which result in different user experiences, based on:

  1. Is the LinkedIn application installed on the device?
  2. Is the user a LinkedIn member?
  3. Is the user signed into the LinkedIn application on their device?
  4. Has the user granted your application permission to access their profile?

LinkedIn app is not installed on the mobile device

The SDK will direct the user to the App Store to install the official LinkedIn application.  It is up to the user to install it.  Once installed, the user will have to manually return to your application and restart the authorization process to continue. The showGoToAppStoreDialog argument can be used to control whether the user will be shown a dialog and given the option to go to the store.

LinkedIn app is installed, user is not a LinkedIn member

The LinkedIn application will launch and the user will be prompted to create a new LinkedIn account.  The user will have to complete the account creation process (including email validation), manually return to your application and restart the authorization workflow to continue.

LinkedIn app is installed, user is not signed in to LinkedIn

The LinkedIn application will launch and users will be prompted to login with their LinkedIn credentials.  Once validated, users will be presented with an authorization screen showing the name and the logo of your application and listing the permissions that your app is requesting.  If permission is granted, the user is returned back to your iOS application with the original state that was passed during the start of the authorization process.

LinkedIn app is installed, user is signed in to LinkedIn but has not authorized your app

The LinkedIn application will launch and an authorization screen showing the name and the logo of your application and listing the permissions that your app is requesting. If permission is granted, the user is returned back to your iOS application with the original state that was passed during the start of the authorization process.

LinkedIn app is installed, user is signed in and previously authorized your app

The LinkedIn application will immediately return the user back to your iOS application.