How to build Mailgun Email passwordless sign-in with iOS (Swift)

For our new friends:

Logto is an Auth0 alternative designed for modern apps and SaaS products. It offers both Cloud and Open-source services to help you quickly launch your identity and management (IAM) system. Enjoy authentication, authorization, and multi-tenant management all in one.

We recommend starting with a free development tenant on Logto Cloud. This allows you to explore all the features easily.

In this article, we will go through the steps to quickly build the Mailgun sign-in experience (user authentication) with iOS (Swift) and Logto.

Prerequisites

A running Logto instance. Check out the introduction page to get started.
Basic knowledge of iOS (Swift).
A usable Mailgun account.

Create an application in Logto

Logto is based on OpenID Connect (OIDC) authentication and OAuth 2.0 authorization. It supports federated identity management across multiple applications, commonly called Single Sign-On (SSO).

To create your Native app application, simply follow these steps:

Open the Logto Console. In the "Get started" section, click the "View all" link to open the application frameworks list. Alternatively, you can navigate to Logto Console > Applications, and click the "Create application" button.
In the opening modal, click the "Native app" section or filter all the available "Native app" frameworks using the quick filter checkboxes on the left. Click the "iOS (Swift)" framework card to start creating your application.
Enter the application name, e.g., "Bookstore," and click "Create application".

🎉 Ta-da! You just created your first application in Logto. You'll see a congrats page which includes a detailed integration guide. Follow the guide to see what the experience will be in your application.

Integrate iOS (Swift) with Logto

Add Logto SDK as a dependency

Use the following URL to add Logto SDK as a dependency in Swift Package Manager.

https://github.com/logto-io/swift.git

Since Xcode 11, you can directly import a Swift package w/o any additional tool.

We do not support Carthage and CocoaPods at the time due to some technical issues.

Carthage

Carthage needs a xcodeproj file to build, but swift package generate-xcodeproj will report a failure since we are using binary targets for native social plugins. We will try to find a workaround later.

CocoaPods

CocoaPods does not support local dependency and monorepo, thus it's hard to create a .podspec for this repo.

Init LogtoClient

Initialize the client by creating a LogtoClient instance with a LogtoConfig object.

ContentView.swift
import Logto
import LogtoClient

let config = try? LogtoConfig(
  endpoint: "<your-logto-endpoint>", // E.g. http://localhost:3001
  appId: "<your-app-id>"
)
let client = LogtoClient(useConfig: config)

info:

By default, we store credentials like ID Token and Refresh Token in the Keychain. Thus the user doesn't need to sign in again when he returns.

To turn off this behavior, set usingPersistStorage to false:

let config = try? LogtoConfig(
  // ...
  usingPersistStorage: false
)

Before we dive into the details, here's a quick overview of the end-user experience. The sign-in process can be simplified as follows:

Your app invokes the sign-in method.
The user is redirected to the Logto sign-in page. For native apps, the system browser is opened.
The user signs in and is redirected back to your app (configured as the redirect URI).

This authentication process follows the OpenID Connect (OIDC) protocol, and Logto enforces strict security measures to protect user sign-in.
If you have multiple apps, you can use the same identity provider (Logto). Once the user signs in to one app, Logto will automatically complete the sign-in process when the user accesses another app.

To learn more about the rationale and benefits of redirect-based sign-in, see Logto sign-in experience explained.

Configure redirect URI

Let's switch to the Application details page of Logto Console. Add a Redirect URI io.logto://callback and click "Save changes".

info:

The Redirect URI in iOS SDK is only for internal use. There's NO NEED to add a Custom URL Scheme until a connector asks.

note:

Before calling .signInWithBrowser(redirectUri:), make sure you have correctly configured Redirect URI in Admin Console.

You can use client.signInWithBrowser(redirectUri:) to sign in the user and client.signOut() to sign out the user.

For example, in a SwiftUI app:

ContentView.swift
struct ContentView: View {
  @State var isAuthenticated: Bool

  init() {
    isAuthenticated = client.isAuthenticated
  }

  var body: some View {
    VStack {
      if isAuthenticated {
        Button("Sign Out") {
          Task { [self] in
            await client.signOut()
            isAuthenticated = false
          }
        }
      } else {
        Button("Sign In") {
          Task { [self] in
            do {
              try await client.signInWithBrowser(redirectUri: "${
                props.redirectUris[0] ?? 'io.logto://callback'
              }")
              isAuthenticated = true
            } catch let error as LogtoClientErrors.SignIn {
              // error occured during sign in
            } catch {
              // other errors
            }
          }
        }
      }
    }
  }
}

Checkpoint: Test your application

Now, you can test your application:

Run your application, you will see the sign-in button.
Click the sign-in button, the SDK will init the sign-in process and redirect you to the Logto sign-in page.
After you signed in, you will be redirected back to your application and see the sign-out button.
Click the sign-out button to clear token storage and sign out.

Add Mailgun connector

Email connector is a method used to send one-time passwords (OTPs) for authentication. It enables Email address verification to support passwordless authentication, including Email-based registration, sign-in, two-factor authentication (2FA), and account recovery. You can easily connect Mailgun as your Email provider. With the Logto Email connector, you can set this up in just a few minutes.

To add a Email connector, simply follow these steps:

Navigate to Console > Connector > Email and SMS connectors.
To add a new Email connector, click the "Set up" button and select "Mailgun".
Review the README documentation for your selected provider.
Complete the configuration fields in the "Parameter Configuration" section.
Customize the Email template using the JSON editor.
Test your configuration by sending a verification code to your Email address.

note:

If you are following the in-place Connector guide, you can skip the next section.

Set up Mailgun email connector

Prerequisites

A Mailgun account
An API key from your Mailgun account, requires the permission to send messages (emails). See Where Can I Find My API Key and SMTP Credentials? for more information.

Basic configuration

Fill out the endpoint field when you are using a different Mailgun API endpoint, for example, EU region should be https://api.eu.mailgun.net. The default value is https://api.mailgun.net.
Fill out the domain field with the domain you have registered in your Mailgun account. This value can be found in the Domains section of the Mailgun dashboard. The domain should be in the format example.com, without the https:// or http:// prefix.
Fill out the apiKey field with the API key you have generated in your Mailgun account.
Fill out the from field with the email address you want to send emails from. This email address must be registered in your Mailgun account. The email address should be in the format Sender Name \<[email protected]>.

Deliveries

Config object

The "Deliveries" section allows you to configure the content of the emails to be sent in different scenarios. It is a JSON key-value map where the key is the usage type and the value is an object containing the content config for the email to be sent.

{
  "<usage-type>": {
    // ...
  }
}

Usage types

The following usage types are supported:

Register: The email to be sent when a user is registering.
SignIn: The email to be sent when a user is signing in.
ForgotPassword: The email to be sent when a user is resetting their password.
Generic: The email to be sent when a user is performing a generic action, for example, testing the email connector.

note:

If the usage type is not specified in the deliveries config, the generic email will be sent. If the generic email is not specified, the connector will return an error.

Content config

The connector supports both direct HTML content and Mailgun template. You can use one of them for each usage type.

In both subject and content, you can use the {{code}} placeholder to insert the verification code.

To use direct HTML content, fill out the following fields:

subject: The subject of the email to be sent.
replyTo: The email address to be used as the reply-to address.
html: (Required) The HTML content of the email to be sent.
text: The plain text version of the email to be sent.

To use Mailgun template, fill out the following fields:

subject: The subject of the email to be sent.
replyTo: The email address to be used as the reply-to address.
template: (Required) The name of the Mailgun template to be used.
variables: The variables to be passed to the Mailgun template. Should be a JSON key-value map since it will be stringified before sending to Mailgun. Note there's no need to include the code variable since it will be automatically added by the connector.

Example

The following is an example of the deliveries config:

{
  "Register": {
    "subject": "{{code}} is your verification code",
    "replyTo": "Foo <[email protected]>",
    "html": "<h1>Welcome to Logto</h1><p>Your verification code is {{code}}.</p>",
    "text": "Welcome to Logto. Your verification code is {{code}}."
  },
  "SignIn": {
    "subject": "Welcome back to Logto",
    "replyTo": "Foo <[email protected]>",
    "template": "logto-sign-in",
    "variables": {
      "bar": "baz"
    }
  }
}

Save your configuration

Double check you have filled out necessary values in the Logto connector configuration area. Click "Save and Done" (or "Save changes") and the Mailgun connector should be available now.

Once you create a connector successfully, you can enable phone number-based passwordless login and registration.

Navigate to Console > Sign-in experience > Sign-up and sign-in.
Set up sign-up methods (Optional):
1. Select "Email address" or "Email or phone number" as the sign-up identifier.
2. "Verify at sign-up" is forced to be enabled. You can also enable "Create a password" on registration.
Set up sign-in methods:
1. Select Email address as one of sign-in identifiers. You can provide multiple available identifiers (email, phone number, and username).
2. Select "Verification code" and / or "Password" as the authentication factor.
Click "Save changes" and test it in "Live preview".

In addition to registration and login via OTPs, you can also have password recovery and -based security verification enabled, as well as linking Email address to profile. See End-user flows for more details.

Testing and Validation

Return to your iOS (Swift) app. You should now be able to sign in with Mailgun. Enjoy!

Create an application in Logto​

Integrate iOS (Swift) with Logto​

Add Logto SDK as a dependency​

Carthage​

CocoaPods​

Init LogtoClient​

Sign in​

Regarding redirect-based sign-in​

Configure redirect URI​

Sign-in and sign-out​

Checkpoint: Test your application​

Add Mailgun connector​

Set up Mailgun email connector​

Prerequisites​

Basic configuration​

Deliveries​

Config object​

Usage types​

Content config​

Example​

Save your configuration​

Enable Mailgun connector in Sign-in Experience​

Testing and Validation​

Further readings​

Create an application in Logto

Integrate iOS (Swift) with Logto

Add Logto SDK as a dependency

Carthage

CocoaPods

Init LogtoClient

Sign in

Regarding redirect-based sign-in

Configure redirect URI

Sign-in and sign-out

Checkpoint: Test your application

Add Mailgun connector

Set up Mailgun email connector

Prerequisites

Basic configuration

Deliveries

Config object

Usage types

Content config

Example

Save your configuration

Enable Mailgun connector in Sign-in Experience

Testing and Validation

Further readings