Skip to main content

Login with OAuth2 Providers

The following code contains example use cases for authentication flows using OAuth2 with Google / Facebook / Microsoft. Currently only support Google

Login with credentials from Google​

Step 1: Authenticate with Google​

To authenticate with Google, you will need to use the Google Sign-In API to retrieve a Google ID token (or access-token) for the user. You can then use this token to authenticate the user with the server.

Here is document how to Verify the Google ID token on your server side

Example Google account information verified from Goolge IdToken
{
  "envelope": {
    "alg": "RS256",
    "kid": "acda360fb36cd15ff83af8...",
    "typ": "JWT"
  },
  "payload": {
    "iss": "https://accounts.google.com",
    "azp": "454...67pgst.apps.googleusercontent.com",
    "aud": "454...67pgst.apps.googleusercontent.com",
    "sub": "107...195",
    "email": "be...nt@gmail.com",
    "email_verified": true,
    "at_hash": "iSfgM...rQ",
    "name": "An Ngo",
    "picture": "https://lh3.googleusercontent.com/a/AGN...96-c",
    "given_name": "The",
    "family_name": "Name",
    "locale": "en",
    "iat": 1680971466,
    "exp": 1680975066
  }
}

Step 2: Log in with OAuth Provider​

Once you have authenticated the user with Google, you can use their Google account to log in to your application. To do this, you will need to use an OAuth provider like Google to create a user account on your server.

  1. Call POST /auth/login with the following request body:
{
  "type": "oauth-provider",
  "clientId": "client-app-id",
  "withOAuth": {
    "providerName": "18kings-account-web.google",
    "providerToken": "4543091062...t67pgst.apps.googleusercontent.com",
    "providerTokenType": "idtoken"
  }
}

Properties

FieldDescription
providerNameprovider name that pre-config in backend that associated with a Google clientId and secret.
providerTokenToken that web / mobile client get from user, can be an id-token or access-token.
providerTokenTypevalue: 'idtoken' or 'accesstoken' to match token providerToken value above
  1. Expect a 200 OK response with an accessToken property.
{
  "accessToken": "...",
  "refreshToken": "..."
}

Step 3: Update user profile​

After logging in with the OAuth provider, you may need to update the user's profile with additional information (e.g. email address, name, etc.). This can be done using an API endpoint on your server.

Note

After update email / username / password, user can login by usename and password instead.

Step 4: Update user email​

  1. Call PATCH /api/me/email with the following request body:
{
  "email": "your-new-email@gmail.com"
}
  1. Call GET /auth/confirm-email/:verifyToken, where :verifyToken is the verification token sent to the user's email address.
  2. Expect a 200 OK response with the following body:
{
  "success": true,
  "message": "Email verified"
}

Step 5: Update user password​

  1. Call PATCH /api/me/password with the following request body:
{
  "currentPassword": "",
  "password": "your-new-password",
  "passwordConfirm": "your-new-password"
}
Note

In first password changes request, current password allow empty

Password must follow password rules and must includes uppercase and special characters.

/((?=._\d)|(?=._\W+))(?![.\n])(?=._[A-Z])(?=._[a-z]).\*$/
  1. Expect a 200 OK response with the following body:
{
  "success": true,
  "message": "Password updated"
}

Step 5: Update user username​

Note

Username only allow to changes in limited times, currently 1

  1. Call PATCH /api/me/username with the following request body:
{
  "username": "your-new-username"
}
  1. Expect a 200 OK response with the following body:
{
  "success": true,
  "message": "Username updated"
}

Step 5: Use Access Token​

Once the user's profile has been updated, you can use the access token to authenticate subsequent requests to your server.

Intergate login buttons with provider (Google, Facebook...)​

Draft guide to integrate external provider login button (currently only support Google)

Pure provider login button​

Use this method require immerdiate step to use client library that login provider provide then use credential from client library to login

  1. Step 1: Using provider-based client login library to login and directly get provider access token, suggestion some guide below:
  1. Step 2: Using provider-based access token to login with POST /auth/login as above guide

Use api server as direct login​

Using this method to directly login into service, only available on webapp since this require redirection that only available when call on browser

(to be implemented)

  • POST /api/auth/login: Login user.
  • PATCH /api/me/email: Update user email.
  • PATCH /api/me/username: Update user username.
  • PATCH /api/me/password: Update user password.