7pass-node-sdk 中文文档教程

Question

7Pass NodeJS SDK

7Pass NodeJS SDK 是一个用于与 7Pass SSO 服务。 你可以使用这个库来 为您的网站实施身份验证并利用 7Pass SSO 提供的已有功能。

Installation

要安装包，请运行以下命令：

npm install 7pass-node-sdk

Running the example application

为了演示库的功能，有一个 交互式教程/指南可用。 在我们开始设置之前 它起来，你需要你的网络应用程序的客户端。 客户代表 与您要验证的服务关联的实体 到。

要获取客户端凭据，您首先需要联系 7Pass 技术团队。

获得可用凭据后，您可以继续运行应用程序。

首先需要安装 SDK 库依赖项：

npm install

然后转到 example_app 目录并安装示例应用程序依赖项：

cd example_app
npm install

创建本地配置文件：

cp config.local.js.example config.local.js

编辑 config.local.js 文件在你最喜欢的编辑器中填写 细节。 您应该掌握所有参数 在您的客户端设置之后。 为了进行测试，请将环境设置为 <代码>质量保证。 一旦完成，您就可以启动应用程序了：

npm start

示例应用程序现在应该可以在 <代码>http://localhost:8000。 该应用程序将指导您完成 该库最常见的用例并向您展示代码示例和 沿途的服务器响应。

API Usage

强烈建议您首先查看示例应用程序。 它 将向您展示带有更多注释和实际值的 API 调用。 它 还将向您展示来自 7Pass SSO 服务的真实响应 你进步。

要使用该库，必须使用 我们要使用的客户端的凭据。 如果你没有 还没有凭据，请参阅上文。

• client_id (required)
• client_secret (required)

如果您正在开始开发，那么工作总是一个好主意 针对 7Pass SSO 服务的非实时实例。 指定 您要针对其发出的实例（环境） 请求，您可以将一个名为 environment 的附加键传递给 配置。 目前有两个环境在运行：QA 和 生产。 不要忘记之前切换到生产版本 您向公众发布您的应用程序。

var sevenpass = require('7pass-node-sdk');

var config = {
  client_id: 'YOUR_CLIENT_ID',
  client_secret: 'YOUR_CLIENT_SECRET',
  environment: 'qa' // Optional, defaults to 'production'
};

// 1. Create and initialize the configuration object
// Configuration object fetches OpenID Configuration and JWT public key endpoints
sevenpass.Configuration.createAndInit(config, function(err, ssoConfig) {
  if(err) {
    throw err;
  }

  // 2. Create 7Pass SSO object passing initialized Configuration object
  var sso = new sevenpass.SSO(ssoConfig);

  //your app code continues here.
});

对于这两种环境，都有一个默认的 host URL，可以在其中访问 7Pass API 端点。 对于 production 环境，它是 https://sso.7pass.de，对于 qa，主机是 https://sso.qa.7pass.ctf.prosiebensat1.com。 如果需要，可以通过在配置中指定 host 来覆盖它，如下所示：

var config = {
    host: 'https://mysubdomain.7pass.de',
    // ... other config values
};

Authentication flow

身份验证过程很简单，高级视图如下 如下：用户被重定向到 7Pass SSO 服务，使用 特制的 URL 和他/她登录（或注册）。 一旦用户 已完成该过程，他/她将被重定向回您的 URL 中带有特殊代码的应用程序。 然后应用程序将 使用代码以获取用户的详细信息。 该过程可能会有所不同 取决于传递的选项。

1. Get a redirect URL

该库自动处理 URL 的生成 需要重定向用户。 唯一需要的参数是 redirect_uri 网址。 URL 必须是绝对的，可以是任意的 （假设它已向客户注册）但按照惯例 导致同一主机和称为“回调”的路由。

使用状态 参数是可选的，但建议避免 CSRF 攻击

• the value is usually stored in the session and is also used with sso.authorization().callback() method when handling the callback request.

options = {
  redirect_uri: 'https://example.com/callback', // Required.
  scope: 'openid profile email', // Optional, default value.
  response_type: 'code' // Optional, default value.
  state: sessionState // Optional, but recommended to avoid CSRF attacks
};

redirectUrl = sso.authorization().authorizeUri(options);

该库将自动设置 client_id 和 nonce（a 唯一请求标识符）参数自动。

2. Redirect an user

现在是时候将用户重定向到生成的 URL 了。

3. Handling 7Pass callback

用户完成登录/注册对话框后，他/她 被重定向到带有标志结果的 redirect_uri URL 过程中。 用户可能已成功通过身份验证，但也 可能已决定取消该过程或可能出现其他错误 已经发生了。 因此，正确的错误处理很重要。

每当发生错误时，都会出现两个查询参数 在 URL 中 - error 和 error_description。 错误参数 包含一个错误代码并且 error_description 包含一个人 适合直接显示的错误的可读描述 用户。

您可以选择手动处理错误，如下所示。 否则，如果出现错误， sso.authorization().callback() 回调收到 AuthorizeCallbackException 错误。

// 1. Check if query params contain callback error
if(queryParams.error) {
  var error = queryParams.error;
  var errorDescription = queryParams.error_description;

  // 2. Handle the error and display appropriate message to your end-user.
}

该库自行处理检索令牌，您只需要提供 redirect_uri 以及请求中的查询参数。 这允许您检索可用于稍后获取有关用户的实际信息的令牌。 这些令牌特定于特定用户并且是私有的。 您需要妥善保管它们，不要与任何人分享。

sessionState 参数是可选的，但应该提供相同的参数 如果与 sso.authorization().authorizeUri() 方法一起使用。 提供状态值时收到 AuthorizeCallbackException 回调错误，并且 从查询参数中检索到的不匹配。

// queryParams variable below contains query parameters from the current URL

// 1. Request access token
sso.authorization().callback(callbackUri, queryParams, sessionState, function(err, tokens) {
  if(err) {
    throw err;
  }

  // 2. Store tokens into the user's session storage. You might also want
  //    to store them in your persistent storage (i.e. your database) or
  //    any other storage of your own choosing.
});

收到的响应将具有以下结构。 跑过 示例应用程序以查看实际值。

{
  "access_token": ACCESS_TOKEN,
  "token_type": "Bearer",
  "refresh_token": REFRESH_TOKEN,
  "expires_in": 7200,
  "id_token": JWT_STRING,
  "received_at": RECEIVED_AT_TIMESTAMP,
  "id_token_decoded": DECODED_JWT
}

注意：id_token_decoded 值是从 id_token 解码而来的 场并验证。 如果令牌验证失败，则抛出错误。

4. Caching an access token

令牌在类型的单个对象中表示 <代码>令牌集。 您现在可以将令牌存储到用户的会话存储中。 您可能还想将它们存储在您的持久存储（即您的数据库）或 您自己选择的任何其他存储。

访问令牌在指定的一定时间内有效 expires_in 字段中的秒数。 一旦访问令牌过期，它 无法再使用。 您可以使用刷新获得一个新的 令牌如下：

var TokenSet = require('7pass-node-sdk').TokenSet;

function getFreshTokens(callback) {
  // 1. Create TokenSet object - tokensData contains hash of tokens data as retrieved from user's session
  tokens = new TokenSet(tokensData);

  // 2. Check whether the access token has expired and return immediately if not.
  if(!tokens.isAccessTokenExpired()) {
    return callback(null, tokens);
  }

  // 3. Refresh tokens
  sso.authorization().refresh(tokens, function(err, refreshedTokens) {
    if(err) {
      return callback(err);
    }

    // 4. Store the refreshed tokens back into user's session storage.

    // 5. Return fresh tokens
    callback(null, refreshedTokens)
  });
}

getFreshTokens(function(err, tokens) {
  // Now when you made sure tokens are fresh, you can use them further to create API clients.
})

注意：上面的refresh() 方法也接受像{ refresh_token: 'REFRESH_TOKEN' } 这样的对象作为参数。

5. Calling our API endpoints

现在我们确保令牌是最新的，我们可以开始制作 向 7Pass SSO 服务请求获取用户数据。

与前面的示例相同，运行示例应用程序查看 真正的服务器响应。

// Create a client object using the tokens
var accountClient = sso.accountClient(tokens);

accountClient.get('me', function(err, data) {
  // Handle error

  // 'data' variable contains the response data
});

7Pass SSO 服务提供了相当多的此类端点。 学习 更多关于他们的信息，你可以去 官方文档的概述。

Client Credentials requests

该库支持多种类型的“客户端”。 这些客户 通常在所需的配置参数和 之后在他们提供的功能中。 “客户凭证” client 是一种特殊的客户端，它与用户无关 帐户，只能用于调用“客户端”API。

您可以在 文档 accessType 参数等于 client。

var sevenpass = require('7pass-node-sdk'), sso;

var config = {
  client_id: 'YOUR_CLIENT_ID',
  client_secret: 'YOUR_CLIENT_SECRET',
  environment: 'qa' // Optional, defaults to 'production'
};

// 1. Create and initialize the configuration object
// Configuration object fetches OpenID Configuration and JWT public key endpoints
sevenpass.Configuration.createAndInit(config, function(err, ssoConfig) {
  if(err) {
    throw err;
  }

  // 2. Create 7Pass SSO object passing initialized Configuration object
  sso = new sevenpass.SSO(ssoConfig);

  // 3. Get the tokens using the client credentials grant type
  sso.authorization().clientCredentials(handleClientCredentialsAuthorization);
});

function handleClientCredentialsAuthorization(err, tokens) {
  if(err) {
    throw err;
  }

  // 4. Use the client as you normally would when using the standard access
  var clientCredentialsClient = sso.clientCredentialsClient(tokens);
  clientCredentialsClient.post('checkPassword', {
    password: 'PASSWORD'
  }, function(err, data) {
    //handle response
  });
}

Device flow

借助设备流，人们可以轻松安全地登录应用程序和服务 在输入或显示功能有限的设备上使用他们的 7Pass 帐户。 这包括智能电视、数码相框或物联网设备。

该设备（您的应用程序）指示最终用户使用另一台计算机或设备并连接 向 7Pass 批准访问请求。 由于您的应用程序无法接收 传入请求，它会反复轮询 7Pass 授权服务器，直到 最终用户完成审批流程。

您的应用程序通过请求一组验证来启动流程 通过发出 HTTP POST 请求从授权服务器获取代码 到令牌端点。

sso.authorization().deviceCode(function(err, deviceCodeResponse) {
    // handle error

    // deviceCodeReponse - see example below
});

deviceCodeResponse 将是如下对象：

{
    code: CODE         // used along with poll requests (see below)
    user_code: Q9CFLH  // the code which user should enter on LINK page 
    expires_in: 600    // expiration of the code (in seconds) 
    interval: 5        // recommended interval for repeating poll requests (in seconds)
    link: LINK_URL     // verification URL user should use to authenticate
    link_qr: IMAGE_URL // image URL of QR code encoded link
}

现在应该提示用户访问另一台设备上的 link URL 以 输入 <代码>用户代码。 link_qr 是表示二维码编码的图像的 URL link URL。 这可以供使用移动设备的用户使用，他们可以扫描它并打开 link URL 在他们的移动浏览器中，而无需自己手动输入。

当用户尝试在 link URL 上进行身份验证时，您的应用程序会反复轮询 7Pass 服务器。 推荐的间隔在 interval 值中指定。

以下示例中的 code 可以是从 sso.authorization().deviceCode() 方法调用接收到的 deviceCodeResponse 对象， 具有 code 属性的对象或只是具有 code 值的字符串。

// repeat every [interval] seconds.
sso.authorization().deviceCodePoll(code, function(err, response) {
    if (err) {
        // handle the error appropriately
        // if OAuth2 error: err.error is set to one of error codes 'code_expired', 'slow_down', 'invalid_grant'
        return;
    }

    // reponse === false in case 'authorization_pending' response is received

    if (response !== false) {
        // reponse is TokenSet object
        // stop polling - user has authorized from another device successfully
    }
});

Backoffice requests

该库还可用于执行“后台”请求。 这些 请求是在没有用户直接参与的情况下发起的，并且 用于管理目的。 你的客户需要有 backoffice_code 授权类型允许。 你还需要知道的ID 您要与之合作的用户。

后台请求用于代表其他用户进行 API 调用。 获取这些请求的访问令牌 您需要使用提供帐户 id 的特殊授权类型“backoffice代码”。 身份验证成功后，您将获得与使用上述标准流程相同的令牌集。

var sevenpass = require('7pass-node-sdk');

var config = {
  backoffice_key: 'YOUR_BACKOFFICE_KEY',
  service_id: 'YOUR_SERVICE_ID',
  environment: 'qa' // Optional, defaults to 'production'
};

// 1. Create and initialize the configuration object
// Configuration object fetches OpenID Configuration and JWT public key endpoints
sevenpass.Configuration.createAndInit(config, function(err, ssoConfig) {
  if(err) {
    throw err;
  }

  // 2. Create 7Pass SSO object passing initialized Configuration object
  var sso = new sevenpass.SSO(ssoConfig);

  // 3. Get the tokens using the backoffice
  sso.authorization().backoffice({
    account_id: 'ACCOUNT_ID' // Required, the ID of the user you want to access
  }, handleBackofficeAuthorization);
});

function handleBackofficeAuthorization(err, tokens) {
  if(err) {
    throw err;
  }

  // 4. Use the client as you normally would when using the standard access
  var aaccountClient = sso.accountClient(tokens);
  accountClient.get('me', function(err, data) {
    //handle response
  });
}

响应将像往常一样。 获得令牌后，7Pass SSO 服务将像访问令牌已使用 “标准”方式。

Client/backoffice registration

当您使用注册新用户时 客户端或后台注册 API， 您可能希望将它们反弹到 7Pass SSO 服务，以便创建用户会话并让用户登录。

此 SDK 提供了一个名为 autologinUri() 的方法，可用于生成重定向（反弹）网址。 该方法接受 TokenSet 作为其第一个参数。 您可以在使用注册 API 时检索用户的令牌 通过提供 scope 参数。 请参阅注册 API 文档以获取更多详细信息。 response_type 默认为 none 但可以设置为任何其他 支持的类型 如果需要的话。

// client is an instance of ApiClient created using sso.clientCredentialsClient() or sso.backofficeClient() methods.
client.post('registration', {
    scope: 'openid profile email'
    // other parameters
}, function(err, response) {
    //handle error

    var tokens = TokenSet.receiveTokens(response);

    var uri = sso.authorization().autologinUri(tokens, {
        redirect_uri: callbackUri, // Required
        state: sessionState // Optional but recommended to use
    }, {
        remember_me: true // Default value: false
    });

    // Redirect user to uri
});

与其他普通授权请求一样，您可以使用 sso.authorization().callback() 方法 处理回调请求。 如果 response_type 设置为 none，回调将接收 null。

Running the tests

该库使用 mocha 进行测试。

npm test