Table of Contents

1. About The Project
2. Getting Started
3. Installation
   • Using NPM Package
   • Using CDN Link
4. Usage
   • App Switcher
   • Authentication and Authorization

About The Project

---

A Javascript Library for integrate Teko Market to Web Application.
Library contain 2 parts:

• App Switcher
• Authentication and Authorization (TekoID)

Getting started

import TekoMarketSDK from 'teko-market-v1'

const { TekoMarket } = TekoMarketSDK
  
const App = props => { 
  if (TekoMarket.user.isLoggedIn()) {
    return (
      <HomePageView 
        userInfo={TekoMarket.user.getUserInfo()} 
      />
    )
  }
  return <LoginView />
}
  
const LoginView = props => ( 
  <p onClick={() => TekoMarket.user.login()}>  
    Login with TekoID 
  </p>
)  

(back to top)

Installation

Using NPM package

# With yarn  
yarn add teko-market-v1
  
# With npm  
npm install teko-market-v1

Then you can initiate the client using TekoMarket:

import TekoMarketSDK from 'teko-market-v1'  

const { TekoMarket } = TekoMarketSDK
 
TekoMarket.init({  
  clientId: 'your-client-id',  
  redirectUri: 'your-redirect-uri',
  oauthDomain: 'https://oauth.develop.tekoapis.net'  
}).then(() => {  
 // The initial phase is finish. 
 // Now you can do your logic. 
})  

which returns a promise and resolve after finish initiating.

Using CDN Link

You can also include JS SDK teko-market.min.js in your source code, then access the lib using window.TekoMarket.

<script src="https://unpkg.com/teko-market-v1/dist/bundle/teko-market.min.js"></script> 

var configs  = { 
    clientId: "<your-client-id>", // Market provides when register client auth 
    redirectUrl: "<your-redirect-uri>", //App provides for redirect when login successfully. 
} 
window.TekoMarket.init(config)

(back to top)

Usage

App Switcher

Using IFrame

<iframe
  id="app-switcher"
  title="app-switcher"
  name='{
    "parentOrigin": "<window.location.origin>" // required
    "align":"<"right | left" // optional, default value: "left"
  }'
  src="<MARKET_WEB_DOMAIN>/app-switcher"
  frameborder="0"
  scrolling="no"
  height="52px"
/>

Example:

<iframe
  id="app-switcher"
  title="app-switcher"
  name='{"parentOrigin": "https://market.dev.teko.vn","align":"right"}'
  src="https://market.dev.teko.vn/app-switcher"
  frameborder="0"
  scrolling="no"
  height="52px"
/>

Using component from SDK

(coming soon)

(back to top)

Authentication and Authorization

async TekoMarket.init(configs)

configs key	Type	Default value	Required
clientId	string		Y
oauthDomain	string	https://oauth.teko.vn
redirectUri	string	protocol//hostname:port
postLogoutRedirectUri	string	protocol//hostname:port
scopes	[string]	[]
silent	boolean	true
monitorSession	boolean	false
checkTokenRevoked	boolean	false

• clientId: The ID of your client which you registered in Identity Teko.
• redirectUri: Your client will redirect to this uri with authorization code value after user successfully logged in. This value should match exact with one of the redirect_uris you registered in IAM App.
• postLogoutRedirectUri: Your client will redirect to this uri after user successfully logged out. This value should match exact with one of the post_logout_redirect_uris you registered in IAM App.
• scopes: The scopes of your client.
• oauthDomain: The TekoMarket domain to use SDK.
• silent: If the SDK auto renew access token silently when the current one is expired. Set false to turn off this feature (so user must re-login if access token is expired).
• monitorSession: Set to true to able to listen to changes in user session.
• checkTokenRevoked: Set to true to call oauthDomain/userinfo endpoint to ensure the current cached token is not revoked.

NOTE: For develop environment, please specific oauthDomain to https://oauth.develop.tekoapis.net

NOTE: For stage environment, please specific oauthDomain to https://oauth.stage.tekoapis.net

NOTE: TekoMarket.init() function is an async function.

---

(back to top)

TekoMarket.user

.isLoggedIn()

Return true if user is logged in, false if not.

.login(redirectUri = null)

Redirect to Teko Identity OAuth Login page to start login process.

After login success, Teko Identity OAuth Login will redirect back to optional parameter redirectUri.

By default, it will redirect to redirectUri param in TekoMarket.init function.

Call this function when user click to Login button in your application.

This value should match exact with one of the redirect_uris you registered in IAM App.

async .loginSilent()

A promise return current user logged in OAuth server with latest info and new access token. Raise if there is not logged user in OAuth server.

.logout(redirectUri = null)

Clear current user's info and log user out.

After logout success, Teko Identity OAuth Login will redirect back to optional parameter redirectUri.

By default, it will redirect to postLogoutRedirectUri param in TekoMarket.init function.

Call this function when user click to Logout button in your application.

This value should match exact with one of the post_logout_redirect_uris you registered in IAM UI.

.loadUser()

Load current cache user in storage. Return undefined if there is not any user in cache storage.

Return value example:

{
  accessToken: 'random-string',
  expiresAt: 1595500000,
  expiresIn: 3600,
  idToken: 'jwt-string',
  profile: {
    sub: 'string',
    name: 'string',
    picture: 'url-string',
  },
  scopes: ['openid', 'profile'],
  sessionState: 'random-string',
  tokenType: 'Bearer'
}

NOTE: This function might return an user with expired accessToken.

.unloadUser()

Remove current cache user in storage.

.getAccessToken()

Get logged user's current access token.

Return a string which is current user's access token if user is logged. undefined if user is not logged.

NOTE: Since the access token can be renew silently after the current is expired (init with slient: true), be sure that you always use the current access token (not the old one).

import axios from 'axios'
import TekoMarketSDK from 'teko-market-v1'

const { TekoMarket } = TekoMarketSDK
const { user } = TekoMarket

// Bad
const axiosInstance = axios.create({
  headers: { 
    Authorization: `Bearer ${user.getAccessToken()}` 
  }
})

// The access token always same
axiosInstance.get('/api/resources') 

// Good
axios.get('/api/resources', {
  headers: { 
    Authorization: `Bearer ${user.getAccessToken()}` 
  }
}) // Now the token is fetch each time a request is made

// Better
const axiosInstance = axios.create()
axiosInstance.interceptors.request.use(
  config => {
    config.headers.Authorization = `Bearer ${user.getAccessToken()}`
    return config
  },
  error => Promise.reject(error)
)
axiosInstance.get('/api/resources')

NOTE: You should treat access token as a random string, even when OAuth server return this token in some specific forms (like JWT).

.getUserInfo()

Get current user's general information.

Return object which includes current user's information. Return undefined if user is not logged or openid not in scopes.

• With openid scope, id_token will return with fields: sub, name, picture, updated_at.

• With addition profile scope, id_token will return with addition fields: email, phone_number, birthday, address.

Return value example (with openid, profile, read:permissions included in scopes):

{
  sub: 'user_unique_id',
  name: 'User Name',
  picture: 'https://domain.com/avatar_url.jpg',

  email: 'email@teko.vn',
  phone_number: '0123456789',
  birthday: '2000-12-31',
  address: 'Yume street',
}

async .getFullUserInfo(adminDomain = null)

Send HTTP request to get current user's full information.

Return object which includes current user's information. Return undefined if user is not logged or access token is expired. Return {message: null} current access token is invalid (revoked).

The response is as same as .getUserInfo() response, with addition read:permissions scope:

• With addition read:permissions scope, response will return with addition fields: roles, permissions, meta_data.

Return value example (with openid, profile, read:permissions included in scopes):

{
  sub: 'user_unique_id',
  name: 'User Name',
  picture: 'https://domain.com/avatar_url.jpg',
  updated_at: '2019-12-31 00:00:00',

  email: 'email@teko.vn',
  phone_number: '0123456789',
  birthday: '2000-12-31',
  address: 'Yume street',

  roles: ['string'],
  permissions: ['string'],
  meta_data: { key: 'value' }
}

WARNING: Calling getFullUserInfo() without specific adminDomain may lead to incorrect data.

For Teko OAuth, the adminDomain is auto-detected from oauthDomain. For other OAuth (Digilife OAuth), please specific this parameter.

This parameter is needed because of the limitation in current OAuth server when refresh user's access control data. This may be changed in later version.

.getUserScopes()

Get logged user's scopes.

Return array of string which is current user's scopes if user is logged. undefined if user is not logged.

Return value example:

['openid', 'profile']

NOTE: This scopes may different with the scopes you defined when init. Because the scopes may be able to access by your app, but not for the current user (the user denied the app for access his/her data). If you want to use scopes in order to display correct UI, please use this scopes value.

.getAccessTokenExpiresAt()

Return timestamp when the access token expired. undefined if user is not logged.

(back to top)

---

TekoMarket.user.events

Register callbacks and execute them whenever certain events raise.

Current supported events:

• userLoaded: raised when a user session has been established (or re-established). Not raised when user is loaded from cache storage.
• userSessionChanged: raised when user's sign in status at OAuth Server has changed.
• silentRenewError: raised when automatic silent renew has failed.
• accessTokenExpiring: raised 5 minutes before the current access token expires.
• accessTokenExpired: raised when current access token has expired.

You can register callbacks by add functions, or remove them if you no longer want to execute them.

Examples:

// Should only call after Teko.init has resolved
TekoMarket.user.events.addUserSessionChanged(() => {
  alert('User session changed. Force user to re-login.')
  TekoMarket.user.unloadUser()
  TekoMarket.user.login()
})

TekoMarket.user.events.addSilentRenewError(err => {
  console.err('Silent renew error. Details:', err)
})

(back to top)