Android toolkit for Auth0 API
Java
Latest commit ac425c6 Jan 2, 2017 @hzalaz hzalaz committed on GitHub Update README.md
[skip ci]

README.md

Auth0.Android

CI Status Coverage Status License Maven Central Bintray

Android java toolkit for Auth0 API

Requirements

Android API version 15 or newer

Installation

Gradle

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.4.0'
}

Permissions

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

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

Usage

First create an instance of Auth0 with your client information

Auth0 account = new Auth0("{YOUR_CLIENT_ID}", "{YOUR_DOMAIN}");

Alternatively, you can save your client 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_DOMAIN</string>
</resources>

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

Auth0 account = new Auth0(context);

Authentication API

The client provides methods to authenticate the user against Auth0 server.

Create a new instance by passing the account:

AuthenticationAPIClient authentication = new AuthenticationAPIClient(account);

Login with database connection

authentication
    .login("info@auth0.com", "a secret password", "my-database-connection")
    .start(new BaseCallback<Credentials>() {
        @Override
        public void onSuccess(Credentials payload) {
            //Logged in!
        }

        @Override
        public void onFailure(AuthenticationException error) {
            //Error!
        }
    });

The default scope used is openid

Passwordless Login

Step 1: Request the code

authentication
    .passwordlessWithEmail("info@auth0.com", PasswordlessType.CODE, "my-passwordless-connection")
    .start(new BaseCallback<Credentials>() {
        @Override
        public void onSuccess(Void payload) {
            //Code sent!
        }

        @Override
        public void onFailure(AuthenticationException error) {
            //Error!
        }
    });

The default scope used is openid

Step 2: Input the code

authentication
    .loginWithEmail("info@auth0.com", "123456", "my-passwordless-connection")
    .start(new BaseCallback<Credentials>() {
        @Override
        public void onSuccess(Credentials payload) {
            //Logged in!
        }

        @Override
        public void onFailure(AuthenticationException error) {
            //Error!
        }
    });

Sign Up with database connection

authentication
    .signUp("info@auth0.com", "a secret password", "my-database-connection")
    .start(new BaseCallback<Credentials>() {
        @Override
        public void onSuccess(Credentials payload) {
            //Signed Up & Logged in!
        }

        @Override
        public void onFailure(AuthenticationException error) {
            //Error!
        }
    });

Get user information

authentication
   .userInfo("user access_token")
   .start(new BaseCallback<Credentials>() {
       @Override
       public void onSuccess(UserProfile payload) {
           //Got the profile!
       }

       @Override
       public void onFailure(AuthenticationException error) {
           //Error!
       }
   });

Management API (Users)

The client provides methods to link and unlink users account.

Create a new instance by passing the account and the primary user token:

Auth0 account = new Auth0("client id", "domain");
UsersAPIClient users = new UsersAPIClient(account, "api token");

Link users

users
    .link("primary user id", "secondary user token")
    .start(new BaseCallback<List<UserIdentity>>() {
        @Override
        public void onSuccess(List<UserIdentity> payload) {
            //Got the updated identities! Accounts linked.
        }

        @Override
        public void onFailure(Auth0Exception error) {
            //Error!
        }
    });

Unlink users

users
    .unlink("primary user id", "secondary user id", "secondary provider")
    .start(new BaseCallback<List<UserIdentity>>() {
        @Override
        public void onSuccess(List<UserIdentity> payload) {
            //Got the updated identities! Accounts linked.
        }

        @Override
        public void onFailure(Auth0Exception error) {
            //Error!
        }
    });

Update User Metadata

Map<String, Object> metadata = new HashMap<>();
metadata.put("name", Arrays.asList("My", "Name", "Is"));
metadata.put("phoneNumber", "1234567890");

users
    .updateMetadata("user id", metadata)
    .start(new BaseCallback<UserProfile, ManagementException>() {
        @Override
        public void onSuccess(UserProfile payload) {
            //Metadata updated
        }

        @Override
        public void onFailure(ManagementException error) {
            //Error!
        }
    });

In all the cases, the User ID parameter is the unique identifier of the auth0 account instance. i.e. in google-oauth2|123456789081523216417 it would be the part after the '|' pipe: 123456789081523216417.

Web-based Auth

First go to Auth0 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

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

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

Also register the intent filters inside your activity's tag, so you can receive the call in your activity. Note that you will have to specify the callback url inside the data tag.

    <application android:theme="@style/AppTheme">

        <!-- ... -->

        <activity
            android:name="com.mycompany.MainActivity"
            android:theme="@style/MyAppTheme"
            android:launchMode="singleTask">

            <intent-filter android:autoVerify="true">
                <action android:name="android.intent.action.VIEW" />

                <category android:name="android.intent.category.DEFAULT" />
                <category android:name="android.intent.category.BROWSABLE" />

                <data
                    android:host="{YOUR_AUTH0_DOMAIN}"
                    android:pathPrefix="/android/{YOUR_APP_PACKAGE_NAME}/callback"
                    android:scheme="https" />
            </intent-filter>

        </activity>

        <!-- ... -->

    </application>

Make sure the Activity's launchMode is declared as "singleTask" or the result won't come back after the authentication.

When you launch the WebAuthProvider you'll expect a result back. To capture the response override the onNewIntent method and call WebAuthProvider.resume() with the received parameters:

public class MyActivity extends Activity {

    @Override
    protected void onNewIntent(Intent intent) {
        if (WebAuthProvider.resume(intent)) {
            return;
        }
        super.onNewIntent(intent);
    }
}
A note about App Deep Linking:

Currently, the default scheme used in the Callback Uri is https. This works best for Android API 23 or newer if you're using Android App Links, but in previous Android versions this may show the intent chooser dialog prompting the user to chose either your application or the browser. You can change this behaviour by using a custom unique scheme, so that the OS opens directly the link with your app.

  1. Update the intent filter in the Android Manifest and change the custom scheme.
  2. Update the allowed callback urls in your Auth0 Dashboard client's settings.
  3. Call withScheme() passing the scheme you want to use.
WebAuthProvider.init(account)
                .withScheme("myapp")
                .start(MainActivity.this, authCallback);

Authenticate with any Auth0 connection

WebAuthProvider.init(account)
                .withConnection("twitter")
                .start(MainActivity.this, authCallback);

Use Code grant with PKCE

Before you can use Code Grant in Android, make sure to go to your client's section in dashboard and check in the Settings that Client Type is Native.

WebAuthProvider.init(account)
                .useCodeGrant(true)
                .start(MainActivity.this, authCallback);

Specify scope

WebAuthProvider.init(account)
                .withScope("user openid")
                .start(MainActivity.this, authCallback);

The default scope used is openid

Specify Connection scope

WebAuthProvider.init(account)
                .withConnectionScope("email", "profile", "calendar:read")
                .start(MainActivity.this, authCallback);

Authenticate with Auth0 hosted login page

Simply don't specify any custom connection and the Lock web widget will show.

WebAuthProvider.init(account)
                .start(MainActivity.this, authCallback);

FAQ

  • Why is the Android Lint error 'InvalidPackage' considered a warning?

When building the project with build, an error appeared regarding an invalid package on the okio dependency. This snippet is in the build.gradle file so that the build runs fine:

android {
    //...
    lintOptions {
       warning 'InvalidPackage'
    }
}

ref: https://github.com/square/okio/issues/58#issuecomment-72672263

Proguard

The rules should be applied automatically if your application is using minifyEnabled = true. If you want to include them manually check the proguard directory. By default you should at least use the following files:

  • proguard-okio.pro
  • proguard-gson.pro

What is Auth0?

Auth0 helps you to:

  • Add authentication with multiple authentication sources, either social like Google, Facebook, Microsoft Account, LinkedIn, GitHub, Twitter, Box, Salesforce, amont others, or enterprise identity systems like Windows Azure AD, Google Apps, Active Directory, ADFS or any SAML Identity Provider.
  • Add authentication through more traditional username/password databases.
  • Add support for linking different user accounts with the same user.
  • Support for generating signed Json Web Tokens to call your APIs and flow the user identity securely.
  • Analytics of how, when and where users are logging in.
  • Pull data from other sources and add it to the user profile, through JavaScript rules.

Create a free Auth0 Account

  1. Go to Auth0 and click Sign Up.
  2. Use Google, GitHub or Microsoft Account to login.

Issue Reporting

If you have found a bug or if you have a feature request, please report them at this repository issues section. Please do not report security vulnerabilities on the public GitHub issue tracker. The Responsible Disclosure Program details the procedure for disclosing security issues.

Author

Auth0

License

This project is licensed under the MIT license. See the LICENSE file for more info.