Developer Docs - Mobile Docs - Using Auth0

Using Auth0 for your Rock mobile application login.

M v5.0 C v15.1

What is Auth0?

Auth0 is a cloud-based identity and access management (IAM) platform that provides developers and organizations with secure and easy-to-use solutions for authenticating and authorizing user access to applications. Auth0 offers a range of authentication methods such as username and password, social identity providers, multi-factor authentication, and more.

With Auth0, developers can add authentication and authorization capabilities to their applications quickly and easily. Check out their website to learn more about the services they offer.

To test Auth0, set up your shell through App Factory and mention Auth0 in the notes. The team will send you everything you need from there.

Configuration

To ensure Auth0 works seamlessly in Rock Mobile, follow this step-by-step guide to configure a new Auth0 application for Rock Mobile. In this guide, we will:

Rock requires a First Name, Last Name and either a valid Phone Number or Email to process external authentication. You should take steps to ensure that those specific data points are always returned from Auth0 authentication.  

Creating an Auth0 Application

To begin, let's create the Auth0 application that will handle our Rock Mobile logins. You should only need one application for all of your mobile applications.

You cannot use the same application you've configured for Rock Web, since it requires settings specific to mobile authentication.

2.  Select Native as the type of application.  

5. In the Allowed Callback URLs of the Auth0 application, add an entry in the following format. If your package name and bundle identifier differ, you will require two URLs, one for each.  

This value is provided by App Factory when they create your shell.

://auth0/callback

Great! We should now have all of the basic configuration finished.

Getting Additional Data for Rock

To ensure all of the necessary data for Rock is obtained, we will:

Configuring Universal Login

additionalSignUpFields: [{
    name: "given_name",
    placeholder: "Enter your first name",
    storage: "root" // IMPORTANT!
    {
    name: "family_name",
    placeholder: "Enter your last name",
    storage: "root" // IMPORTANT!
    },
    {
}]

The entire file looks like this if you want to copy and paste the entire example.

Once finished, paste it into the HTML section into the box. Ensure the preview looks correct.

Pass in Additional Information to your Rock Instance (optional)

This part of the tutorial utilizes an Auth0 Action, which is not part of the free Auth0 plan. If you don't want or need to pass down custom fields such as Gender, feel free to skip to Configuring Rock Mobile.

This is supported through the use of Identity Claims. In short, identity claims are set during your authentication process to provide additional information about an authenticated individual. There are quite a few ways you can set these claims as well, mostly through Auth0 Rules or Actions.

1.  Do you remember the additionalSignUpFields we configured earlier? Let's add some more fields to that.  

 type: "select",
    name: "gender",
    placeholder: "choose your gender",
    options: [
      {value: "1", label: "Male"},
      {value: "2", label: "Female"},
      {value: "0", label: "Unspecified"}
      ],
    },
    {
    name: "phone_number",
    placeholder: "Phone Number"

This will add a Gender picker that reflects the Gender enum, and a basic Phone Number field.

3. In onExecutePostLogin method, configure the identity claims to pass down the proper data, like such:  

exports.onExecutePostLogin = async (event, api) => {
  var userPhoneNumber = event.user.phone_number ?? event.user.user_metadata?.phone_number;
  var userEmail = event.user.email ?? event.user.user_metadata?.email;

  var needsPhoneOrEmail = (userPhoneNumber && userPhoneNumber != "") || (userEmail && userEmail != "");

  if( needsPhoneOrEmail )
  {
    // Invalid login. Here you could customize the login flow to prompt the users for the values, if you wanted to.
  }

  if (event.authorization) {
    // We're careful here to only update the claims if they don't
    // already exist. These can be set previously be social providers, so 
    // if we have a value that's null it's likely it came from there,
    // and the claim is already set (so we don't need to reference metadata).
    if( userPhoneNumber )
    {
      api.idToken.setCustomClaim("phone", userPhoneNumber );
    }
    if( event.user.user_metadata?.gender )
    {
      api.idToken.setCustomClaim("gender", event.user.user_metadata?.gender );
    }
    if( event.user.user_metadata?.given_name )
    {
      api.idToken.setCustomClaim("given_name", event.user.user_metadata?.given_name );
    }
    if(  event.user.user_metadata?.family_name )
    {
      api.idToken.setCustomClaim("family_name", event.user.user_metadata?.family_name );
    }
  }
};

Configuring Rock Mobile

There are a couple of configuration steps for Rock Mobile.

2. Enable Auth Login in the Login block.

Hooray! You should now be fully capable of handling Auth0-related logins.

In the Sign Up tab, you should see all of the additional fields you configured.

When you successfully log in with Auth0 (even for new accounts), a Person in Rock will be matched or created with the values of the Auth0 account.

Supported Claims

The following identity claims are supported and can be utilized to supply additional information about a Rock Person. Since Auth0 configurations can vary, we supply a few different keys that are recognized and translated accordingly.