Mar Cabrera

Technical Services Engineer

Authentication is one of the most important features for any app these days, and there will be a point when your users might want to reset their password for different reasons.

Atlas App Services can help implement this functionality in a clear and simple way. In this tutorial, we’ll develop a simple app that you can follow along with and incorporate into your apps.

If you also want to follow along and check the code that I’ll be explaining in this article, you can find it in the [Github repository](https://github.com/mongodb-developer/Reset-Password-Swift). 

## Context

The application consists of a login flow where the user will be able to create their own account by using a username/password. It will also allow them to reset the password by implementing the use of Atlas App Services for it and [Universal Links](https://developer.apple.com/ios/universal-links/).

There are different options in order to implement this functionality.

* You can configure an email provider to [send a password reset email</u>](https://www.mongodb.com/docs/atlas/app-services/authentication/email-password/#send-a-password-reset-email)<span class="colour" style="color:rgb(0, 0, 0)">. This option will send an email to the user with the MongoDB logo and a URL that contains the necessary parameters that will be needed in order to reset the password.
* App Services can automatically run a password reset function. You can implement it guided by our [password reset documentation](https://www.mongodb.com/docs/atlas/app-services/authentication/email-password/#run-a-password-reset-function). App Services passes this function unique confirmation tokens and data about the user. Use these values to define custom logic to reset a user's password.
* If you decide to use a custom password reset email from a specific domain by using an external service, when the email for the reset password is received, you will get a URL that will be valid for 30 minutes, and you will need to implement [Universal Links](https://developer.apple.com/documentation/xcode/allowing-apps-and-websites-to-link-to-your-content?language=objc) for it so your app can detect the URL when the user taps on it and extract the tokens from it.
* You can define a function for App Services to run when you callResetPasswordFunction() in the SDK. App Services passes this function with unique confirmation tokens.

For this tutorial, we are going to use the first option. When it gets triggered, it will send the user an email and a valid URL for 30 minutes. But please be aware that we do not recommend using this option in production. Confirmation emails are not currently customizable beyond the base URL and subject line. In particular, they always come from a mongodb.com email address. For production apps, we recommend using a confirmation function. You can check [how to run a confirmation function in our MongoDB documentation](https://www.mongodb.com/docs/atlas/app-services/authentication/email-password/#run-a-confirmation-function).

## Configuring authentication

First, you’ll need to create your Atlas App Services App. I recommend [following our documentation](https://www.mongodb.com/docs/atlas/app-services/manage-apps/create/create-with-ui/#create-an-app-with-the-app-services-ui) and this will provide you with the base to start configuring your app.

After creating your app, go to the **Atlas App Services** tab, click on your app, and go to **Data Access → Authentication** on the sidebar.

In the Authentication Providers section, enable the provider **Email/Password**. In the configuration window that will get displayed after, we will focus on the **Password Reset Method** part.

![Authentication section - Atlas App Services](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/authentication_section_atlas_app_services_fdfd671e78.png)

For this example, the user confirmation will be done automatically. But make sure that the **Send a password reset email** option is enabled.

![Authentication Configuration - Atlas App Services](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/authentication_configuration_atlas_app_services_ad44f6abff.png)

One important thing to note is that **you won’t be able to save and deploy these changes unless the URL section is completed**. Therefore, we’ll use a temporary URL and we’ll change it later to the final one.

![password reset in authentication section ](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/password_reset_url_925424c75b.png)

Click on the Save Draft button and your changes will be deployed.

### Implementing the reset password functionality

Before starting to write the related code, please make sure that you have followed this [quick start guide](https://www.mongodb.com/docs/realm/sdk/swift/quick-start/#quick-start---swift-sdk) to make sure that you can use our Swift SDK.

The logic of implementing reset password will be implemented in the `MainViewController.swift` file. In it, we have an IBAction called `resetPasswordButtonTapped`, and inside we are going to write the following code:

``` swift
 
    @IBAction func resetPasswordButtonTapped(_ sender: Any) {
        let email = app.currentUser?.profile.email ?? ""
        let client = app.emailPasswordAuth
 
        client.sendResetPasswordEmail(email) { (error) in
            DispatchQueue.main.async {
                guard error == nil else {
                    print("Reset password email not sent: \(error!.localizedDescription)")
                    return
                }
 
                print("Password reset email sent to the following address: \(email)")
 
	let alert = UIAlertController(title: "Reset Password", message: "Please check your inbox to continue the process", preferredStyle: UIAlertController.Style.alert)
                alert.addAction(UIAlertAction(title: "OK", style: UIAlertAction.Style.default, handler: nil))
                self.present(alert, animated: true, completion: nil)
 
            }
        }
    }
```

By making a call to `client.sendResetPasswordEmail` with the user's email, App Services sends an email to the user that contains a unique URL. The user must visit this URL within 30 minutes to confirm the reset.

Now we have the first part of the functionality implemented. But if we try to tap on the button, it won’t work as expected. We must go back to our Atlas App Services App, to the Authentication configuration.

![password reset in authentication section ](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/password_reset_url_925424c75b.png)

The URL that we define here will be the one that will be sent in the email to the user. You can use your own from your own website hosted on a different server but if you don’t, don’t worry! Atlas App Services provides [Static Hosting](https://www.mongodb.com/docs/atlas/app-services/hosting/#static-hosting). You can use hosting to store individual pieces of content or to upload and serve your entire client application, but please note that in order to enable static hosting, **you must have a paid tier** (i.e M2 or higher).

## Configuring hosting

Go to the Hosting section of your Atlas App Services app and click on the Enable Hosting button. App Services will begin provisioning hosting for your application. It may take a few minutes for App Services to finish provisioning hosting for your application once you've enabled it.

![hosting section in Atlas App Services](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/hosting_section_atlas_app_services_fa7ca5fcf0.png)

The resource path that you see in the screenshot above is the URL that will be used to redirect the user to our website so they can continue the process of resetting their password.

Now we have to go back to the Authentication section in your Atlas App Services app and tap on the Edit button for Email/Password. We will focus our attention on the lower area of the window.

![authentication configuration, password reset](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/resetting_password_3b9333daa7.png)

In the Password Reset URL we are going to add our hosted URL. This will create the link between your back end and the email that gets sent to the user. 

The base of the URL is included in every password reset email. App Services appends a unique `token` and `tokenId` to this URL. These serve as query parameters to create a unique link for every password reset. To reset the user's password, extract these query parameters from the user's unique URL.

In order to extract these query parameters and use them in our client application, we can use Universal Links.

## Universal links

According to Apple, when adding [universal links](https://developer.apple.com/library/archive/documentation/General/Conceptual/AppSearch/UniversalLinks.html) support to your app, your users can tap a link to your website and get seamlessly redirected to your installed app without going through Safari. But if the app isn’t installed, then tapping a link to your website will open it in Safari. 

**Note**: Be aware that in order to add the universal links entitlement to your Xcode project, you need to have an Apple Developer subscription. 

#1 Add the **Associated Domains** entitlement to the **Signing & Capabilities** section of your project on Xcode and add to the domains the URL from your hosted website following the syntax: `>applinks:<url>`

![Associated domains, Xcode project](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/associated_domains_xcode_project_94c5960cce.png)

#2 You now need to create an `apple-app-site-association` file that contains JSON data about the URL that the app will handle. In my case, this is the structure of my file. The value of the `appID` key is the team ID or app ID prefix, followed by the bundle ID.

``` json
{
    "applinks": {
        "apps": [],
        "details": [
            {
                "appID": "QX5CR2FTN2.io.realm.marcabrera.aries",
                "paths": [ "*" ]
            }
        ]
    }
}
```

#3 Upload the file to your HTTPS web server. In my case, I’ll update it to my Atlas App Services hosted website. Therefore, now I have two files including `index.html`.

![hosting section, Atlas App Services](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/hosting_section_2_5feddbca85.png)

### Code

You need to implement the code that will handle the functionality when your user taps on the link from the received email.

Go to the `SceneDelegate.swift` file of your Xcode project, and on the continue() delegate method, add the following code:

``` swift
   func scene(_ scene: UIScene, continue userActivity: NSUserActivity) {
 
        if let url = userActivity.webpageURL {
            handleUniversalLinks(url)
        }
    }
```

``` swift
 func scene(_ scene: UIScene, willConnectTo session: UISceneSession, options connectionOptions: UIScene.ConnectionOptions)  {
 
        guard let _ = (scene as? UIWindowScene) else { return }
 
        // UNIVERSAL LINKS HANDLING
 
        guard let userActivity = connectionOptions.userActivities.first, userActivity.activityType == NSUserActivityTypeBrowsingWeb,
                let incomingURL = userActivity.webpageURL else {
            // If we don't get a link (meaning it's not handling the reset password flow then we have to check if user is logged in)
            if let _ = app.currentUser {
                // We make sure that the session is being kept active for users that have previously logged in
                let storyboard = UIStoryboard(name: "Main", bundle: nil)
                let tabBarController = storyboard.instantiateViewController(identifier: "TabBarController")
                let navigationController = UINavigationController(rootViewController: tabBarController)
 
            }
            return
        }
 
        handleUniversalLinks(incomingURL)
    }
```

``` swift
   private func handleUniversalLinks(_ url: URL) {
        // We get the token and tokenId URL parameters, they're necessary in order to reset password
        let token = url.valueOf("token")
        let tokenId = url.valueOf("tokenId")
 
        let storyboard = UIStoryboard(name: "Main", bundle: nil)
        let resetPasswordViewController = storyboard.instantiateViewController(identifier: "ResetPasswordViewController") as! ResetPasswordViewController
 
        resetPasswordViewController.token = token
        resetPasswordViewController.tokenId = tokenId
 
    }
```

The `handleUniversalLinks()` private method will extract the `token` and `tokenId` parameters that we need to use in order to reset the password. We will store them as properties on the `ResetPassword` view controller.

Also note that we use the function `url.valueOf(“token”)`, which is an extension that I have created in order to extract the query parameters that match the string that we pass as an argument and store its value in the `token` variable.

``` swift
extension URL {
    // Function that returns a specific query parameter from the URL
    func valueOf(_ queryParameterName: String) -> String? {
        guard let url = URLComponents(string: self.absoluteString) else { return nil }
 
        return url.queryItems?.first(where: {$0.name == queryParameterName})?.value
    }
}
```

**Note**: This functionality won’t work if the user decides to terminate the app and it’s not in the foreground. For that, we need to implement similar functionality on the `willConnectTo()` delegate method.

``` swift
    func scene(_ scene: UIScene, willConnectTo session: UISceneSession, options connectionOptions: UIScene.ConnectionOptions) {
        // Use this method to optionally configure and attach the UIWindow `window` to the provided UIWindowScene `scene`.
        // If using a storyboard, the `window` property will automatically be initialized and attached to the scene.
        // This delegate does not imply the connecting scene or session are new (see `application:configurationForConnectingSceneSession` instead).
 
        guard let _ = (scene as? UIWindowScene) else { return }
 
        // UNIVERSAL LINKS HANDLING
 
        guard let userActivity = connectionOptions.userActivities.first, userActivity.activityType == NSUserActivityTypeBrowsingWeb,
                let incomingURL = userActivity.webpageURL else {
            // If we don't get a link (meaning it's not handling the reset password flow then we have to check if user is logged in)
            if let _ = app.currentUser {
                // We make sure that the session is being kept active for users that have previously logged in
	    let storyboard = UIStoryboard(name: "Main", bundle: nil)
                let mainVC = storyboard.instantiateViewController(identifier: "MainViewController")
 
                window?.rootViewController = mainVC
                window?.makeKeyAndVisible()
            }
            return
        }
 
        handleUniversalLinks(incomingURL)
    }
```

## Reset password

This view controller contains a text field that will capture the new password that the user wants to set up, and when the Reset Password button is tapped, the `resetPassword` function will get triggered and it will make a call to the Client SDK’s resetPassword() function. If there are no errors, a success alert will be displayed on the app. Otherwise, an error message will be displayed.

``` swift
    private func resetPassword() {
 
        let password = confirmPasswordTextField.text ?? ""
 
        app.emailPasswordAuth.resetPassword(to: password, token: token ?? "", tokenId: tokenId ?? "") { (error) in
            DispatchQueue.main.async {
                self.confirmButton.hideLoading()
                guard error == nil else {
                    print("Failed to reset password: \(error!.localizedDescription)")
                    self.presentErrorAlert(message: "There was an error resetting the password")
                    return
                }
                print("Successfully reset password")
                self.presentSuccessAlert()
            }
        }
    }
```

## Repository

The code for this project can be found in the [Github repository](https://github.com/mongodb-developer/Reset-Password-Swift). 

I hope you found this tutorial useful and that it will solve any doubts you may have! I encourage you to explore our [Realm Swift SDK documentation](https://www.mongodb.com/docs/realm/sdk/swift/) so you can check all the features and advantages that Realm can offer you while developing your iOS apps. We also have a lot of resources for you to dive in and learn how to implement them.

Learn how to easily implement reset password functionality thanks to Atlas App Services on your iOS apps.

Authentication for Your iOS Apps with Atlas App Services

Mobile device authentication serves as the crucial first line of defense against potential intruders who aim to exploit personal information, financial data, or private details. As our mobile phones store a wealth of sensitive information, it is imperative to prioritize security while developing apps that ensure user safety. 

Apple sign-in is a powerful solution that places user privacy at the forefront by implementing private email relay functionality. This enables users to shield their email addresses, granting them greater control over their data. Combining this with Atlas App Services provides developers with a streamlined and secure authentication experience. It also simplifies app development, service integration, and data connectivity, eliminating operational overhead. 

In the following tutorial, I will show you how with only a few steps and a little code, you can bring this seamless implementation to your iOS apps! If you also want to follow along and check the code that I’ll be explaining in this article, you can find it in the [Github repository](https://github.com/mongodb-developer/apple-sign-in-swift-sdk-example). 

## Context

This sample application consists of an iOS app with a “Sign in with Apple” button, where when the user taps on it, it will prompt the authentication native sheet that will allow the user to choose to sign in to your app hiding or showing their email address. Once the sign-up process is completed, the sign-in process gets handled by the Authentication API by Apple. 

## Prerequisites

Since this tutorial’s main focus is on the code implementation with Apple sign-in, a few previous steps are required for it. 

- Have the latest stable version of [Xcode](https://developer.apple.com/xcode/resources/) installed on your macOS computer, and make sure that the OS is compatible with the version. 
- Have a setup of a valid Apple Developer Account and configure your App ID. You can follow the official [Apple documentation](https://developer.apple.com/help/account/configure-app-capabilities/about-sign-in-with-apple).
- Have the Apple Sign-In Capability added to your project. Check out the official [Apple sign-in official resources](https://developer.apple.com/sign-in-with-apple/resources/).
- Have the Realm Swift SDK installed on your project and an Atlas App Services app linked to your cluster. Please follow the steps in our [Realm Swift SDK documentation](https://www.mongodb.com/docs/realm/sdk/swift/) on how to [create an Alas App Services app](https://www.mongodb.com/docs/atlas/app-services/apps/create/#create-an-app).

## Configuring Apple provider on Atlas App Services

In order to follow this tutorial, you will need to have an **Atlas App Services app** created. If not, please follow the steps in our [MongoDB documentation](https://www.mongodb.com/docs/atlas/app-services/apps/create/). It’s quite easy to set it up! 

First, in your Atlas App Services app, go to **Data Access** -> **Authentication** on the sidebar. 

In the **Authentication Providers** section, enable the **Apple** provider when tapping on the **Edit** button. You’ll see a screen like the one in the screenshot below: 

![Authentication Providers section - Atlas App Services](https://images.contentstack.io/v3/assets/blt39790b633ee0d5a7/bltd55983ef4e874447/64a83e15873fa3768802f576/image3.png)

You will have now to fill the corresponding fields with the following information: 

- **Client ID:** Enter your application’s Bundle ID for the App Services Client ID.
- **Client Secret:** Choose or create a new [secret](https://www.mongodb.com/docs/atlas/app-services/values-and-secrets/#secret), which is stored in Atlas App Services' back end.
- **Redirect URIs:** You will have to use a URI in order to redirect the authentication. You can use your own custom domain, but if you have a paid tier cluster in Atlas, you can benefit from our [Hosting Service](https://www.mongodb.com/docs/atlas/app-services/hosting/#host-files)!

![Authentication Provider completed - Atlas App Services](https://images.contentstack.io/v3/assets/blt39790b633ee0d5a7/blt6f35f8363b204bee/64a83e5c1f8d5a5ef9587ae8/image2.png)

Click on the “Save Draft” button and your changes will be deployed. 

### Implementing the Apple sign-in authentication functionality

Now, before continuing with this section, please make sure that you have followed our [quick start guide](https://www.mongodb.com/docs/realm/sdk/swift/quick-start/#quick-start---swift-sdk) to make sure that you have our [Realm Swift SDK installed](https://www.mongodb.com/docs/realm/sdk/swift/install/). Moving on to the fun part, it’s time to code!

This is a pretty simple UIKit project, where *LoginViewController.swift* will implement the authentication functionality of Apple sign-in, and if the authenticated user is valid, then a segue will transition to *WelcomeViewController.swift*.

On top of the view controller code, make sure that you import both the AuthenticationServices and RealmSwift frameworks so you have access to their methods. In your Storyboard, add a UIButton of type *ASAuthorizationAppleIDButton* to the *LoginViewController* and link it to its corresponding Swift file.

In the *viewDidLoad()* function of *LoginViewController*, we are going to call *setupAppleSignInButton()*, which is a private function that lays out the Apple sign-in button, provided by the AuthenticationServices API. Here is the code of the functionality.

```swift
// Mark: - IBOutlets
@IBOutlet weak var appleSignInButton: ASAuthorizationAppleIDButton!

// MARK: - View Lifecycle
override func viewDidLoad() {
    super.viewDidLoad()
    setupAppleSignInButton()
}


// MARK: - Private helper
private func setupAppleSignInButton() {
    appleSignInButton.addTarget(self, action: #selector(handleAppleIdRequest), for: .touchUpInside)
    appleSignInButton.cornerRadius = 10
}
```

The private function adds a target to the *appleSignInButton* and gives it a radius of 10 to its corners. The screenshot below shows how the button is laid out in the testing device.

![Device screenshot with button layout](https://images.contentstack.io/v3/assets/blt39790b633ee0d5a7/blt30eca8c08864f3f1/64a83e95873fa356be02f582/image1.png)

Now, moving to *handleAppleIdRequest*, here is the implementation for it: 

```swift
@objc func handleAppleIdRequest() {
    let appleIDProvider = ASAuthorizationAppleIDProvider()
    let request = appleIDProvider.createRequest()
    request.requestedScopes = [.fullName, .email]
    let authorizationController = ASAuthorizationController(authorizationRequests: [request])
    authorizationController.delegate = self
    authorizationController.performRequests()
}
```

This function is a method that handles the initialization of Apple ID authorization using *ASAuthorizationAppleIDProvider* and *ASAuthorizationController* classes. Here is a breakdown of what the function does: 

1. It creates an instance of *ASAuthorizationAppleIDProvider*, which is responsible for generating requests to authenticate users based on their Apple ID.
2. Using the *appleIDProvider* instance, it creates an authorization request when calling *createRequest()*.
3. The request is used to configure the specific data that the app needs to access from the user’s Apple ID. In this case, we are requesting fullName and email.
4. We create an instance of *ASAuthorizationController* that will manage the authorization requests and will also handle any user interactions related to the Apple ID authentication.
5. The *authorizationController* has to set its delegate to self, as the current object will have to conform to the *ASAuthorizationControllerDelegate* protocol.
6. Finally, the specified authorization flows are performed by calling *performRequests()*. This method triggers the system to present the Apple ID login interface to the user. 

As we just mentioned, the view controller has to conform to the *ASAuthorizationControllerDelegate*. To do that, I created an extension of *LoginViewController*, where the implementation of the *didCompleteWithAuthorization* delegate method is where we will handle the successful authentication with the Swift Realm SDK.

```  swift
func authorizationController(controller: ASAuthorizationController, didCompleteWithAuthorization authorization: ASAuthorization) {
    if let appleIDCredential = authorization.credential as? ASAuthorizationAppleIDCredential {
        let userIdentifier = appleIDCredential.user
        let fullName = appleIDCredential.fullName
        let email = appleIDCredential.email


        guard let identityToken = appleIDCredential.identityToken else {
            return
        }
        let decodedToken = String(decoding: identityToken, as: UTF8.self)
        print(decodedToken)

        realmSignIn(appleToken: decodedToken)
    }
}
```

To resume it in a few lines, this code retrieves the necessary user information from the Apple ID credential if the credentials of the user are successful. We also obtain the *identityToken*, which is the vital piece of information that is needed to use it on the Atlas App Services authentication. 

However, note that this token **has to be decoded** in order to be used on Atlas App Services, and for that, you can use the *String(decoding:, as:)* method. 

Once the token is decoded, it is a JWT that contains claims about the user signed by Apple Authentication Service. Then the *realmSignIn()* private method is called and the decoded token is passed as a parameter so the authentication can be handled. 

```swift
private func realmSignIn(appleToken: String) {
    let credentials = Credentials.apple(idToken: appleToken)
    app.login(credentials: credentials) { (result) in
        switch result {
        case .failure(let error):
            print("Realm Login failed: \(error.localizedDescription)")

        case .success(_):
            DispatchQueue.main.async {
                print("Successful Login")
                self.performSegue(withIdentifier: "goToWelcomeViewController", sender: nil)
            }
        }
    }
}
```

The *realmSignIn()* private function handles the login into Atlas App Services. This function will allow you to authenticate your users that will be connected to your app without any additional hassle. First, the credentials are generated by *Credentials.apple(idToken:)*, where the decoded Apple token is passed as a parameter. 

If the login is successful, then the code performs a segue and goes to the main screen of the project, *WelcomeViewController*. If it fails, then it will print an error message. Of course, feel free to adapt this error to whatever suits you better for your use case (i.e., an alert message). 

Another interesting delegate method in terms of error handling is the *didCompleteWithError()* delegate function, which will get triggered if there is an error during the Apple ID authentication. You can use this one to provide some feedback to the user and improve the UX of your application.

## Important note

One of the biggest perks of Apple sign-in authentication, as it was mentioned earlier, is the flexibility it gives to the user regarding what gets shared with your app. This means that if the user decides to hide their email address and not to share their full name as the code was requested earlier through the *requestedScopes* definition, you will receive **an empty string** in the response. In the case of the email address, it will be a *nil* value. 

If your iOS application has a use case where you want to establish communication with your users, you will need to implement [communication using Apple's private email relay service](https://developer.apple.com/documentation/sign_in_with_apple/sign_in_with_apple_js/communicating_using_the_private_email_relay_service). You should avoid asking the user for their email in other parts of the app too, as it could potentially create a rejection on the App Store review.

## Repository

The code for this project can be found in the [Github repository](https://github.com/marcabreracast/apple-sign-in). 

I hope you found this tutorial helpful. I encourage you to explore our [Realm Swift SDK documentation](https://www.mongodb.com/docs/realm/sdk/swift/) to discover all the benefits that it can offer to you when building iOS apps. We have plenty of resources available to help you learn and implement these features. So go ahead, dive in, and see what Atlas App Services has in store for your app development journey. 

If you have any questions or comments don’t hesitate to head over to our [Community Forums](https://www.mongodb.com/community/forums/) to continue the conversation. Happy coding!

Learn how to implement Apple sign-in within your own iOS mobile applications using Swift and MongoDB Atlas App Services.

Mar Cabrera

Content by Mar Cabrera

Authentication for Your iOS Apps with Atlas App Services

Authentication for Your iOS Apps with Apple Sign-in and Atlas App Services