¶ Single Sign-On

Single sign-on (SSO) is one of the popular solutions for enterprise business integration. The definition of SSO is that in multiple application systems, users only need to log in once to access all mutually trusted application systems. You can read this guide to learn how to quickly implement single sign-on in your application.

¶ Installation

¶ Install via NPM

$ npm install @authing/sso --save

Then it can be used in the following way

import AuthingSSO from "@authing/sso";

¶ Install via CDN

<script src="https://cdn.jsdelivr.net/npm/@authing/sso/dist/AuthingSSO.umd.min.js"></script>
<script>
  console.log(AuthingSSO);
</script>

¶ Quick Start

Before starting, you need to create an application。

¶ Initialization

To initialize the AuthingSSO SDK, you need to pass in the application ID and application domain name. The format of the application domain name is example-app.authing.cn without the protocol header and Path. See the initialization constructor for detailed parameters.

import AuthingSSO from "@authing/sso";

let auth = new AuthingSSO({
  appId: "APP_ID",
  appDomain: "example-app.authing.cn"
});

let auth = new AuthingSSO({
  appId: "APP_ID",
  appDomain: "example-app.you-authing-service.cn",
  host: {
    oauth: "https://core.you-authing-service.com/graphql"
  }
});

¶ Login

¶ Redirect login

Initiating single sign-on, it will redirect to the login page. The relevant application needs to open the authorization code mode if use authorization code mode.

auth.login();

¶ Window login

Initiate single sign-on, a window will pop up,and the login page in it. The relevant application needs to open the authorization code mode if use authorization code mode.

auth.windowLogin();

The business domain name callback address needs to host an html file, which is used to send the obtained code access_token id_token and other parameters to the parent window by postMessage, and then close the window.

For example, the callback address is [https://example.com/handle.html](https://example.com/handle.html. This html needs a piece of code to send postMessage, which is responsible for taking out relevant parameters from the url and passing them to the parent window.

GitHub reference code: https://github.com/Authing/oidc-window (opens new window)。

¶ Redirect to registration page

Sometimes you may want to allow users to redirect to the registration page, an example of use is as follows:

// Call this function to redirect directly to the registration page
auth.register();

¶ Check login status

After the user logs in and returns to your business address, you can use this method to query the user's login status in this application. If the user is logged in, the user information of the user can be obtained, and you can understand the definitions ofall fields of user information.

let res = await auth.trackSession();
/**
 * {
 *    session: { appId: 'xxx', type: 'oidc/oauth', userId: 'yyy'},
 *    userInfo: {
 *      "_id": "USER_ID",
 *      "email": "USER_EMAIL",
 *      "registerInClient": "CLIENT_ID",
 *      "token": "JTW_TOKEN",
 *      "tokenExpiredAt": "2019-10-28 10:15:32",
 *      "photo": "PICTURE",
 *      "company": "",
 *      "nickname": "NICKNAME",
 *      "username": "USERNAME",
 *   },
 *   urlParams: {
 *      code: 'xxx', // These parameters are obtained from the url and need to be stored by the developer for use
 *      id_token: 'ID_TOKEN',
 *      access_token: 'ACCESS_TOKEN'
 *   }
 * }
 *
 * if session not exist，return：
 *
 * {
 *   session: null
 * }
 * */

After obtaining the user information, you can get the user's identity credential (the token field ), which you can carry in subsequent requests sent by the client to the backend server token, for axios example :

const axios = require("axios");
axios
  .get({
    url: "https://yourdomain.com/api/v1/your/resources",
    headers: {
      Authorization: "Bearer ID_TOKEN"
    }
  })
  .then(res => {
    // custom codes
  });

The legitimacy of this needs to be checked in the back-end interface to verify the user's identity. For details of the verification method, see Verifying User Identity Credentials (token) . After identifying the user's identity, you may also need to perform permission management on the user to determine whether the user has permission to operate this API.

¶ Sign out

This method is an asynchronous function, please make sure to use await to wait for the return before proceeding to the next step.

let res = await auth.logout();
/**
 * {
 *    message: "Single Sign out success",
 *    code: 200
 * }
 * */

¶ API

¶ Initialize constructor

The constructor accepts an object as a parameter. The list of parameters in the object is as follows:

Example:

let auth = new AuthingSSO({
  appId: "APP_ID",
  appDomain: "example-app.authing.cn"
});

¶ login

Request the authorized address of the application to log in.

Parameter list:

Example:

auth.login();

¶ register

Call this function to redirect directly to the registration page.

Parameter list:

Example:

auth.register();

¶ trackSession

Example:

let res = await auth.trackSession();
/**
 * {
 *    session: { appId: 'xxx', type: 'oidc/oauth', userId: 'yyy'},
 *    userInfo: {
 *      "_id": "USER_ID",
 *      "email": "USER_EMAIL",
 *      "registerInClient": "CLIENT_ID",
 *      "token": "JTW_TOKEN",
 *      "tokenExpiredAt": "2019-10-28 10:15:32",
 *      "photo": "PICTURE",
 *      "company": "",
 *      "nickname": "NICKNAME",
 *      "username": "USERNAME",
 *   },
 *   urlParams: {
 *      code: 'xxx', // hese parameters are obtained from the url and need to be stored by the developer for use
 *      id_token: 'ID_TOKEN',
 *      access_token: 'ACCESS_TOKEN'
 *   }
 * }
 *
 * if session not exist，return：
 *
 * {
 *   session: null
 * }
 * */

¶ logout

This method is an asynchronous function, please make sure to use await to wait for the return before proceeding to the next step.

Example:

let res = await auth.logout();
/**
 * {
 *    message: "Single Sign out success",
 *    code: 200
 * }
 * */

¶ Get help

1. Join us on forum: #authing-chat (opens new window)