Email Link/Passwordless
Email Link authentication, which is also referred to as Passwordless authentication, works by sending a verification email to a user requesting to sign in. This verification email contains a special Dynamic Link that links the user back to your app, completing authentication in the process. In order to configure this method of authentication, we will use Firebase Dynamic Links, which we will need to set up.
If this is your first time working with Dynamic Links, here's a great introduction video from Firebase's Firecast series on YouTube. Note, we will outline most of the steps covered in this tutorial below!
Start by going to the Firebase Console and navigate to your project:
- Select the Auth panel and then click the Sign In Method tab.
- Click Email/Password and ensure it is enabled.
- Turn on Email link (passwordless sign-in), then click Save.
Configuring Dynamic Links
As we mentioned above, we will need to configure dynamic links for this auth flow.
- Go to the project's settings on the Firebase console. When enabling dynamic links, you will need to add an App Store ID and a Team ID. Feel free to make up the App Store ID (ex: 123456789). For the Team ID, enter an id affiliated with an Apple Developer account.
- Navigate to the Dynamic Links in the Firebase Console and click Get Started
- Enter a domain. Something like authenticationexample.page.link works. Note, this domain will likely be taken so adjust authenticationexample accordingly (ex: authenticationexample123). Either way, be sure to add the .page.link to complete the domain link!
- Now, copy the domain you created above and navigate in Xcode to the Signing & Capabilities tab of the app's main target. You will need to add the Associated Domains capability. If your project has automatically manage signing checked (also on this tab), you can add the Associated Domains capability by tapping the "+" button (also on that tab). If not, you will need to add this capability on the Apple Developer console and download the resulting provisioning profile before moving to the next steps. Please refer to the Firebase docs for more info.
- Once you have the Associated Domains capability enabled and have copied the domain you created on the Firebase Console, paste
applinks:[insert the domain you copied] into the Associated Domains section on either Xcode or Apple developer console (depending on how you set up Associated Domains in the previous step)
- Example:
applinks: authenticationexample.page.link
Now let's create the dynamic link that will be used in the Passwordless login flow. Return to the Dynamic Links tab on the Firebase Console. Click New Dynamic Link, then:
- Setup your short URL. Feel free to put whatever here, like "demo", "login, or "passwordless" for example. Click Next.
- For the Deep Link URL, configure the URL to look like:
https://[insert an authorized domain]/login?email=email
For the authorized domain ⬆, go to the the Authentication tab, then click the "Sign-in method", and scroll down to the "Authorized domains" section. Copy the domain that looks like [the app's name].firebaseapp.com. Paste this entire domain into the Deep Link we are creating above. You can also instead allowlist the dynamic links URL prefix and use that here as well.
- On step 3, Define link behavior for iOS, select Open the deep link in your iOS App and make sure your app is selected in the drop down.
- Configure the following steps as you please and then hit Create!
Run the app on your device or simulator.
- Select Email Link/Passwordless. This will present a login screen where you can enter an email for the verification email to be sent to.
- Enter an email and tap Send Sign In Link. While keeping the current view controller displayed, switch to a mail app and wait to receive the verification email.
- Once the email has been received, open it and tap the sign in link. This will link back to the quickstart and finish the login flow.
See the Getting Started with Email Link/Passwordless Sign In guide for more details.
So how does this work?
We will start by taking a look at PasswordlessViewController.swift. If you are currently running the quickstart app, select the "Email Link/Passwordless" authentication option.
The user is prompted for an email to be used in the verification process. When the Send Sign In Link button is tapped, we configure our verification link by adding the user's email to the dynamic link we created earlier. Then we send a send the link to the user's email. You can edit the format of these verification emails on the Firebase Console.
When the user receives the verification email, they can open the link contained in the email to be redirected back to the app (using the power of Dynamic Links 😎. On apps using the SceneDelegate API, opening the incoming dynamic link will be handled in UIWindowSceneDelegate's func scene(_ scene: UIScene, continue userActivity: NSUserActivity) method. This method can be implemented in SceneDelegate.swift. Since the quickstart uses the SceneDelegate API, you can check out the implementation here. We basically pass the incoming link to a helper method that will do a few things:
// SceneDelegate.swift
private func handleIncomingDynamicLink(_ incomingURL: URL) {
DynamicLinks.dynamicLinks().handleUniversalLink(incomingURL) { (dynamicLink, error) in
// Handle the potential `error`
guard let link = dynamicLink?.url?.absoluteString else { return }
// Here, we check if our dynamic link is a sign-link (the one we emailed our user!)
if Auth.auth().isSignIn(withEmailLink: link) {
// Save the link as it will be used in the next step to complete login
UserDefaults.standard.set(link, forKey: "Link")
// Post a notification to the PasswordlessViewController to resume authentication
NotificationCenter.default.post(Notification(name: Notification.Name("PasswordlessEmailNotificationSuccess")))
}
}
}
If the incoming dynamic link is a sign-in link, then we post a notification that pretty much says: "Hey! A user just opened a verification dynamic link that we emailed them and we need to complete the authentication!"
This takes us back to our PasswordlessViewController.swift, where we registered for this exact notification! When the notification is posted, we will receive it here and call the passwordlessSignIn() method to complete the authentication. In this method, we used Firebase Auth's Auth.auth().signIn(withEmail: String, link: String) which, behind the scenes, checks that this link was the link we originally sent to the associated email and if so, signs in the user! 🥳
Phone Number
When Firebase Auth uses Phone Number authentication, Auth will attempt to send a silent Apple Push Notification (APN) to the device to confirm that the phone number being used is associated with the device. If APNs (which, like Sign In with Apple, are a capability you can enable in Xcode or on the Apple Developer Console) are not enabled or configured correctly, Auth will instead present a web view with a reCAPTCHA verification flow.
Start by going to the Firebase Console and navigate to your project:
- Select the Auth panel and then click the Sign In Method tab.
- Click Phone and turn on the Enable switch, then click Save.
- Run the app on your device or simulator.
- Choose Phone Number to launch the Phone Number Authentication flow
- After entering a phone number, please wait roughly 5 seconds to allow Firebase Auth to present the necessary flow.
See the official Firebase docs for phone authentication for more info!
Anonymous Authentication
Start by going to the Firebase Console and navigate to your project:
- Select the Auth panel and then click the Sign In Method tab.
- Click Anonymous and turn on the Enable switch, then click Save.
- Run the app on your device or simulator.
- Choose Anonymous Authentication to launch the Anonymous Sign In flow
See the official Firebase docs for anonymous authentication for more info!
Custom Auth System
Firebase Auth can manage authentication for use cases that utilize a custom auth system. Ensure you have an authentication server capable of producing custom signed tokens. When a user signs in, make a request for a signed token from your authentication server.
After your server returns the token, pass that into Firebase Auth's signIn(withCustomtoken: String) method to complete the authentication process. In the quickstart, you can demo signing in with tokens you generate. See CustomAuthViewController.swift for more info.
If you wish to setup a custom auth system. The below steps can help in its configuration.
- In the Firebase Console, navigate to Project settings:
- Navigate to the Service accounts tab.
- Locate the section All service account, and click on the
X service accounts link. This will take you to the Google Cloud Console.
- In the Google Cloud Console:
- Make sure the right Firebase project is selected.
- From the left "hamburger" menu navigate to the API Manager tab.
- Click on the Credentials item in the left column.
- Click New credentials and select Service account key. Select New service account,
pick any name, and select JSON as the key type. Then click Create.
- You should now have a new JSON file for your service account in your Downloads directory.
- Open the file
web/auth.html in your computer's web browser. The auth.html file can now be found in the current directory's LegacyAuthQuickstart subdirectory.
- Click Choose File and upload the JSON file you just downloaded.
- Enter any User ID and click Generate.
- Copy the token link displayed.
- Run the app on your device or simulator.
- Select Custom Auth system
- Paste in the token you generated earlier.
- Pressing Login should then login the token's affiliated user.
Support
License
Copyright 2020 Google LLC
Licensed to the Apache Software Foundation (ASF) under one or more contributor
license agreements. See the NOTICE file distributed with this work for
additional information regarding copyright ownership. The ASF licenses this
file to you under the Apache License, Version 2.0 (the "License"); you may not
use this file except in compliance with the License. You may obtain a copy of
the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations under
the License.
