Auth0 is an authentication broker that supports social identity providers as well as enterprise identity providers such as Active Directory, LDAP, Google Apps and Salesforce.
- Integrates your Android app with Auth0.
- Provides a beautiful native UI to log your users in.
- Provides support for Social Providers (Facebook, Twitter, etc.), Enterprise Providers (AD, LDAP, etc.) and Username & Password.
- Passwordless authentication using SMS and Email.
Since June 2017 new Applications no longer have the Password Grant Type* enabled by default. If you are using a Database Connection in Lock then you will need to enable the Password Grant Type, please follow this guide. The reasons for this change are listed in this embedded vs native mobile article.
Android API Level 15+ is required in order to use Lock's UI.
Lock is available both in Maven Central and JCenter. To start using Lock add these lines to your build.gradle
dependencies file:
implementation 'com.auth0.android:lock:2.11.0'
Those using this library from version 2.11.0
and up should start targeting latest android SDK versions, as recommended by Google. Those running into conflicts because of different com.android.support
libraries versions can choose to use latest release 28.0.0
or exclude the ones required by this library and require a different version in their app's build.gradle
file as shown below:
e.g. if choosing an older version such as 25.4.0
apply plugin: 'com.android.application'
android {
//...
}
dependencies {
implementation ('com.auth0.android:lock:2.11.0'){
exclude group: 'com.android.support', module: 'appcompat-v7'
exclude group: 'com.android.support', module: 'customtabs'
exclude group: 'com.android.support', module: 'support-v4'
exclude group: 'com.android.support', module: 'design'
exclude group: 'com.android.support', module: 'recyclerview-v7'
}
implementation 'com.android.support:appcompat-v7:25.4.0'
implementation 'com.android.support:customtabs:25.4.0'
implementation 'com.android.support:support-v4:25.4.0'
implementation 'com.android.support:design:25.4.0'
implementation 'com.android.support:recyclerview-v7:25.4.0'
//...
}
If you haven't done yet, go to Auth0 and create an Account, it's free! Then create a new Application of type Native and add a URL in Allowed Callback URLs with the following format:
https://{YOUR_AUTH0_DOMAIN}/android/{YOUR_APP_PACKAGE_NAME}/callback
The package name value required in the Callback URL can be found in your app's build.gradle
file in the applicationId
property. Both the domain and client id values can be found at the top of your Application's settings. You're going to use them to setup the SDK so let's add them to the strings.xml
file:
<resources>
<string name="com_auth0_client_id">YOUR_AUTH0_CLIENT_ID</string>
<string name="com_auth0_domain">YOUR_AUTH0_DOMAIN</string>
</resources>
In your app/build.gradle file add the Manifest Placeholders for the Auth0 Domain and Auth0 Scheme properties which are going to be used internally by the library to register an intent-filter. You can also add the intent-filter manually to the corresponding Lock activity in the Android Manifest as described later.
apply plugin: 'com.android.application'
android {
compileSdkVersion 28
defaultConfig {
applicationId "com.auth0.samples"
minSdkVersion 15
targetSdkVersion 28
//...
//---> Add the next line
manifestPlaceholders = [auth0Domain: "@string/com_auth0_domain", auth0Scheme: "https"]
//<---
}
//...
}
The next step is to create an instance of Auth0
with your applications information:
Auth0 account = new Auth0("{YOUR_AUTH0_CLIENT_ID}", "{YOUR_AUTH0_DOMAIN}");
Alternatively, if you are using custom domains and are required to specify a different URL to fetch the Lock widget configuration from, you can use the 3 String constructor:
Auth0 account = new Auth0("{YOUR_AUTH0_CLIENT_ID}", "{YOUR_AUTH0_DOMAIN}", "{THE_CONFIGURATION_DOMAIN}");
Another way to create it is using the values defined previously in the string.xml
file, by passing an Android Context. The name of the keys must match the ones listed above or the constructor will throw an exception.
Auth0 account = new Auth0(context);
It is strongly encouraged that Lock be used in OIDC Conformant mode. When this mode is enabled, it will force Lock to use Auth0's current authentication pipeline and will prevent it from reaching legacy endpoints. By default is false
.
Auth0 account = new Auth0("{YOUR_AUTH0_CLIENT_ID}", "{YOUR_AUTH0_DOMAIN}");
//Configure the account in OIDC conformant mode
account.setOIDCConformant(true);
//Use the account to launch Lock
Passwordless Lock cannot be used with this flag set to true
. For more information, please see the OIDC adoption guide.
Modify the AndroidManifest.xml
file, to include the Internet permission:
<uses-permission android:name="android.permission.INTERNET" />
Next, add the LockActivity
inside the application
tag:
<activity
android:name="com.auth0.android.lock.LockActivity"
android:label="@string/app_name"
android:launchMode="singleTask"
android:screenOrientation="portrait"
android:theme="@style/Lock.Theme"/>
In versions 2.5.0 or lower of Lock.Android you had to define an intent-filter inside the
LockActivity
to make possible to the library to capture a social provider's authentication result. This intent-filter declaration is no longer required for versions greater than 2.5.0, as it's now done internally by the library for you.
In case you are using an older version of Lock for Social Authentication, the intent-filter must be added to the LockActivity
by you.
<activity
android:name="com.auth0.android.lock.LockActivity"
android:label="@string/app_name"
android:launchMode="singleTask"
android:screenOrientation="portrait"
android:theme="@style/Lock.Theme">
<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>
Make sure the Activity's launchMode
is declared as singleTask
or the result won't come back in the authentication.
Then in any of your Activities you need to initialize Lock. If your auth0Scheme
value is not https
you need to use withScheme()
as shown below.
// This activity will show Lock
public class HomeActivity extends Activity {
private Lock lock;
@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
// Your own Activity code
Auth0 account = new Auth0("YOUR_AUTH0_CLIENT_ID", "YOUR_AUTH0_DOMAIN");
account.setOIDCConformant(true);
lock = Lock.newBuilder(account, callback)
//Customize Lock
//.withScheme("myapp")
.build(this);
}
@Override
protected void onDestroy() {
super.onDestroy();
// Your own Activity code
lock.onDestroy(this);
lock = null;
}
private LockCallback callback = new AuthenticationCallback() {
@Override
public void onAuthentication(Credentials credentials) {
//Authenticated
}
@Override
public void onCanceled() {
//User pressed back
}
@Override
public void onError(LockException error) {
//Exception occurred
}
};
}
Start LockActivity
from inside your Activity
.
startActivity(lock.newIntent(this));
The Passwordless feature requires your Application to have the Resource Owner Legacy Grant Type enabled. Check this article to learn how to enable it. Note that Passwordless authentication cannot be used with the OIDC Conformant Mode enabled.
PasswordlessLockActivity
authenticates users by sending them an Email or SMS (similar to how WhatsApp authenticates you). In order to be able to authenticate the user, your application must have the SMS/Email connection enabled and configured in your dashboard.
Modify the AndroidManifest.xml
file, to include the Internet permission:
<uses-permission android:name="android.permission.INTERNET" />
Next, add the PasswordlessLockActivity
inside the application
tag:
<activity
android:name="com.auth0.android.lock.PasswordlessLockActivity"
android:label="@string/app_name"
android:launchMode="singleTask"
android:screenOrientation="portrait"
android:theme="@style/Lock.Theme">
<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}/email"
android:scheme="https" />
</intent-filter>
</activity>
The data
attribute of the intent-filter defines which syntax of "Callback URI" your app is going to capture. In the above case it's going to capture calls from email
passwordless connections. In case you're using the sms
passwordless connection, the pathPrefix
would end in sms
.
In versions 2.5.0 or lower of Lock.Android you had to define an intent-filter inside the
PasswordlessLockActivity
to make possible to the library to capture a Social provider's authentication result. This intent-filter declaration is no longer required for versions greater than 2.5.0, as it's now done internally by the library for you.
In case you are using an older version of Lock for Social Authentication, the data attribute inside the intent-filter must be added to the PasswordlessLockActivity
by you.
<activity
android:name="com.auth0.android.lock.PasswordlessLockActivity"
android:label="@string/app_name"
android:launchMode="singleTask"
android:screenOrientation="portrait"
android:theme="@style/Lock.Theme">
<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}/email"
android:scheme="https" />
<data
android:host="@string/com_auth0_domain"
android:pathPrefix="/android/${applicationId}/callback"
android:scheme="https" />
</intent-filter>
</activity>
Make sure the Activity's launchMode
is declared as singleTask
or the result won't come back in the authentication.
When the Passwordless connection is SMS you must also add the CountryCodeActivity
to allow the user to change the Country Code prefix of the phone number.
<activity
android:name="com.auth0.android.lock.CountryCodeActivity"
android:theme="@style/Lock.Theme.ActionBar" />
Then in any of your Activities you need to initialize PasswordlessLock. If your auth0Scheme
value is not https
you need to use withScheme()
as shown below.
// This activity will show Lock
public class HomeActivity extends Activity {
private PasswordlessLock lock;
@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
// Your own Activity code
Auth0 account = new Auth0("YOUR_AUTH0_CLIENT_ID", "YOUR_AUTH0_DOMAIN");
account.setOIDCConformant(true);
lock = PasswordlessLock.newBuilder(account, callback)
//Customize Lock
//.withScheme("myapp")
.build(this);
}
@Override
protected void onDestroy() {
super.onDestroy();
// Your own Activity code
lock.onDestroy(this);
lock = null;
}
private LockCallback callback = new AuthenticationCallback() {
@Override
public void onAuthentication(Credentials credentials) {
//Authenticated
}
@Override
public void onCanceled() {
//User pressed back
}
@Override
public void onError(LockException error) {
//Exception occurred
}
};
}
Start PasswordlessLockActivity
from inside your Activity
.
startActivity(lock.newIntent(this));
The current default scheme used by the library to generate the Redirect URL for Web Authentication is https
. This works best for Android Marshmallow (API 23) or newer if you're using Android App Links. However, in previous Android versions this may show the intent chooser dialog prompting the user to choose either your application or the browser to resolve the intent. You can change this behavior by using a custom unique scheme, so that the OS opens the link directly with your app.
- Update the
auth0Scheme
Manifest Placeholder value in theapp/build.gradle
file or the Intent Filter definition in theAndroidManifest.xml
file by changing the existing scheme to the new one. - Update the Allowed Callback URLs in your Auth0 Dashboard Applications's settings to match URLs that begin with the new scheme.
- Call
withScheme()
in the Lock.Builder/PasswordlessLock.Builder passing the scheme you want to use.
The scheme value must be lowercase. A warning message will be logged if this is not the case.
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-gson.pro
proguard-otto.pro
proguard-lock-2.pro
As this library depends on Auth0.Android
, you should keep the files up to date with the proguard rules defined in the repository.
Auth0 helps you to:
- Add authentication with multiple authentication sources, either social like Google, Facebook, Microsoft Account, LinkedIn, GitHub, Twitter, Box, Salesforce, among 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.
- Go to Auth0 and click Sign Up.
- Use Google, GitHub or Microsoft Account to login.
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.
This project is licensed under the MIT license. See the LICENSE file for more info.