@10duke/web-client-pkce 中文文档教程

Question

10Duke Identity and Entitlement client library for browser-based applications

该库的主要特点是：

• Authentication / Single Sign-On using OpenID Connect Authorization Code Flow with Proof Key for Code Exchange (PKCE)
• Single Sign-Out
• License consumption
• License release

客户端库目前涵盖许可证使用和发布的基本用例。

该库使用 Fetch API 进行 HTTP 请求。

Installation

npm i @10duke/web-client-pkce

Example

此库由 10Duke Identity and Entitlement React 示例客户端 使用。

Basic usage, authentication

上面链接的示例给出了如何使用此客户端库的真实示例。 下面给出了用于身份验证的库使用示例：

import { Authenticator } from "@10duke/web-client-pkce";
import { Authentication } from "@10duke/web-client-pkce";

// Create authenticator for OpenID Connect authentication and OAuth authorization
// against the 10Duke server
const authenticator = new Authenticator(
  new URL("https://10duke-account.example.com/user/oauth20/authz"),
  new URL("https://10duke-account.example.com/user/oauth20/token"),
  new URL("https://10duke-account.example.com/user/oauth20/signout"),
  new URL("https://10duke-account.example.com/.well-known/jwks.json"),
  "my-client-id",
  new URL("https://my-client.example.com/logincb"),
  "openid profile email https://apis.10duke.com/auth/openidconnect/organization"
);

/**
 * Start login against 10Duke. Browser is directed to 10Duke for login. When login
 * is complete, 10Duke returns the browser back to the client redirect_uri
 * ("https://my-client.example.com/logincb" in this example). As dictated by the
 * OpenID Connect spec, client is required to store some state for later use.
 */
async function startLogin(state?: string): Promise<void> {
  const startLoginState = await authenticator.startLogin("MyState");
  localStorage.setItem("startLoginState", JSON.stringify(startLoginState));
  window.location.href = startLoginState.url.toString();
}

/**
 * ...eventually browser is directed back to the client, and client needs to handle
 * OpenID Connect response from 10Duke. An example response URL:
 * https://my-client.example.com/logincb?code=abc123&state=MyState
 *
 * In real life, this response handling would probably not be in the same
 * context / component / code file as starting the login.
 * See the sample projects for a real-life example.
 *
 * @param code Authorization code received as "code" query parameter in
 *     the OpenID Connect response from the server
 * @param state State received as "state" query parameter in the OpenID Connect
 *     response from the server (optional, only included in the response if client
 *     specified state when starting login)
 */
async function completeLogin(
  code: string,
  state: string
): Promise<Authentication> {
  // Read the state stored when starting login
  const storedLoginState = localStorage.getItem("startLoginState");
  const startLoginState = JSON.parse(storedLoginState) as StartLoginResponse;
  localStorage.removeItem("startLoginState");

  // Complete authentication by exchanging the code to an access token and ID token
  return await authenticator.completeAuthentication(
    startLoginState,
    code,
    state
  );
}

// completeLogin must be called with actual values read from the response URL.
// Here "abc123" and "MyState" represent values of "code" and "state" query parameters,
// respectively.
const authn = await completeLogin("abc123", "MyState");
// The Authentication object can now be used for accessing user details and
// OAuth access token, for example:
const email = authn.getUserEmail();
const accessToken = authn.getAccessToken();

Basic usage, licensing

上面链接的示例给出了如何使用此客户端库的真实示例。 下面给出了用于许可的库使用示例：

import { LicenseChecker } from "@10duke/web-client-pkce";
import { LicenseCheckResult } from "@10duke/web-client-pkce";
import { LicenseReleaseResult } from "@10duke/web-client-pkce";

// Create license checker for checking, consuming and releasing licenses
const licenseChecker = new LicenseChecker(
  // accessToken received from the server (see the authentication / authorization example)
  accessToken,
  new URL("https://10duke-account.example.com/authz"),
  new URL("https://10duke-account.example.com/.well-known/jwks.json"),
  // Optional hw parameter for identifying the client hardware, for example hash derived
  // from baseboard serial number. Can be omitted for browser applications.
  "MyHardwareId"
);

/**
 * Consumes license for the given licensed item.
 *
 * @param licensedItem Name of licensed item to consume. Typically this is name of
 *    the client application or a licensed feature of the client application.
 */
async function consumeLicense(
  licensedItem: string
): Promise<LicenseCheckResult> {
  return licenseChecker.consumeLicense(licensedItem);
}

// Here "MyCoolApp" represents name of the license to check
const licenseCheckResult = await consumeLicense("MyCoolApp");
const licenseGranted = licenseCheckResult.hasLicense("MyCoolApp");
const leaseId = licenseCheckResult.jti;

/**
 * Releases an earlier consumed license.
 *
 * @param leaseId Lease id received when consuming the license
 */
async function releaseLicense(leaseId: string): Promise<LicenseReleaseResult> {
  return licenseChecker.releaseLicense(leaseId);
}

// Use the earlier received leaseId to release license
const licenseReleaseResult = await releaseLicense(leaseId);
const licenseReleased = licenseReleaseResult(leaseId);