Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/trivago/Heimdall.droid
Easy to use OAuth 2 library for Android by trivago.
https://github.com/trivago/Heimdall.droid
Last synced: about 1 month ago
JSON representation
Easy to use OAuth 2 library for Android by trivago.
- Host: GitHub
- URL: https://github.com/trivago/Heimdall.droid
- Owner: trivago
- License: apache-2.0
- Created: 2015-02-09T09:17:37.000Z (over 9 years ago)
- Default Branch: master
- Last Pushed: 2023-05-11T16:38:20.000Z (over 1 year ago)
- Last Synced: 2024-07-18T14:42:07.624Z (2 months ago)
- Language: Kotlin
- Homepage: http://trivago.github.io/Heimdall.droid/
- Size: 44 MB
- Stars: 258
- Watchers: 39
- Forks: 23
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- License: LICENSE.txt
Awesome Lists containing this project
README
# 
Heimdall
Heimdall is an [OAuth 2.0](https://tools.ietf.org/html/rfc6749) client specifically designed for easy usage and high flexibility. It supports all grants as described in [Section 4](https://tools.ietf.org/html/rfc6749#section-4) as well as refreshing an access token as described in [Section 6](https://tools.ietf.org/html/rfc6749#section-6) of the [The OAuth 2.0 Authorization Framework](https://tools.ietf.org/html/rfc6749) specification.
This library makes use of [RxJava](https://github.com/ReactiveX/RxJava). Therefore you should be familar with [Observables](https://github.com/ReactiveX/RxJava/wiki/Observable).
If you are an iOS Developer then please take a look at the [Swift version of Heimdall](https://github.com/trivago/Heimdallr.swift).
[](https://jitpack.io/#trivago/Heimdall.droid)
[](https://travis-ci.org/trivago/Heimdall.droid)
[](http://android-arsenal.com/details/1/2016)
[](https://android-arsenal.com/api?level=9)
## Installation
Heimdall is ready to be used via [jitpack.io](https://jitpack.io/#rheinfabrik/Heimdall.droid).
Simply add the following code to your root `build.gradle`:
```groovy
allprojects {
repositories {
jcenter()
maven { url "https://jitpack.io" }
}
}
```
Now add the gradle dependency in your application's `build.gradle`:
```groovy
dependencies {
compile 'com.github.rheinfabrik:Heimdall.droid:{latest_version}'
}
```
## Examples
Heimdall's main class is the `OAuth2AccessTokenManager`. It is responsible for retrieving a new access token and keeping it valid by refreshing it.
In order to initialize an `OAuth2AccessTokenManager` instance, you need to pass an object implementing the `OAuth2AccessTokenStorage` interface. You can use the predefined `SharedPreferencesOAuth2AccessTokenStorage` if it suits your needs. Make sure that your `OAuth2AccessTokenStorage` is as secure as possible!
```java
SharedPreferencesOAuth2AccessTokenStorage storage = new SharedPreferencesOAuth2AccessTokenStorage<>(mySharedPreferences, OAuth2AccessToken.class);
OAuth2AccessTokenManager<> manager = new OAuth2AccessTokenManager(storage);
```
On your manager instance you can now call `grantNewAccessToken(grant)` to receive a new access token. The grant instance you pass must implement the `OAuth2Grant` interface and your actual server call.
Here is an example of an `OAuth2ResourceOwnerPasswordCredentialsGrant`.
```java
public class MyOAuth2Grant extends OAuth2ResourceOwnerPasswordCredentialsGrant {
// Constructor
@Override
public Observable grantNewAccessToken() {
// Create the network request based on the username, the password and the grant type.
// You can use Retrofit to make things easier.
}
}
```
Your manager instance also has a method called `getValidAccessToken(refreshGrant)`. This is probably the main reason we build this library. It firstly checks if the stored access token is expired and then either emits the unexpired one or refreshs it if it is expired using the passed refresh grant.
Here is an example of an `OAuth2RefreshAccessTokenGrant`.
```java
public class MyOAuth2Grant extends OAuth2RefreshAccessTokenGrant {
// Constructor
@Override
public Observable grantNewAccessToken() {
// Create the network request based on the grant type and the refresh token.
// You can use Retrofit to make things easier.
}
}
```
Mostly you will use the `OAuth2AuthorizationCodeGrant` to authorize the user via a third party service such as Trakt.tv.
The implemention of a grant authorizing with Trakt.tv might look as following:
```java
public final class TraktTVAuthorizationCodeGrant extends OAuth2AuthorizationCodeGrant {
public String clientSecret;
@Override
public Uri buildAuthorizationUri() {
return Uri.parse("https://trakt.tv/oauth/authorize")
.buildUpon()
.appendQueryParameter("client_id", clientId)
.appendQueryParameter("redirect_uri", redirectUri)
.appendQueryParameter("response_type", RESPONSE_TYPE).build();
}
@Override
public Observable exchangeTokenForCode(String code) {
// Create the network request based on the grant type, clientSecret and the retrieved code.
// You can use Retrofit to make things easier.
}
}
```
Using that grant with an Android WebView might look like this (please note that we use [Retrolambda](https://github.com/evant/gradle-retrolambda) here):
```java
// Create the grant
TraktTVAuthorizationCodeGrant grant = new TraktTVAuthorizationCodeGrant();
grant.clientSecret = "secret"
grant.clientId = "id"
grant.redirectUri = "uri"
// Set up web view loading
webView.setWebViewClient(new WebViewClient() {
@Override
public void onPageFinished(WebView view, String url) {
super.onPageFinished(view, url);
// Tell the grant we loaded an url
grant.onUrlLoadedCommand.onNext(Uri.parse(url));
}
});
// Load the authorization url once build
grant.authorizationUri()
.map(Uri::parse)
.observeOn(AndroidSchedulers.mainThread())
.subscribe(myWebView::load)
// Start the authorization process
grant.grantNewAccessToken()
.subscribe(token -> Log.d("Heimdall", "New token: " + token))
```
## Sample Application
Please also check out our sample application which performs an authorization against [trakt.tv](https://trakt.tv/) and displays a simple list of the user's watchlists.
**Note:** In order to build the sample by yourself you have to [create a new application on trakt.tv](https://trakt.tv/oauth/applications/new) and add the credentials wherever `TraktTvAPIConfiguration.java` is used.
## About
Heimdall was built by [trivago](http://www.trivago.com) :factory:
## License
Heimdall is licensed under Apache Version 2.0.