Add authentication to your Apache Cordova app

Article
05/05/2021

Note

This product is retired. For a replacement for projects using .NET 8 or later, see the Community Toolkit Datasync library.

In this tutorial, you add Microsoft authentication to the quickstart project using Microsoft Entra ID. Before completing this tutorial, ensure you've created the project and enabled offline sync.

Configure your backend for authentication

To configure your backend for authentication, you must:

Create an app registration.
Configure Azure App Service Authentication and Authorization.
Add your app to the Allowed External Redirect URLs.

During this tutorial, we'll configure your app to use Microsoft authentication. A Microsoft Entra tenant has been configured automatically in your Azure subscription. You can use Microsoft Entra ID to configure Microsoft authentication.

You need the backend URL of the Azure Mobile Apps service that was provided when you provisioned the service.

Create an app registration

Sign in to the Azure portal.
Select Microsoft Entra ID > App registrations > New registration.
In the Register an application page, enter zumoquickstart in the Name field.
Under Supported account types, select Accounts in any organizational directory (Any Microsoft Entra directory - multitenant) and personal Microsoft accounts (e.g. Skype, Xbox).
In Redirect URI, select Web and type <backend-url>/.auth/login/aad/callback. For example, if your backend URL is https://zumo-abcd1234.azurewebsites.net, you would enter https://zumo-abcd1234.azurewebsites.net/.auth/login/aad/callback.
Press the Register button at the bottom of the form.
Copy the Application (client) ID.
From the left pane, select Certificates & secrets > New client secret.
Enter a suitable description, select a validity duration, then select Add.
Copy the secret on the Certificates & secrets page. The value isn't displayed again.
Select Authentication.
Under Implicit grant and hybrid flows, enable ID tokens.
Press Save at the top of the page.

Important

The client secret value (password) is an important security credential. Don't share the password with anyone or distribute it within a client application.

Configure Azure App Service Authentication and Authorization

In the Azure portal, select All Resources, then your App Service.
Select Settings > Authentication.
Press Add identity provider.
Select Microsoft as the identity provider.
- For App registration type, select Provide the details of an existing app registration.
- Paste the values you copied earlier into the Application (client) ID and Client secret boxes.
- For Issuer URL, enter https://login.microsoftonline.com/9188040d-6c67-4c5b-b112-36a304b66dad/v2.0. This URL is the "magic tenant url" for Microsoft logins.
- For Restrict access, select Require authentication.
- For Unauthenticated request, select HTTP 401 Unauthorized.
Press Add.
Once the authentication screen returns, press Edit next to Authentication settings.
In the Allowed external redirect URLs box, enter zumoquickstart://easyauth.callback.
Press Save.

Step 10 requires that all users are authenticated before accessing your backend. You can provide fine-grained controls by adding code to your backend.

DID YOU KNOW? You can also allow users with organizational accounts in Microsoft Entra ID, Facebook, Google, Twitter, or any OpenID Connect compatible provider. Follow the instructions in the Azure App Service documentation.

Test that authentication is being requested

Run the app using cordova run android
Verify that an unhandled exception with a status code of 401 (Unauthorized) is raised after the app starts.

Add authentication to the app

To add authentication via the built-in provider, you must:

Add the authentication provider to the list of known good sources.
Call the authentication provider before accessing data.

Update the Content Security Policy

Each Apache Cordova app declares their known good sources via a Content-Security-Policy header. Each supported provider has an OAuth host that needs to be added:

Provider	SDK Provider Name	OAuth Host
Microsoft Entra ID	Microsoft Entra ID	`https://login.microsoftonline.com`
Facebook	facebook	`https://www.facebook.com`
Google	google	`https://accounts.google.com`
Twitter	twitter	`https://api.twitter.com`

Edit www/index.html; add the OAuth host for Microsoft Entra ID as follows:

<meta http-equiv="Content-Security-Policy" content="
    default-src 'self' 
    data: gap: https://login.microsoftonline.com https://ZUMOAPPNAME.azurewebsites.net; 
    style-src 'self'; media-src *;">

The content is multiple lines for readability. Place all code on the same line.

<meta http-equiv="Content-Security-Policy" content="default-src 'self' data: gap: https://login.microsoftonline.com https://ZUMOAPPNAME.azurewebsites.net; style-src 'self'; media-src *;">

You have already replaced ZUMOAPPNAME with the name of your app.

Call the authentication provider

Edit www/js/index.js. Replace the setup() method with the following code:

function setup() {
    client.login('aad').then(function () {
        // ORIGINAL CONTENTS OF FUNCTION
        todoTable = client.getSyncTable('todoitem');
        refreshDisplay();
        addItemEl.addEventListener('submit', addItemHandler);
        refreshButtonEl.addEventListener('click', refreshDisplay);
        // END OF ORIGINAL CONTENTS OF FUNCTION
    });
}

Test the app

Run the following command:

cordova run android

Once the initial startup is complete, you'll be prompted to sign in with your Microsoft credentials. Once complete, you can add and delete items from the list.

Tip

If the emulator does not automatically start, open Android Studio, then select Configure > AVD Manager. This will allow you to start the device manually. If you run adb devices -l, you should see your selected emulated device.

Deleting the resources

Now you've completed the quickstart tutorial, you can delete the resources with az group delete -n zumo-quickstart. You can also delete the global app registration used for authentication through the portal.

Next steps

Take a look at the HOW TO sections:

You can also do a Quick Start for another platform using the same service:

Share via