@adrianjost/oauth2-firebase 中文文档教程

Question

oauth2-firebase

该库为 Firebase 提供 OAuth2 服务器实现。 要点是：

• Supporting Google Sign-In, GitHub Login and Facebook Login to authenticate users as Federation ID provider using Firebase Authentication.
• Providing each endpoint for Cloud Functions.
• Storing information into Cloud Firestore.
• Supporting Authorization Code Grant, Implicit Grant and Client Credentials grant of OAuth 2.0.

How to install

本节介绍如何使用此库。

Prerequisite

您必须已经有一些启用 Cloud Functions、Cloud Firestore 和 Firebase Authentication 的 Firebase 项目。 特别是，有必要在 Firebase 身份验证上启用联邦 ID 提供商的 Google 登录或 Facebook 登录。

Install this library

这个库一直作为 JavaScript 库在 npm 存储库中提供。 你可以安装这个库 使用 npm 命令。 我们代表您的项目目录 ${PROJECT_HOME}。

$ cd ${PROJECT_HOME}
$ cd functions
$ npm install oauth2-firebase --save

Define endpoints as Cloud Functions

这个库为 OAuth 2.0 提供了一些端点。 每个端点都是 express 的处理函数。

如果您使用 TypeScript 编写您的函数，请将以下代码添加到您的 functions/index.ts 文件中。

$ vi index.ts

您需要编写的代码如下：

Google 登录

import * as functions from "firebase-functions";
import {authorize, Configuration, googleAccountAuthentication, token} from "oauth2-firebase";

Configuration.init({
  crypto_auth_token_secret_key_32: functions.config().crypto.auth_token_secret_key_32,
  project_api_key: functions.config().project.api_key
});

exports.token = token();
exports.authorize = authorize();
exports.authentication = googleAccountAuthentication();

...

Facebook 登录

import * as functions from "firebase-functions";
import {authorize, Configuration, facebookAccountAuthentication, token} from "oauth2-firebase";

Configuration.init({
  crypto_auth_token_secret_key_32: functions.config().crypto.auth_token_secret_key_32,
  project_api_key: functions.config().project.api_key
});

exports.token = token();
exports.authorize = authorize();
exports.authentication = facebookAccountAuthentication();

...

GitHub 登录

import * as functions from "firebase-functions";
import {authorize, Configuration, githubAccountAuthentication, token} from "oauth2-firebase";

Configuration.init({
  crypto_auth_token_secret_key_32: functions.config().crypto.auth_token_secret_key_32,
  project_api_key: functions.config().project.api_key
});

exports.token = token();
exports.authorize = authorize();
exports.authentication = githubAccountAuthentication();

...

通过上面的代码，定义了以下端点：

• https://.../token - Token endpoint.
• https://.../authorize - Authorization endpoint.
• https://.../authentication - Login page for Google Sign-In.

Generate a shared key

该库使用共享密钥来导航页面。 您需要为共享密钥生成一个随机字符串。 该字符串的长度必须为 32。 例如：

$ cat /dev/urandom | base64 | fold -w 32 | head -n 1

Set a configuration value to your project

生成随机字符串后，您需要使用以下 firebase 命令将该字符串设置为共享密钥。

firebase functions:config:set crypto.auth_token_secret_key_32=<YOUR_GENERATED_RANDOM_STRING>

此外，您需要设置您的 Firebase 项目的 API Key 值。 您可以通过以下方式检索 API 密钥值 以下步骤：

1. Go to the setting page of your Firebase project: https://console.firebase.google.com/project/<YOUR_PROJECT_ID>/settings/general/
2. Get the string of the field labeled Web API Key.

然后，执行以下命令注册配置：

firebase functions:config:set project.api_key=<YOUR_API_KEY>

Deploy your project

编写代码并设置配置后，将您的项目部署到 Firebase。

$ firebase deploy --only functions

Operations

操作OAuth2.0服务器需要设置数据库如下：

• Register your client
• Set a description for each scope

Register your client

在OAuth2.0中，每个客户端都必须提前注册。 这个库使用 Cloud Firestore 作为存储 对于客户定义。 在当前版本中，您需要使用 Firebase 控制台注册客户端定义 手动。 要注册客户端定义，请在“客户端”集合中添加一个新文档，如下所示：

• Collection: clients
• Doc ID: Auto-generated. This will be used as a Client ID value.
• Fields:
• user_id - The user ID which represents this client as a user.
• provider_name - The provider name who this client provides.
• client_secret - The client secret string. You need to generate this string as the shared key, and need to share the provider.
• redirect_uri - If this client supports Authorization Code grant and Implicit grant, you need to set this redirect_uri string.
• grant_type - This is an object. Each key represents a grant type, and each value is boolean whether the grant type is supported or not. You need to set these entries: authorization_code, password, client_credentials and refresh_token.
• response_type - This is an object. Each key represents a response type, and each value is boolean whether the response type is supported or not. You need to set these entries: code and token.
• scope - This is an object. Each key represents a scope, and each value is boolean whether the scope is supported or not. You need to set the entry: profile.

以下是表示上述值的示例 JSON 字符串：

{
  "user_id": "client@123",
  "provider_name": "Google, Inc.",
  "client_secret": "foobar123456",
  "redirect_uri": "https://foobar.com/foo/bar/baz",
  "grant_type": {
    "authorization_code": true,
    "password": false,
    "client_credentials": true,
    "refresh_token": true
  },
  "response_type": {
    "code": true,
    "token": true
  },
  "scope": {
    "profile": true
  }
}

Set a description for each scope

该库显示一个同意页面，询问他们是允许还是拒绝范围。 您需要使用 Firebase 控制台手动为每个范围注册描述。 要注册范围描述，请在“范围”集合中添加新文档，如下所示：

• Collection: scopes
• Doc ID: Auto-generated.
• Fields:
• name - Scope name (ex. "profile").
• description - Scope description (ex. "User profile information (User ID and Nickname)").

以下是表示上述值的示例 JSON 字符串：

{
  "name": "profile",
  "description": "User profile information (User ID and Nickname)"
}

Use Additional Endpoints

该库提供了一些额外的端点：

• userinfo - Userinfo API endpoint.
• tokeninfo - Tokeninfo API endpoint.

Userinfo API endpoint

在 OpenID Connect 规范中，userinfo 端点是定义。 它提供经过身份验证的用户的信息。 您可以通过编写以下代码轻松提供 userinfo API 端点：

import {userinfo} from "oauth2-firebase";
...
exports.userinfo = userinfo();

此 userinfo 端点用作受保护的资源端点。 也就是说，访问令牌是使用此端点所必需的。 例如：

$ curl -X POST -H "Authorization: Bearer <YOUR_ACCESS_TOKEN>" https://.../userinfo

如果访问令牌有效，您将检索到以下结果：

{
  "sub": "<AUTHENTICATED_USER_ID>",
  "name": "<AUTHENTICATED_USER_NAME>"
}

Tokeninfo API endpoint

tokeninfo API 端点提供传递的访问令牌的信息。 通过这个端点，您可以确认 传递的访问令牌是否为您的客户颁发。 您可以通过以下方式轻松提供 tokeninfo API 端点 编写以下代码：

import {tokeninfo} from "oauth2-firebase";
...
exports.tokeninfo = tokeninfo();

tokeninfo API 端点接受访问令牌作为名为“access_token”的查询参数。 例如：

curl https://.../tokeninfo?access_token=<YOUR_ACCESS_TOKEN>

如果访问令牌有效，您将检索到以下结果：

{
  "aud": "<CLIENT_ID>",
  "sub": "<USER_ID>",
  "expires_in": "<EXPIRES_IN_VALUE>",
  "scope": "<SCOPE_VALUES>"
}

您可以通过比较aud 值来检查访问令牌是否适用于您的客户端。

Configurations

您可以配置此库的每个行为。

Set expires_in values to access tokens

您可以为每个授权类型的访问令牌设置每个 expires_in 值（单位：秒）。 例如：

const expiresInMap = new Map<string, number>();
expiresInMap.set("authorization_code", 2678400);
expiresInMap.set("implicit", 86400);
expiresInMap.set("password", 86400);
expiresInMap.set("client_credentials", 2678400);
expiresInMap.set("refresh_token", 2678400);
Configuration.init({
  ...
  tokens_expires_in: expiresInMap
});

在这个库中，默认值是：

• Authorization Code Grant: 86400
• Implicit Grant: 3600
• Password: 86400
• Client Credentials: 86400
• Refresh Token: 86400

Customize the consent page design

这个库提供了一个非常简单的同意页面设计。 但是，您可以自定义设计。 例如，你 可以从您的代码中为同意页面提供您自己的模板字符串。

要自定义页面设计，您需要创建一个实现 ConsentViewTemplate 接口的新类。 例如，类代码将如下所示：

import {ConsentViewTemplate} from "oauth2-firebase/dist/endpoint/views/consent_view_template";

export class MyConsentViewTemplate implements ConsentViewTemplate {

  provide(): Promise<string> {
    return new Promise<string>((resolve, reject) => {
      resolve(`<!DOCTYPE html>

<html lang="ja">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1">
    <title>Authorization page</title>
</head>
<body>
<p><%= providerName %> requests the following permissions:</p>
<ul>
    <% for (const key of scopeString.split(" ")) { %>
    <li><%= scopes.get(key) %></li>
    <% } %>
</ul>
<p>Could you allow them?</p>
<form method="post" action="/authorize/consent">
    <input type="hidden" name="auth_token" value="<%= encryptedAuthToken %>">
    <input type="hidden" name="user_id" value="<%= encryptedUserId %>">
    <button type="submit" name="action" value="allow">Allow</button>
    <button type="submit" name="action" value="deny">Deny</button>
</form>
</body>
</html>
`)
    })
  }

}

模板字符串写为“ejs”模板。 该库在呈现时将以下值绑定到模板。

• providerName: string - The provider name of the client.
• scopeString: string - The scope string devided by space the client code specifies.
• scopes: Map<string, string> - The map object which has a set of the scope name and its description.
• encryptedAuthToken: string - The encrypted auth token. You need to set this as the hidden parameter.
• encryptedUserId: string - The encrypted user ID. You need to set this as the hidden parameter.

并且，您需要将实例设置为 Configuration 类实例，如下所示：

import * as functions from "firebase-functions";
import {authorize, Configuration, googleAccountAuthentication, token, userinfo} from "oauth2-firebase";
import {MyConsentViewTemplate} from "./my_consent_view_template"

Configuration.init({
  crypto_auth_token_secret_key_32: functions.config().crypto.auth_token_secret_key_32,
  project_api_key: functions.config().project.api_key,
  views_consent_template: new MyConsentViewTemplate()
});

exports.token = token();
exports.authorize = authorize();
exports.authentication = googleAccountAuthentication();
exports.userinfo = userinfo();

...

Add Your Protected Resource Endpoint

在此库中，默认提供受 userinfo 保护的资源端点。 但是，您可以添加自己的受保护 资源端点。 每个受保护的资源都会收到请求，包括为用户/客户端颁发的访问令牌， 针对使用受保护的资源检查访问令牌是否有效，并实际返回资源 和/或创建一些资源或做某事。 这个库提供了一个方便的抽象类。 你可以定义你的 通过创建一个扩展抽象类并实现以下两个方法的新类来访问端点：

• validateScope() - Check whether the passed scopes are valid to call this endpoint.
• handleRequest() - The code body to access to target resources.

要在 Cloud Functions 上发布端点，您需要通过 endpoint 属性检索端点函数。 结果，您的代码将如下所示：

import * as express from "express";
import {AbstractProtectedResourceEndpoint} from "oauth2-firebase";
import {ProtectedResourceEndpointResponse} from "oauth2-nodejs";

class FriendsEndpoint extends AbstractProtectedResourceEndpoint {

  protected validateScope(scopes: string[]): boolean {
    return scopes.indexOf("frields") !== -1;
  }

  protected handleRequest(req: express.Request, endpointInfo: ProtectedResourceResponse): Promise<string> {
    return new Promise<string>((resolve, reject) => {
      fetchFrields(endpointInfo.userId).then(friends => {
        resolve(JSON.stringify(friends));
      }).catch(e => {
        reject(e);
      })
    });
  }

}

exports.friends = new FriendsEndpoint().endpoint;

如果传递的访问令牌无效，则不会调用 handleRequest() 函数并返回错误响应 通过抽象类。