Single Sign-On for Native iOS Applications with WSO2 Identity Server

Single sign-on (SSO) is an authentication process that allows a user to access multiple applications using the same set of credentials. With SSO, a user can provide credentials once and gain access to different applications without having to sign in to each application individually.

You can add SSO capability to your iOS based native client applications using WSO2 Identity Server as an identity provider.

This tutorial demonstrates how you can add SSO support to a sample iOS application using WSO2 Identity Server as the Identity Provider. 

The tutorial includes the following sections:

Before you start the tutorial, be sure to complete the following prerequisites:

• Set up a MacOS based computer to try out the tutorial.

• Download and install WSO2 Identity Server, which will act as the identity provider in the tutorial. You can download the product installer from here, and run it.

• Download or clone the WSO2 Identity Server samples repository.

• Download and install Xcode 9+ to work with the iOS client app sample.

Once you have the prerequisites, you can follow the step-by-step instructions in the following sections.

Since WSO2 Identity Server acts as the identity provider in this tutorial, first you need to configure WSO2 Identity Server as an identity provider.

Before you begin, you need to set up a valid SSL certificate in WSO2 Identity Server. This is important because by default iOS applications are restricted from communicating with a source that does not have a valid certificate. However, if you are running the server locally and you want to test the sample application via the iOS simulator, you can add a self-signed certificate to both WSO2 Identity Server and the simulator.

1. Follow the steps here to add a self-signed certificate to WSO2 Identity Server. 

2. Start WSO2 Identity Server and access the management console. You can sign in using admin as the username and password. For detailed instructions on accessing the management console of WSO2 Identity Server, see Accessing the Management Console.

3. On the Main tab of the management console, go to Identity -> Service Provider and click Add. 

4. Enter an appropriate name for the new service provider and click Register. 

5. Expand the Inbound Authentication Configuration section, and then expand the OAuth2/OpenID Connect Configuration.

6. Click Configure and set the following values in addition to the values that are set by default:

   1. Specify wso2issample://oauth as the Callback Url. This is the sample application’s URL.

   2. Select PKCE Mandatory. This is recommended because you need to adhere to the PKCE protocol as a best practice when developing native mobile applications.

   3. Select Allow authentication without the client secret. This allows the native mobile application to bypass the authentication phase. For information on how native applications should interact with an authorization endpoint, see OAuth 2.0 for native apps specification.

7. Click Add. You will see an information message that says Application registered successfully.

8. Click OK.

9. Make a note of the generated OAuth Client Key. You need this value when you set up the sample application.

Now you have set up WSO2 Identity Server. Next you need to set up the sample iOS application.

1. Use this tool to import a self-signed certificate to the iOS simulator.

2. Go to the downloaded WSO2 Identity Server samples repository. Let’s refer to the samples repository directory location as <SAMPLES_HOME> throughout this tutorial.

3. Open the <SAMPLES_HOME>/oidc-client-app-samples/ios-client-app-sample/WSO2-IS-SampleApp.xcworkspace file in Xcode. 

Following is the directory structure of the sample application project:

Open

Following are descriptions of the key components of the sample application project:

• AppDelegate.swift - The default delegation class to observe changes of the sample application state.

• Main.storyboard - The main storyboard of the sample application.

• Info.plist -  Contains all the essential details about the sample application.

• Config.plist - The configuration file that contains identity provider details along with the OAuth client ID.

• controllers directory - Contains controllers for the login view and profile view.

• model directory - Contains model data objects.

• mgt directory - Contains management classes.

• utils directory - Contains utility classes.

• resources directory - Contains the resource files used in the application.

• service directory - Contains the service class that handles the OAuth communication. We will take a look at the purpose of this directory in detail later in the tutorial.

Now that you are familiar with the key components of the sample project, let's set up the dependencies and third party libraries that are required.

• The sample client application uses CocoaPods as the dependency manager in the project and the dependencies are defined in the pods file. In this tutorial you do not need to install the dependencies because the dependencies are already included along with the sample application source code.

• The sample client application project uses AppAuth as the third party library for OAuth 2.0 communication between the client and server. The AppAuth library is added as a dependency in the pod file. 

There are two key configuration steps that you need to perform before you run the application.

To configure application settings, right click on the <SAMPLES_HOME>/oidc-client-app-samples/ios-client-app-sample/WSO2-IS-SampleApp/Info.plist file and open it with a source code editor.

• In the source code, you will see the following lines of code:

  <key>CFBundleURLTypes</key> <array> <dict> <key>CFBundleURLName</key> <string>wso2is.local</string> <key>CFBundleURLSchemes</key> <array> <string>wso2issample</string> </array> </dict> </array>

  Here, the CFBundleURLTypes property specifies the URL scheme of the application. The URL scheme defines the manner in which applications communicate with each other. The sample application uses a custom URL scheme called wso2issample. 

  This is why you had to specify wso2issample://oauth as the callback URL when you created the OAuth service provider in the Setting up WSO2 Identity Server section. When authentication is done, users are redirected to the sample application through the wso2issample://oauth URL.

• You will also see the following lines of code:

  <key>NSAppTransportSecurity</key> <dict> <key>NSAllowsArbitraryLoads</key> <true/> </dict>

  The above code block specifies that you allow the application to connect to sources with untrusted certificates. You can only use the above code block in a test environment. 

To configure endpoint and OAuth client settings, right click on the <SAMPLES_HOME>/oidc-client-app-samples/ios-client-app-sample/WSO2-IS-SampleApp/Config.plist file and open it with a source code editor.

• In the source code, you will see several OAuth related properties defined as follows:

  <dict> <key>IssuerURL</key> <string>https://localhost:9443</string> <key>LogOutURL</key> <string>https://localhost:9443/oidc/logout</string> <key>UserInfoURL</key> <string>https://localhost:9443/oauth2/userinfo?schema=openid</string> <key>TokenURL</key> <string>https://localhost:9443/oauth2/token</string> <key>AuthURL</key> <string>https://localhost:9443/oauth2/authorize</string> <key>RedirectURL</key> <string>wso2issample://oauth</string> <key>ClientID</key> <string>[YOUR_OAUTH_CLIENT_ID]</string> </dict>

  The first few properties are endpoints of the WSO2 Identity Server OAuth API. You can replace these values depending on your WSO2 Identity Server setup. 

  • The RedirectURL should be the same URL that you specified as the callback URL when you created the OAuth service provider in the Setting up WSO2 Identity Server section. 

  • The ClientID should be the OAuth client ID that you obtained in the Setting up WSO2 Identity Server section.