Flutter SDK
How to integrate with a Flutter app
This guide provides instructions on integrating Authgear with a Flutter app. Supported platforms include:
Flutter 2.5.0 or higher
Setup Application in Authgear
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.
You will see the "New Application" page or 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, 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, select "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.
Create a Flutter app
Follow the documentation of Flutter to see how you can create a new Flutter app.
Install the SDK
Platform Integration
To finish the integration, setup the app to handle the redirectURI specified in the application. This part requires platform specific integration.
This declares the URL schemes supported by your app, so the device can redirect the user to the app after authentication using the redirect URI.
Android
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.
Targeting API level 30 or above (Android 11 or above)
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
.
iOS
Declare URL Handling in Info.plist
In Info.plist
, add the matching redirect URI by adding the key CFBundleURLTypes
and the values inside <dict>
as shown as the following example.
Try authenticate
Add this code to your app. This snippet configures authgear to connect to an authgear server deployed at endpoint
with the client you have just setup via clientID
, opens a browser for authentication, and then upon success redirects to the app via the redirectURI
specified.
Now, your user is logged in!
Get the Logged In State
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 SessionState.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 SessionState.unknown
, SessionState.noSession
or SessionState.authenticated
. Initially, the sessionState
is SessionState.unknown
. After a call to authgear.configure
, the session state would become SessionState.authenticated
if a previous session was found, or SessionState.noSession
if such session was not found.
Fetching User Info
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.
Using the Access Token in HTTP Requests
To include the access token to the HTTP requests to your application server, use wrapHttpClient
.
The wrapped client will include the Authorization header in every HTTP request, and refresh access token automatically.
Logout
To log out the user from the current app session, you need to invoke thelogout
function.
Next steps
To protect your application server from unauthorized access. You will need to integrate your backend with Authgear.
Backend IntegrationFlutter SDK Reference
For detailed documentation on the Flutter SDK, visit Flutter SDK Reference
Footnote
[^1]: For futher instruction on setting up custom URI scheme in Flutter, see https://docs.flutter.dev/development/ui/navigation/deep-linking
[^2]: For more explaination on JWT, see https://en.wikipedia.org/wiki/JSON_Web_Token
Last updated