Android SDK
How to use authgear android SDK
Last updated
How to use authgear android SDK
Last updated
This guide provides instructions on integrating Authgear with an Android app. Supported platforms include:
Android 5.0 (API 21) or higher
Signup for an Authgear Portal account in https://portal.authgear.com. Or you can use your self-deployed Authgear.
From the Project listing, create a new Project or select an existing Project. After that, we will need to create an application in the project.
Step 1: Create an application in the Portal
Go to Applications on the left menu bar.
Click ⊕Add Application in the top tool bar.
Input the name of your application and select Native App as the application type. Click "Save".
You will see a list of guides that can help you for setting up, then click "Next".
Step 2: Configure the application
In your IDE (e.g. Android Studio), define a custom URI scheme that the users will be redirected back to your app after they have authenticated with Authgear, e.g. com.myapp.example://host/path
.[^1]
Head back to Authgear Portal, fill in the Redirect URI that you have defined in the previous steps.
Click "Save" in the top tool bar and keep the Client ID. You can also obtain it again from the Applications list later.
If you wish to validate JSON Web Token (JWT) in your own application server, turn on "Issue JWT as access token".[^2] If you wish to forward authentication requests to Authgear Resolver Endpoint, leave this unchecked. See comparisons in Backend Integration.
Add jitpack
repository to gradle
Add authgear in dependencies. Use $branch-SNAPSHOT
(e.g. main-SNAPSHOT
) for the latest version in a branch or a release tag/git commit hash of the desired version.
Add the following activity entry to the AndroidManifest.xml
of your app. The intent system would dispatch the redirect URI to OauthRedirectActivity
and the SDK would handle the rest.
If your Android app is targeting API level 30 or above (Android 11 or above), you need to add a queries
section to AndroidManifest.xml
.
Add the following code to your app's Application
class. If there is none, add a class that extends Application
. Make sure it is declared in AndroidManifest.xml
's application
tag with the name
attribute as described here.
Add the following code to your view model. Do NOT call these codes in activity as this can lead to memory leak when your activity instance is destroyed. You can read more on the view model in the official documentation here.
The above call of authorize
passes in the exact redirect URI as configured in the applications and manifest, the callback then indicates authorization success or failure. By default, the callback is called on the main thread.
Now, your user is logged in!
When you start launching the application. You may want to know if the user has logged in. (e.g. Show users the login page if they haven't logged in). The SessionState
reflects the user logged in state in the SDK local state. That means even the SessionState
is AUTHENTICATED
, the session may be invalid if it is revoked remotely. After initializing the Authgear SDK, call fetchUserInfo
to update the SessionState
as soon as it is proper to do so.
The value of SessionState
can be UNKNOWN
, NO_SESSION
or AUTHENTICATED
. Initially, the sessionState
is UNKNOWN
. After a call to authgear.configure
, the session state would become AUTHENTICATED
if a previous session was found, or NO_SESSION
if such session was not found.
In some cases, you may need to obtain current user info through the SDK. (e.g. Display email address in the UI). Use the fetchUserInfo
function to obtain the user info, see example.
Call refreshAccessTokenIfNeeded
every time before using the access token, the function will check and make the network call only if the access token has expired. Include the access token into the Authorization header of your application request. If you are using OKHttp in your project, you can also use the interceptor extension provided by the SDK, see detail.
To log out the user from the current app session, you need to invoke thelogout
function.
To protect your application server from unauthorized access. You will need to integrate your backend with Authgear.
For detailed documentation on the Flutter SDK, visit Android SDK Reference
[^1]: For further instruction on setting up custom URI scheme in Android, see https://developer.android.com/training/app-links/deep-linking [^2]: For more explanation on JWT, see https://en.wikipedia.org/wiki/JSON_Web_Token