AppAuth for Android is a client SDK for communicating with [OAuth 2.0] (https://tools.ietf.org/html/rfc6749) and [OpenID Connect] (http://openid.net/specs/openid-connect-core-1_0.html) providers. It strives to directly map the requests and responses of those specifications, while following the idiomatic style of the implementation language. In addition to mapping the raw protocol flows, convenience methods are available to assist with common tasks like performing an action with fresh tokens.
The library follows the best practices set out in [OAuth 2.0 for Native Apps]
(https://tools.ietf.org/html/draft-ietf-oauth-native-apps)
including using
Custom Tabs
for the auth request. For this reason,
WebView is explicitly not supported due to usability and security reasons.
The library also supports the PKCE extension to OAuth which was created to secure authorization codes in public clients when custom URI scheme redirects are used. The library is friendly to other extensions (standard or otherwise) with the ability to handle additional parameters in all protocol requests and responses.
A talk providing an overview of using the library for enterprise single sign-on (produced by Google) can be found here: Enterprise SSO with Chrome Custom Tabs.
Download the latest AAR (direct link / Bintray repository) or add a dependency using Gradle:
compile 'net.openid:appauth:0.3.0'Or Maven:
<dependency>
<groupId>net.openid</groupId>
<artifactId>appauth</artifactId>
<version>0.2.0</version>
</dependency>AppAuth supports Android API 16 (Jellybean) and above.
When a Custom Tabs implementation is provided by a browser on the device (for example by Chrome), Custom Tabs are used for authorization requests. Otherwise, the default browser is used as a fallback.
Both Custom URI Schemes (all supported versions of Android) and App Links (API 23+) can be used with the library.
In general, AppAuth can work with any Authorization Server (AS) that supports native apps, either through custom URI scheme redirects, or App Links. AS's that assume all clients are web-based or require clients to maintain confidentiality of the client secrets may not work well.
The project requires the Android SDK for API level 23 (Marshmallow) to build, though the produced binaries only require API level 16 (Jellybean) to be used.
Follow the instructions in app/README.md to configure the demo app with your own OAuth client (you need to update 3 configuration points with your client info to try the demo).
AppAuth for Android uses Gradle as its build system. In order to build
the library and app binaries, run ./gradlew assemble.
The library AAR files are output to library/build/outputs/aar, while the
demo app is output to app/build/outputs/apk.
In order to run the tests and code analysis, run ./gradlew check.
The build script attempts
to guess the location of your SDK by looking at the values of $ANDROID_SDK_HOME
and $ANDROID_HOME. If neither of these are defined or are not the SDK you
wish to use, you must create a local.properties file in the project root.
This file must define a property sdk.dir that points to your SDK root
directory. For example:
sdk.dir=/path/to/android-sdk
In AndroidStudio, File -> New -> Import project. Select the root folder
(the one with the build.gradle file).
If you get an error like:
Error:Could not find com.android.support:customtabs:23.2.0. then be sure you
have installed the Android Support Library from the Android SDK Manager.
Follow the Android Studio prompts to resolve the dependencies automatically.
AppAuth supports both manual interaction with the Authorization Server
where you need to perform your own token exchanges, as well as convenience
methods that perform some of this logic for you. This example
performs a manual exchange, and stores the result as an AuthState object.
AuthState is a class that keeps track of the authorization and token
requests and responses, and provides a convenience method to call an API with
fresh tokens. This is the only object that you need to serialize to retain the
authorization state of the session. Typically, one would do this by storing
the authorization state in SharedPreferences or some other persistent store
private to the app:
@NonNull public AuthState readAuthState() {
SharedPreferences authPrefs = getSharedPreferences("auth", MODE_PRIVATE);
String stateJson = authPrefs.getString("stateJson");
AuthState state;
if (stateStr != null) {
return AuthState.fromJsonString(stateJson);
} else {
return new AuthState();
}
}
public void writeAuthState(@NonNull AuthState state) {
SharedPreferences authPrefs = getSharedPreferences("auth", MODE_PRIVATE);
authPrefs.edit()
.putString("stateJson", state.toJsonString())
.apply();
}You can configure AppAuth by specifying the endpoints directly:
AuthorizationServiceConfiguration config =
new AuthorizationServiceConfiguration(name, mAuthEndpoint, mTokenEndpoint);
// perform the auth request...Or through discovery:
final Uri issuerUri = Uri.parse("https://accounts.google.com");
AuthorizationServiceConfiguration config;
AuthorizationServiceConfiguration.fetchFromIssuer(
issuerUri,
new RetrieveConfigurationCallback() {
@Override public void onFetchConfigurationCompleted(
@Nullable AuthorizationServiceConfiguration serviceConfiguration,
@Nullable AuthorizationException ex) {
if (ex != null) {
Log.w(TAG, "Failed to retrieve configuration for " + issuerUri, ex);
} else {
// service configuration retrieved, proceed to authorization...
}
}
});If the server supports dynamic client registration, a new registration request can be constructed for dispatch:
RegistrationRequest registrationRequest = new RegistrationRequest.Builder(
serviceConfig,
Arrays.asList(redirectUri))
.build();Requests are dispatched with the help of AuthorizationService. As this
request is asynchronous the response is passed to a callback:
service.performRegistrationRequest(
registrationRequest,
new AuthorizationService.RegistrationResponseCallback() {
@Override public void onRegistrationRequestCompleted(
@Nullable RegistrationResponse resp,
@Nullable AuthorizationException ex) {
if (resp != null) {
// registration succeeded, store the registration response
AuthState state = new AuthState(resp);
//proceed to authorization...
} else {
// registration failed, check ex for more details
}
}
});After configuring or retrieving an authorization service configuration, an authorization request can be constructed for dispatch:
AuthorizationRequest req = new AuthorizationRequest.Builder(
config,
clientId,
ResponseTypeValues.CODE,
redirectUri)
.build();Requests are dispatched with the help of AuthorizationService. As this
will open a custom tab or browser instance to fulfill this request, the
response is delivered via an intent to an activity of your choosing:
AuthorizationService service = new AuthorizationService(context);
Intent postAuthIntent = new Intent(context, MyAuthResultHandlerActivity.class);
service.performAuthorizationRequest(
req,
PendingIntent.getActivity(context, req.hashCode(), postAuthIntent, 0));In the AndroidManifest.xml, declare the activity that receives the redirect
URI intent, and the scheme of your OAuth client's redirect URI:
<activity android:name="net.openid.appauth.RedirectUriReceiverActivity">
<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="com.yourapp"/>
</intent-filter>
</activity>
The response is delivered to the specified handler, and can be extracted from the intent data:
public void onCreate(Bundle b) {
// ...
AuthorizationResponse resp = AuthorizationResponse.fromIntent(getIntent());
AuthorizationException ex = AuthorizationException.fromIntent(getIntent());
if (resp != null) {
// authorization succeeded
} else {
// authorization failed, check ex for more details
}
// ...
}Given the auth response, a token request can be created to exchange the authorization code:
service.performTokenRequest(
resp.createTokenExchangeRequest(),
new AuthorizationService.TokenResponseCallback() {
@Override public void onTokenRequestCompleted(
TokenResponse resp, AuthorizationException ex) {
if (resp != null) {
// exchange succeeded
} else {
// authorization failed, check ex for more details
}
}
});If a confidential client is created through dynamic registration, and
the server expects the client to authenticate at the token endpoint,
the necessary client authentication must be supplied in the token
request. This can be simplified by making sure to store the registration
response in the AuthState instance, then
AuthState::getClientAuthentication can construct the necessary client
authentication:
service.performTokenRequest(
resp.createTokenExchangeRequest(),
state.getClientAuthentication(),
new AuthorizationService.TokenResponseCallback() {
@Override public void onTokenRequestCompleted(
TokenResponse resp, AuthorizationException ex) {
if (resp != null) {
// exchange succeeded
} else {
// authorization failed, check ex for more details
}
}
});With an updated AuthState based on the token exchange, it is then possible to make requests using guaranteed fresh tokens at any future point:
AuthState state = readAuthState();
state.performActionWithFreshTokens(service, new AuthStateAction() {
@Override public void execute(
String accessToken,
String idToken,
AuthorizationException ex) {
if (ex != null) {
// negotiation for fresh tokens failed, check ex for more details
return;
}
// use the access token to do something ...
}
});Browse the [API documentation] (http://openid.github.io/AppAuth-Android/docs/latest/).