Auth0.Android

Auth0.Android is a client-side library you can use with your Android app to authenticate users and access Auth0 APIs.

Check out the Auth0.Android repository on GitHub.

Requirements

Android API version 15 or newer is required.

Installation

Auth0.Android is available through Gradle. To install it, simply add the following line to your build.gradle file:

dependencies {
    compile "com.auth0.android:auth0:1.+"
}

You can check for the latest version on the repository Readme, in Maven, or in JCenter.

After adding your Gradle dependency, make sure to remember to sync your project with Gradle files.

Permissions

Open your app's AndroidManifest.xml file and add the following permission.

<uses-permission android:name="android.permission.INTERNET" />

Initialize Auth0

Save your application information in the strings.xml file using the following names:

<resources>
    <string name="com_auth0_client_id">YOUR_CLIENT_ID</string>
    <string name="com_auth0_domain">YOUR_AUTH0_DOMAIN</string>
</resources>

And then create your new Auth0 instance by passing an Android Context:

Auth0 account = new Auth0(context);

OIDC Conformant Mode

It is strongly encouraged that this SDK be used in OIDC Conformant mode. When this mode is enabled, it will force the SDK to use Auth0's current authentication methods and will prevent it from reaching legacy endpoints. By default is false.

Auth0 account = new Auth0("YOUR_CLIENT_ID", "YOUR_AUTH0_DOMAIN");
//Configure the account in OIDC conformant mode
account.setOIDCConformant(true);
//Use the account in the API applications

Passwordless authentication cannot be used with this flag set to true. For more information, please see the OIDC adoption guide.

Authentication via Universal Login

First go to the Dashboard and go to your application's settings. Make sure you have in Allowed Callback URLs a URL with the following format:

https://YOUR_AUTH0_DOMAIN/android/{YOUR_APP_PACKAGE_NAME}/callback

Replace {YOUR_APP_PACKAGE_NAME} with your actual application's package name, available in your app/build.gradle file as the applicationId value.

Then in your app/build.gradle file add the Manifest Placeholders for the Auth0 Domain and the Auth0 Scheme properties which are going to be used internally by the library to register an intent-filter that captures the callback URI.

apply plugin: 'com.android.application'

android {
    compileSdkVersion 25
    defaultConfig {
        applicationId "com.auth0.samples"
        minSdkVersion 15
        targetSdkVersion 25
        //...

        //---> Add the next line
        manifestPlaceholders = [auth0Domain: "@string/com_auth0_domain", auth0Scheme: "https"]
        //<---
    }
    //...
}

It's a good practice to define reusable resources like @string/com_auth0_domain (as done in a previous step with strings.xml) rather than just hard-coding them.

Alternatively, you can declare the RedirectActivity in the AndroidManifest.xml file with your own intent-filter so it overrides the library's default. If you do this then the Manifest Placeholders don't need to be set as long as the activity declaration contains the tools:node="replace" attribute:

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools"
    package="your.app.package">
    <application android:theme="@style/AppTheme">

        <!-- ... -->

        <activity
            android:name="com.auth0.android.provider.RedirectActivity"
            tools:node="replace">
            <intent-filter>
                <action android:name="android.intent.action.VIEW" />
                <category android:name="android.intent.category.DEFAULT" />
                <category android:name="android.intent.category.BROWSABLE" />
                <data
                    android:host="@string/com_auth0_domain"
                    android:pathPrefix="/android/${applicationId}/callback"
                    android:scheme="https" />
            </intent-filter>
        </activity>

        <!-- ... -->

    </application>
</manifest>

Finally, don't forget to add the internet permission:

<uses-permission android:name="android.permission.INTERNET" />

In versions 1.8.0 or lower of Auth0.Android you had to define the intent-filter inside your activity to capture the authentication result in the onNewIntent method and then call WebAuthProvider.resume() with the received data. The intent-filter declaration and resume call are no longer required for versions greater than 1.8.0, as it's now done internally by the library for you.

Now, let's authenticate a user by presenting the universal login page:

WebAuthProvider.init(account)
                .withAudience("https://YOUR_AUTH0_DOMAIN/userinfo")
                .start(this, authCallback);

The authentication result will be delivered to the callback.

To ensure an Open ID Connect compliant response you must either set an audience using withAudience or enable the OIDC Conformant switch in your Auth0 dashboard under Dashboard > Settings > Advanced > OAuth. You can read more about this in the documentation page on how to use new flows.

Using the Authentication API

The Authentication Application provides methods to accomplish authentication and related tasks. Create a new instance by passing in the Auth0 object created in the previous step.

AuthenticationAPIClient authentication = new AuthenticationAPIClient(account);

Get user information

To get the information associated with a given user's access_token, you can call the userInfo endpoint, passing the token.

authentication
  .userInfo("Access Token")
  .start(new BaseCallback<UserProfile, AuthenticationException>() {
      @Override
      public void onSuccess(UserProfile information) {
          //user information received
      }

      @Override
      public void onFailure(AuthenticationException error) {
          //user information request failed
      }
  });

Password Resets

To initiate a password reset for a user, call resetPassword with the user's email address and the database connection name as parameters.

String connectionName = "Username-Password-Authentication";
authentication
  .resetPassword("foo@bar.com", connectionName)
  .start(new AuthenticationCallback<Void>() {
    @Override
    public void onSuccess(Void payload) {
      //Password Reset requested
    }

    @Override
    public void onFailure(AuthenticationException error) {
      //Request failed
    }
  });

Password reset requests will fail on network related errors, but will not fail if the designated email does not exist in the database (for security reasons).

Next Steps

Take a look at the following resources to see how the Auth0.Android SDK can be customized for your needs: