Web SDK
Integrate Authgear to your website with the Web SDK
Last updated
Was this helpful?
Integrate Authgear to your website with the Web SDK
Last updated
Was this helpful?
Signup for an account in https://portal.authgearapps.com/ and create a Project. Or you can use your self-deployed Authgear.
After that, we will need to create an Application in the Project Portal.
Step 1: Create an application in the Portal
Go to Applications in your project portal.
Click Add Application in the top command bar.
Input the name of your application. This is for reference only.
Decide a path in your website that users will be redirected to after they have authenticated with Authgear. Add the URI to Redirect URIs. e.g.https://yourdomain.com/auth-redirect
, or http://localhost:4000/auth-redirect
for local development.
Click "Save" and keep the Client ID. You can also obtain it from the Applications list later.
Step 2: Configure the application
In Edit Application, if you are using cookie-based authentication, you can decide the path that the user redirects to after logout. Add the URI to Post Logout Redirect URIs.
If you want to validate JWT access token in your server, under Token Settings, select Issue JWT as access token. If you will forward incoming requests to Authgear Resolver Endpoint for authentication, leave this unchecked. See comparisons in Backend Integration.
Step 3: Add your website to allowed origins
Go to Applications > Allowed Origins.
Add your website origin to the allowed origins. e.g. yourdomain.com
or localhost:4000
for local development.
Click "Save".
Step 4: Setup a custom domain (Required for Cookie-based authentication)
Go to Custom Domains
Add your custom domain in Input New Domain
Follow the instructions to verify and configure the custom domain.
Click "Activate" to change the domain status to "Active". The custom domain will be your new Authgear endpoint.
For cookie-based authentication, users will log in via the custom domain e.g. "auth.yourdomain.com" . So that a session cookie of your domain is set for the client and all your websites under "*.yourdomain.com" would share the same session cookies automatically.
The Web JS SDK is available as an npm package. Install the package in your project directory
The SDK must be properly configured before use. Call the configure
method every time your page loads up.
The SDK should be configured according to the authentication approach of your choice
Token-based authentication
sessionType
should be set to refresh_token
Cookie-based authentication
endpoint
must be a custom domain endpoint
sessionType
should be set to cookie
When the user clicks login/signup on your website, make a start authorization call to redirect them to the login/signup page.
By default, Authgear will not ask user to login again if user has already logged in. You can optionally set prompt
to login
if you you want the user always reach the login page and login again.
After the user authenticates on the login page, the user will be redirected to the redirectURI
with a code
parameter in the URL query. In the redirectURI
of your application, make a finish authorization call to handle the authentication result. This will attempt to exchange the code
for the access token and user info.
Once authorization succeed, the application should navigate the user to other URL such as the user's home page and remove the code
query parameters.
Now, your user is now logged in!
The sessionState
reflects the user logged in state in the SDK local state. That means even thesessionState
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 UserInfo
object provides the unique identifier of the user from your Authgear project. See more details here.
If you are using Token-based authentication, the logout
API will revoke the user app session only. The promise will be resolved after logout and no redirection will occur.
If you are using Cookie-based authentication , the user will be redirected to your Authgear endpoint to log out their session. You should provide the redirectURI
to which user will be redirected after logout.
To include the access token to the HTTP requests to your application server, there are two ways to achieve this.
Authgear SDK provides the fetch
function for you to call your application server. This fetch
function will include the Authorization header in your application request, and handle refresh access token automatically. The authgear.fetch
implements fetch.
You can get the access token through authgear.accessToken
. 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 the application request.
If you are using cookies, all requests from your applications under *.yourdomain.com
to your application server will include the session cookie automatically. You can skip this section and see the next step: Backend Integration
To protect your application server from unauthorized access. You will need to integrate Authgear to your backend.