Navigation

ToDo (iOS App)

On this page

This tutorial demonstrates how to use MongoDB Stitch to integrate the following services for an iOS application:

  • Anonymous/Google/Facebook user authentication services
  • MongoDB service

This tutorial incorporates the services into a provided ToDo iOS application. The ToDo application maintains a single-user todo list. Users can log in using Google or Facebook credentials, add items to the list, check completed items and delete completed items.

The ToDo app uses the items collection in the todo database, which stores a document per each todo item.

Prerequisites

For this app, you need the following:

  • A MongoDB Atlas cluster using MongoDB version 3.4+. This tutorial uses an Atlas Free Tier cluster.
  • A developer account with either Google or Facebook (or both) for user authentication services.
  • iOS 11.0+
  • Xcode 8.2+ and an Xcode project.

Procedure

A. Create a Stitch App

Estimated Time to Complete: ~8 minutes

1

Log into Atlas.

To use MongoDB Stitch, you must be logged into MongoDB Atlas. If you do not have an Atlas account, follow the instructions in the Atlas documentation to create an account.

2

Create an Atlas cluster.

If you do not already have an Atlas cluster for use with MongoDB Stitch, create a cluster.

Important

You must deploy the Atlas cluster with MongoDB version 3.4 or later.

The Sync features require 3.6 or later.

Atlas provides a Free Tier M0 replica set as well as paid M10+ clusters. Free Tier deployments have restrictions as compared to paid M10+ deployments but will work for the purposes of this tutorial. For complete documentation on these restrictions, see Atlas M0 (Free Tier), M2, and M5 Limitations.

3

Add a MongoDB Stitch application.

  1. In Atlas, click Stitch Apps in the left-hand navigation.
  2. Click the Create New Application button.
  3. Under Application Name, enter a name for your application. The name can only contain ASCII letters, numbers, underscores, and hyphens.
  4. Under Link To Cluster, select the MongoDB Atlas cluster that you’d like to use for your application.
  5. Click Create.

After you click Create, a new Stitch application will be created for you. The application will include a MongoDB service named mongodb-atlas that is linked to your cluster. This process may take several minutes.

Once your application has been created, you will be automatically redirected to the Stitch application console.

B. Define Stitch Rules

Estimated Time to Complete: ~6 minutes

Stitch rules specify the read and write access for the fields in your collections.

1

Configure MongoDB.

Create a namespace for the todo.items collection:

  1. Click on Rules under Atlas Clusters in the left navigation pane.

  2. Click the + Add Collection button.

  3. In the Add New Collection dialog, provide the following values:

    Property Value
    Database Name todo
    Collection Name items
    Select a Template Users can only read and write their own data
    Field Name For User ID owner_id

    Stitch creates a new rule (a combination of a role and permissions) based on the template. This rule allows an authenticated user to only read and write their own documents and to insert new documents.

  4. Click Add Collection.

MongoDB Authorization

MongoDB Stitch rules do not override the read and write access (i.e. authorization) that may have been set up separately in MongoDB. That is, MongoDB Stitch rules determine whether the fields are readable or writable; not whether the client has authorization to read or write to a particular database or collection.

Similarly, MongoDB Stitch validation rules do not override document validation rules set up separately in MongoDB.

2

Review Rules for Documents in todo.items.

To view the rule associated with the template, expand todo, and then click on items. Click on the edit button ( pencil icon ) to open the role editor.

By default, the collection has the following Apply When rule:

{
  "owner_id": "%%user.id"
}

With this rule, read and write operations can access all fields in a document if the document contains an owner_id field whose value equals the user ID (%%user.id) of the client issuing the read. If the owner_id field in the document does not equal the client user id, the document is not readable.

For more information on MongoDB rules, see MongoDB Rules.

3

Add a Filter for todo.items.

Filters improve performance by filtering the results returned from a MongoDB call. To add a filter, click on the Filters tab.

To create a filter rule, click the Filters tab, and then click the + New Filter button. Click the filter 1 header to expand it, and then provide the following values:

Field Value
Apply When { "%%true": true }
Filter Query { "owner_id": "%%user.id" }

This filter indicates that when %%true equals true (i.e. always), return only the documents where the owner_id field matches the %%user.id.

Click the Save button to save your changes.

Note

Adding this filter is optional, because it duplicates the logic in the rules that were added with the template we chose. However, in a large-scale application, this filter improves performance significantly.

For more information on filters, see MongoDB Filters.

C. Enable Anonymous Auth

Estimated Time to Complete: 1 minute

To use Anonymous Authentication in the application:

1

Go to Authentication page.

Select Users from the left-side navigation.

2

Enable anonymous authentication.

  1. For Allow users to log in anonymously, click the Edit button.
  2. Switch the toggle to enabled, and then save your changes.

D. Set Up Facebook Authentication

Estimated Time to Complete: ~10 minutes

1

Set up an app in Facebook.

  1. Log in to your Facebook Developer account. If you do not have a Facebook developer account or even a Facebook account, see Facebook - Register and Configure an App.

  2. Add a new Facebook application.

  3. Once created, your application view opens to Product Setup. If not, go to your newly added app and click Add Product.

  4. In Product Setup, click Get Started for Facebook Login. The screen should display the Quickstart instructions.

  5. Choose iOS for your platform.

  6. In the Quick Start for iOS:

    1. You can skip the Download the Facebook SDK for iOS step and the Add Login Kit to your Xcode Project step as the ToDo iOS app project covers these steps.

    2. For the Add your Bundle Identifier step, enter the following and click Save:

      com.mongo.MongoDBSample
      
    3. Optional. You can enable/disable Single Sign On and continue to the next step.

    4. Note the following entry for your project file:

      FacebookAppID entry to copy into your project’s MongoDBSample/Resources/Info.plist file.

      <key>FacebookAppID</key>
      <string>1111111881399056</string>
      

      You will use this during the setup step of the ToDo iOS project in this tutorial.

    5. You can omit the remaining steps as they are already incorporated into the ToDo iOS project.

  7. Click Settings under Facebook Login in the left-hand navigation menu.

  8. Under Valid OAuth redirect URIs, add the following entry:

    https://stitch.mongodb.com/api/client/v2.0/auth/callback
    
  9. Save changes.

  10. Click Settings for your application (i.e. not the Settings under Facebook Login). Note the App ID and App Secret. You will use the information in the Users section of the MongoDB Stitch Admin Console.

2

Configure Stitch for Facebook Authentication.

  1. Select Users from the left-side navigation.
  2. Select the Providers tab.
  3. For Facebook, click the Edit button.
  4. In the Facebook provider settings:
    • Switch the Provider Status toggle to enabled.
    • Enter your new Facebook App ID in the Client ID field and Facebook App Secret in Client Secret field.
  5. Click Save.

E. Set Up Google Authentication

Estimated Time to Complete: ~10 minutes

Note

For Google authentication, you must create both iOS client credentials and web client credentials.

1

Create the iOS OAuth 2.0 client in Google Cloud Platform.

  1. Open the Google Cloud Platform console.

  2. From the projects list, select an existing project or create a new one.

  3. If the APIs & services page isn’t already open, open the left-side menu and select APIs & services.

  4. In the left menu, click Credentials.

  5. Click the New Credentials dropdown, and then select OAuth client ID.

  6. Select iOS.

  7. Provide a name for your application.

  8. Use the following value for the Bundle ID:

    com.mongo.MongoDBSample
    
  9. Click Create.

  10. In the list of OAuth 2.0 client IDs, click the client ID that has the name you specified.

  11. Make note of the iOS URL scheme value; you will add this to your iOS project later in this tutorial.

    For more information on creating OAuth client ID credentials for your application, refer to the Google support website.

2

Create the Web App client credentials.

  1. From the Google Cloud Platform Console console, click the New Credentials dropdown, and then select OAuth client ID.

  2. Select Web application.

  3. Provide a name for your application.

  4. For Authorized JavaScript origins, enter the following value:

    https://stitch.mongodb.com
    
  5. For Authorized redirect URIs, enter the following value:

    https://stitch.mongodb.com/api/client/v2.0/auth/callback
    
  6. Click Create.

  7. Note the client ID and secret. You will use these values in the Users section of the MongoDB Stitch Console in the next section of this tutorial.

3

Configure Stitch Admin Console for Google Authentication

  1. Select Users from the left-side navigation.
  2. Select the Providers tab.
  3. For Google, click the Edit button.
  4. In the Google provider settings:
    • Switch the Provider Status toggle to enabled.
    • Enter your new Client ID and Client Secret from the Google Web App client credentials.
  5. Click Save.

F. Download the Application Source Code

Estimated Time to Complete: ~2 minutes

Clone the Stitch github example repository, or download the zip file for the repo and unzip it. The source code for the ToDo iOS application can be found in todo/ios directory.

G. Configure and Run the Application

1

Open the project in Xcode.

  1. Navigate to the downloaded example directory and navigate to the /todo/ios directory.
  2. Open the workspace file MongoDBSample.xcworkspace.
2

Update Xcode project with your MongoDB Stitch App ID.

From the MongoDBSample view:

  1. Open the MongoDBSample/Resources/Stitch-Info.plist file.

  2. Update the APP_ID with your MongoDB Stitch app id and save.

    In the MongoDB Stitch console, you can find your App ID in the Clients view.

3

Configure project authentication.

A. If you are using Facebook authentication:

  1. Open the MongoDBSample/Resources/Info.plist file.

  2. Update the FacebookAppID with your facebook_app_id entry. The entry is listed in step D.1 above, under in Set Up Facebook Authentication.

  3. In the left-hand navigation pane, click on the top-most MongoDBSample container icon (not the folder).

  4. In the left-hand side of the General tab, click on the MongoDBSample dropdown, and then select MongoDBSample under Targets.

  5. Click on the Info tab and expand the URL Types section.

  6. Click on the + to add a new URL.

  7. In the URL Schemes, enter the Facebook Login Protocol Scheme, which is fb followed by your Facebook app id. For example, if your app id is 12345678, you would enter the following value:

    fb12345678
    

B. If you are using Google authentication:

  1. Click on the MongoDBSample project (not the folder) in the left hand navigation pane.

  2. In the left-hand side of the General tab, click on the MongoDBSample dropdown, and then select MongoDBSample under Targets.

  3. Click on the Info tab and expand the URL Types section.

  4. Click on the + to add a new URL.

  5. In the URL schemes, paste in the value of the iOS URL scheme that was generated when you created the Google iOS OAuth client. It will look similar to this:

    com.googleusercontent.apps.153606348799-cm5beb6ijp46iej68bkpjnl279r3hfhh
    
4

Run the todo app.

From the top menu bar, go to Product and select Clean. You can now run the app.