Build a protected iOS app with Flutter

How to architect or construct Flutter apps is beyond the scope of this guide. It’s also worth noting that there are many Flutter libraries and frameworks for building mobile applications. What is "best" is highly contextual to the product and user requirements for any given project.

To simply demonstrate our SDK integration, we use some basic Flutter patterns and the Material design UI library.

This is a "hands-on" guide. We are providing the mobile app and resource server for you. You can find the repo on GitHub to follow along. All you’ll need is your own ForgeRock® Identity Cloud or Access Management (AM) instance. If you don’t have access to either, and you are interested in the ForgeRock® Identity Platform, reach out to a representative today, and we’ll be happy to get you started.

You need a simple username and password authentication journey/tree for this guide.

Within the ForgeRock server, create a public, "Native", OAuth client for the mobile client app with the following values:

Each of the above is required, so double check you set each of the items correctly. If you don’t, you’ll likely get an "invalid OAuth client" error in Xcode logs.

Create a test user (identity) in your ForgeRock server within the realm you will use.

If using an Identity Cloud tenant, follow our ForgeRock documentation for creating a user in Identity Cloud.

Or, if you are using AM, click Identities in the left navigation. Use the following instructions to create a user:

First, create a new directory mkdir, clone the Flutter Sample project to your local computer, and checkout the branch for this guide:

In addition, there’s a branch that represents the completion of this guide. If you get stuck, you can visit part-one-complete branch in GitHub, and use it as a reference.

This Flutter app requires the installation of the native ForgeRock iOS SDK. You can install this by using SPM (Swift Package Manager) on the generated iOS project.

Next, we need to open Android Studio and build the project. If you haven’t configured Android Studio for Flutter, please follow the guide in the Flutter documentation.

Don’t forget to set the Dart SDK path in Android Studio. You can find that in the folder where you downloaded the Flutter SDK. (For example, ~/flutter/bin/cache/dart-sdk.)

In Android Studio, click File > Open, and navigate to forgerock-flutter-sample/Flutter_To_Do_app/. When Android Studio loads the project and is ready, install any gradle dependencies, and select the iOS simulator to build and run the project.

Additionally, you are required to install the node dependencies for the ToDo node Server.

Using the ForgeRock server settings from above, edit the .env.js file within the project. This can be found the root folder of your project. Add your relevant values to configure all the important server settings to your project. Not all variables will need values at this time. You can list the file in the Terminal by doing ls -a, and edit it using a text editor like nano or vi.

A hypothetical example (required variables commented):

Descriptions of relevant values:

We first need to review the files that allow for the "bridging" between our Flutter project and our native SDKs. In Xcode, navigate to the Runner/Runner directory, and you will see a few important files:

In the Xcode directory/file list section, also known as the Project Navigator, complete the following:

A hypothetical example (your values may vary):

Descriptions of relevant values:

Staying within the Runner directory, find the FRAuthSampleBridge file and open it. We have parts of the file already stubbed out and the dependencies are already installed. All you need to do is write the functionality.

For the SDK to initialize with the FRAuth.plist configuration from Step 2, write the start function as follows:

The start() function above calls the iOS SDK’s start() method on the FRAuth class. There’s a bit more that may be required within this function for a production app. We’ll get more into this in a separate part of this series, but for now, let’s keep this simple.

Once the start() method is called, and it has initialized, the SDK is ready to handle user requests. Let’s start with login().

Just underneath the start() method we wrote above, add the login() method.

This login() function initializes the journey/tree specified for authentication. You call this method without arguments as it does not log the user in. This initial call to the ForgeRock server will return the first set of callbacks that represents the first node in your journey/tree to collect user data.

Also, notice that we have a special "handler" function within the callback of FRUser.login(). This handleNode() method serializes the node object that the iOS SDK returns in a JSON string. Data passed between the "native" layer and the Flutter layer is limited to serialized objects. This method can be written in many ways and should be written in whatever way is best for your application.

To finalize the functionality needed to complete user authentication, we need a way to iteratively call next() until the tree completes successfully or fails. In the bridge file, add a private method called handleNode().

First, we will write the decoding of the JSON string and prepare the node for submission.

Now that you’ve prepared the data for submission, introduce the node.next() call from the iOS SDK. Then, handle the subsequent node returned from the next() call, or process the success or failure representing the completion of the journey/tree.

The above code handles a limited number of callback types. Handling full authentication and registration journeys/trees requires additional callback handling. To keep this tutorial simple, we’ll focus just on SingleValueCallback type.

Finally, add the following lines of code to enable logout for the user:

First, let’s review how the application renders the home view. Open Android Studio and navigate to the Flutter project, flutter_todo_app > java/main.dart.

Open up the second file in the above sequence, the java/main.dart file, and notice the following:

Flutter uses something called MethodChannel to communicate between Flutter and the Native layer. In this application we will define a MethodChannel with the following identifier: 'forgerock.com/SampleBridge'.

The same identifier will be used in the iOS FRSampleBridge so that the two layers communicate and pass information. To initialize the ForgeRock SDK when the log in view first loads, we call the frStart() method on the bridge code.

Navigate to the app’s login view within the Simulator. You should see an empty screen with a button, since the app doesn’t have the data needed to render the form. To render the correct form, retrieve the initial data from the ForgeRock server. This is our first task.

Since most of the action is taking place in flutter_todo_app/Java/login.dart, open it and add the following:

To develop the login functionality, we first need to use the login() method from the bridge code to get the first set of callbacks, and then render the form appropriately. This login() method is an asynchronous method. Let’s get started!

Compose the data gathering process using the following:

The above code is expected to return either a Node with a set of Callback objects, or a success/error message. We need to handle any exceptions thrown from the bridge on the catch block. Typically, when we begin the authentication journey/tree, this returns a Node. Using the FRNode helper object, we parse the result in a native Flutter FRNode object.

In the next step we are going to "handle" this node, and produce our UI.

The _handleNode() method focuses on the callbacks property. This property contains instructions about what to render to collect user input.

The previous code processes the Node callbacks and generates two TextField objects:

Use the frCallback.type to differentiate between the two TextField objects and obscure the text of each TextField. Next, add the TextField objects to the List and create the accompanying TextEditingControllers.

Run the app again, and you should see a dynamic form that reacts to the callbacks returned from our initial call to ForgeRock.

Since a form that can’t submit anything isn’t very useful, we’ll now handle the submission of the user input values to ForgeRock. Continuing in login.dart, edit the current _okButton element, adding an onPressed handler calling the _next() function. This function should do the following:

After the app refreshes, use the test user to login. If successful, you should see a success message. Congratulations, you are now able to authenticate users!

What’s more, you can verify the authentication details by going to the Xcode or Android Studio log, and observing the result of the last call to the ForgeRock server. It should have a type of LoginSuccess with token information.

Now that the user can log in, let’s go one step further and redirect to the TodoList screen. After we get the LoginSccess message we can call the _navigateToNextScreen() method. This will navigate to the TodoList class. When the TodoList initializes, we want to request information about the authenticated user to display their name and other information. We will now utilize the existing FRAuthSampleBridge.getUserInfo() method already included in the bridge code.

Let’s do a little setup before we make the request to the ForgeRock server:

With the setup complete, implement the request to ForgeRock for the user’s information. Within this empty _getUserInfo(), add an async function to make that call FRAuthSampleBridge.getUserInfo() and parse the response.

In the code above, we collected the user information and set the name and email of the user in some variables. In addition to updating the user info, we will call the _getTodos() method in order to retrieve ToDos from the server. Notice that we use the setState() function. This ensures that our UI is updated based on the newly received information.

When you test this in the Simulator, completing a successful authentication results in the home screen being rendered with a success message. The user’s name and email are included for visual validation. You can also view the console in Xcode and see more complete logs.

Now, add the logic into the view to call this new Swift method. Open the todolist.dart file, and add the following:

Revisit the app within the Simulator, and tap the Sign Out button. This time around when clicking yes, will dispose of the alert and log you out, returning you back to the log in screen. If you tap no, you will return to the ToDo list screen.

You should now be able to successfully authenticate a user, display the user’s information, and log a user out.

Congratulations, you just built a ForgeRock protected iOS app with Flutter!