Regular Web App

Summary

This guide demonstrates how to integrate a regular web app with SkyJoy for authentication. SkyJoy allows you to quickly add authentication to almost any application type. By following this guide, you can enhance your web app's security and user management.

Before you begin

• To proceed, you'll need to obtain the necessary Client Credentials. These credentials are essential for authenticating your web app with SkyJoy.

• Contact SkyJoy Team ([e-mail]) to get Client Credentials.

How it works

In a regular web application:

1. Your web browser requests access.

2. Your App Server redirects the user to SkyJoy Authentication Site.

3. The users input info.

4. SkyJoy Authentication Site sends the user info to SkyJoy Authentication Server.

5. SkyJoy Authentication Server callback Authorization Code to your App Server.

6. Your App Server requests exchanges User Access Token/ Refresh Token.

7. SkyJoy Authentication Server responds with the User Token.

For authentication server, use this Base URL below:

For UAT environment

https://id.uat.skyjoy.io/realms/uat-loyalty

For Production environment

https://id.skyjoy.vn/realms/loyalty

Integration steps

This section will provide step-by-step instructions for integrating your web app with SkyJoy for authentication.

1. Redirect to Authentication Site

To enable users to log in, your application will redirect them to the Authentication page. Initiate the authentication process by constructing an authentication URL with the following parameters:

${baseURL}/protocol/openid-connect/auth?client_id=${clientId}&redirect_uri=${redirectUri}&response_type=code&state=${state}&nonce=${nonce}

Parameter

Parameter name	Description
baseURL	The URL of the SkyJoy authentication server
clientId	Your unique client identifier obtained from the SkyJoy team
redirectUri	The URL to which SkyJoy will redirect the user after successful authentication
scopes	Contain value 'openid dob phone profile email'
state	Contain value 'your-random-state-value'. You can generate a random value for CSRF protection.
nonce	Contain value 'your-random-nonce-value'. You can generate a random value for ID Token replay protection

Sample

In Javascript

const baseUrl = 'skyjoy-auth-server';
const clientId = 'your-client-id';
const redirectUri = 'http://your-company.com/callback';
const scopes = 'openid dob phone profile email'; // Space-separated list of scopes
const state = 'your-random-state-value'; // Generate a random value for CSRF protection
const nonce = 'your-random-nonce-value'; // Generate a random value for ID Token replay protection

const authorizationUrl = `${baseUrl}/protocol/openid-connect/auth?` +
    `client_id=${clientId}` +
    `&redirect_uri=${encodeURIComponent(redirectUri)}` +
    `&response_type=code` +
    `&scope=${encodeURIComponent(scopes)}` +
    `&state=${state}` +
    `&nonce=${nonce}`;

res.redirect(authorizationUrl);

The UI of the SkyJoy login page when directing users to the authentication site.

2. Handle Authorization Code from Redirect URL

After the user completes the authentication on the SkyJoy page, they will be redirected back to your web app's redirectUri. Here's how you can handle the authentication flow:

const handleToken = () => {
  const authCode = getAuthCodeFromURL();

  if (authCode) {
    // The user is authenticated
    // You can now request access token from authorization code
  } else {
    // Handle authentication failure
  }
};

const getAuthCodeFromURL = () => {
  const params = new URLSearchParams(window.location.search);
  return params.get('code');
};

• The handleToken function is called when users are redirected back to your redirectUri. It checks for the presence of an authorization code in the URL.

• If a code is present, it can be used to request access token and then get the user's identity. If the code is absent or invalid, you can handle the authentication failure as needed.

3. Access Token Request

To exchange the authorization code for an access token and refresh token, the client applications perform a POST request to SkyJoy Authentication Server.

Sample

const request = require('request'); // You may need to install the `request` package

const tokenOptions = {
    method: 'POST',
    url: `${baseUrl}/protocol/openid-connect/token`,
    form: {
        grant_type: 'authorization_code',
        client_id: clientId,
        code,
        redirect_uri: redirectUri,
    },
};

request(tokenOptions, (error, response, body) => {
    if (!error && response.statusCode == 200) {
        const tokenResponse = JSON.parse(body);

        // You can now use tokenResponse.access_token and tokenResponse.refresh_token to access protected resources and refresh tokens as needed.
    } else {
        // Handle errors
    }
});

4. Get user profile with access token

Now that your users can log in, you will likely want to be able to retrieve the profile associated with authenticated users. For example, you may want to be able to personalize the user interface by displaying a logged-in user’s name or phone number.

This method provides user information through the access token. The client application sends a GET request to the specified URL with the access token included in the Authorization header. The server responds with the user's profile data in a JSON format, including various user attributes such as Sky ID, email verification status, full name, or phone number.

Retrieve user profile

GET {{base_url}}/protocol/openid-connect/userinfo

Headers

Name	Type	Description
Authorization*	String	Bearer {{user_access_token}}
app-id*		{{client-id}}

200: OK Success

{
    "sky_id": "SJ9796934822",
    "sub": "dad1ef6a-0992-4add-a89e-872aaca62352",
    "email_verified": false,
    "name": "Nguyen Van",
    "preferred_username": "[phone]",
    "given_name": "Nguyen",
    "family_name": "Van"
}

5. Add logout to your application

To properly handle logout, we need to clear the session and log the user out of SkyJoy. The client application sends a POST request to the specified URL with the user's refresh token provided in the body. The server responds with a success message indicating the user has been logged out successfully.

Log out user

POST {{base_url}}/protocol/openid-connect/logout

Headers

Name	Type	Description
Content-Type*	String	application/x-www-form-urlencoded
app-id*	String	{{client-id}}

Request Body

Name	Type	Description
client_id*	String	{{client-id}}
refresh_token*	String	<user refresh token>

200: OK success

{
  "success": true,
  "message": "Success",
  "data": null
}