Stormpath's Android SDK allows developers utilizing Stormpath to quickly integrate authentication and token management into their apps.

We're constantly iterating and improving the SDK, so please don't hesitate to send us your feedback! You can reach us via [email protected], or on the issue tracker for feature requests.

• Requirements
• Installation
• Usage
  • Configuring Stormpath
  • User registration
  • Logging in
  • Logging in with Social Providers
    • Configure Your Social Directory in Stormpath
    • Setting up your Android project
    • Initiating Social Login
    • Using the Google or Facebook SDK
  • User data
  • Using the Access Token
  • Logout
  • Reset password
  • Resend verification email
  • Verify email
• License

• Android 2.1+ (API level 7)

Add the SDK as a dependency to your build.gradle to automatically download it from jcenter.

compile 'com.stormpath.sdk:stormpath-sdk-android:2.0'

To see the SDK in action, you can try running the com.stormpath.sdk.StormpathAndroidExample project.

The Android SDK (v2) leverages the Stormpath Client API for its authentication needs. You'll need to sign into the Stormpath Admin Console to get your Client API details. Go into your Application > Policies > Client API, and ensure that it's enabled. Copy your Client API URL, and set it in your Android project:

StormpathConfiguration stormpathConfiguration = new StormpathConfiguration.Builder()
        .baseUrl("https://stormpath-notes.apps.stormpath.io/")
        .build();
Stormpath.init(this, stormpathConfiguration);

You can also enable logging for your debug builds:

if (BuildConfig.DEBUG) {
    // don't enable logging for release builds, the logs contain sensitive information!
    Stormpath.setLogLevel(StormpathLogger.VERBOSE);
}

In order to register a user, instantiate a RegistrationForm object. Stormpath requires an email and password to register.

RegistrationForm registrationForm = new RegistrationForm("[email protected]", "Pa55w0rd");

Then, just invoke the register method on Stormpath class:

Stormpath.register(registrationData, new StormpathCallback<Void>() {
    @Override
    public void onSuccess(Void aVoid) {
        // Handle successful registration
    }

    @Override
    public void onFailure(StormpathError error) {
        // Handle registration error
    }
});

To log in, collect the email (or username) and password from the user, and then pass them to the login method:

Stormpath.login("[email protected]", "Pa55w0rd", new StormpathCallback<Void>() {
    @Override
    public void onSuccess(Void aVoid) {
        // Handle successful login
    }

    @Override
    public void onFailure(StormpathError error) {
        // Handle login error
    }
});

After login succeeds, the accessToken will be saved by the SDK. You can then get it by calling Stormpath.accessToken().

Stormpath also supports logging in with a variety of social providers Facebook, Google, LinkedIn, GitHub, and more. There are two flows for enabling this:

1. Let Stormpath handle the social login.
2. Use the social provider's iOS SDK to get an access token, and pass it to Stormpath to log in.

We've made it extremely easy to set up social login without using the social provider SDKs, but if you need to use their SDKs for more features besides logging in, you should use flow #2 (and skip directly to Using a social provider SDK).

To set up your social directory, read more about social login in the Stormpath Client API Guide.

In your AndroidManifest.xml, you'll need to add Stormpath's login handler activity and configure it with an intent filter to recieve login callbacks from Stormpath.

Add this to your manifest:

<activity android:name="com.stormpath.sdk.CustomTabActivity"
    android:exported="true">
    <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:scheme="REPLACE-ME-HERE" />
    </intent-filter>
</activity>

For the data android:scheme tag, type in your Client API's DNS label, but reversed. For instance, if your Client API DNS Label is edjiang.apps.stormpath.io, type in io.stormpath.apps.edjiang.

In the Stormpath Admin Console's Application settings, add that URL as an "authorized callback URL", appending ://stormpathCallback. Following my earlier example, I would use io.stormpath.apps.edjiang.

Now, you can initiate the login screen by calling:

Stormpath.loginWithProvider(Provider.FACEBOOK, this, new StormpathCallback<Void>() {
    @Override
    public void onSuccess(Void aVoid) {
        // Handle successful login
    }

    @Override
    public void onFailure(StormpathError error) {
        // Handle login error
    }
});

Valid Provider enum values are: FACEBOOK, GOOGLE, LINKEDIN, GITHUB, TWITTER, or you can enter a string.

If you're using the Facebook SDK or Google SDK for your app, follow their setup instructions instead. Once you successfully sign in with their SDK, utilize the following methods to send your access token to Stormpath, and log in your user:

Stormpath.loginWithProvider(Provider.FACEBOOK, accessToken, new StormpathCallback<Void>() {
    @Override
    public void onSuccess(Void aVoid) {
        // Handle successful login
    }

    @Override
    public void onFailure(StormpathError error) {
        // Handle login error
    }
});

You can fetch the user data for the currently logged in user:

Stormpath.getAccount(new StormpathCallback<Account>() {
    @Override
    public void onSuccess(Account account) {
        // Do things with the account
    }

    @Override
    public void onFailure(StormpathError error) {
        // Account request failed
    }
});

You can utilize the access token to access any of your API endpoints that require authentication. It's stored as a property on the Stormpath object as Stormpath.getAccessToken(). You can use the access token by adding it to your Authorization header using the Bearer scheme. This looks like the following:

Authorization: Bearer ACCESSTOKEN

When the access token expires, you may need to refresh it. Expiration times are configurable in the Stormpath application settings.

Stormpath.refreshAccessToken(new StormpathCallback<Void>() {
    @Override
    public void onSuccess(Void aVoid) {
        // success, your new accessToken has been saved
    }

    @Override
    public void onFailure(StormpathError error) {
        // something went wrong - the user will have to log in again
    }
});

You can also log the current user out:

Stormpath.logout();

This will clear the saved accessToken and invalidate the token with the server.

To reset a password for a user, use their email address to call Stormpath.resetPassword():

Stormpath.resetPassword("[email protected]", new StormpathCallback<Void>() {
    @Override
    public void onSuccess(Void aVoid) {
        // success!
    }

    @Override
    public void onFailure(StormpathError error) {
        // something went wrong
    }
});

You can resend a verification email if the email verification flow is enabled:

Stormpath.resendVerificationEmail("[email protected]", new StormpathCallback<Void>() {
    @Override
    public void onSuccess(Void aVoid) {
        // success!
    }

    @Override
    public void onFailure(StormpathError error) {
        // something went wrong
    }
});

If you need to verify the user via the API, you can do so using the sptoken from the verification email:

Stormpath.verifyEmail(sptoken, new StormpathCallback<Void>() {
    @Override
    public void onSuccess(Void aVoid) {
        // success!
    }

    @Override
    public void onFailure(StormpathError error) {
        // something went wrong
    }
});

This project is open source and uses the Apache 2.0 License. See LICENSE file for details.