分类： 集成

OAuth2

Frappe 框架使用 oauthlib 来管理 OAuth2 相关需求。一个 Frappe 实例可以同时充当以下所有角色：

  1. 资源服务器：存放资源，例如你 DocType 中的数据。
  2. 授权服务器：颁发令牌以访问某些资源的服务器。
  3. 客户端：需要访问资源服务器上某些资源的应用。

与上述角色相关的 DocType：

  1. 通用
    • OAuth 设置：用于配置与这三种角色相关的某些 OAuth 功能。
  2. 授权服务器
    • OAuth 客户端：记录在 Frappe 实例中注册的客户端。
    • OAuth 持有者令牌：在此维护发放给已注册客户端的令牌。
    • OAuth 授权码：跟踪客户端用于换取令牌的 OAuth 授权码。
    • OAuth 提供方设置：允许跳过授权。[DEPRECATED] 请改用 OAuth 设置。
  3. 客户端
    • 已连接应用：记录此 Frappe 实例作为客户端注册到哪些授权服务器，以便访问某些资源。例如用户的 Google Drive 账户。
    • 社交登录密钥：与已连接应用类似，但用于登录 Frappe 实例。例如用户的 Google 账户，用于启用“使用 Google 登录”。
    • 令牌缓存：Frappe 实例访问已连接应用时收到的令牌。

功能特性

框架在 oauthlib 之上额外实现的功能：

  • 动态客户端注册：允许客户端自行注册，无需资源所有者手动配置。RFC7591
  • 授权服务器元数据发现：允许客户端查看实例的授权服务器（即自身）元数据，例如授权端点。RFC8414
  • 资源服务器元数据发现：允许客户端查看实例的资源服务器元数据，例如文档、授权服务器等。RFC9728

其他文档

各种 OAuth2 功能的文档：

  1. 如何设置 OAuth 2？
  2. OAuth 2
  3. 基于令牌的身份验证
  4. 将 Frappe 用作 OAuth 服务
  5. 社交登录密钥
  6. 已连接应用

警告

其中一些页面可能已过时，如有疑问，建议始终查看
代码。

OAuth 设置

一个单一 DocType，用于配置 OAuth2 相关功能。建议
直接打开该 DocType 页面，因为每个字段都有
足够详细的帮助文本。

该设置允许切换以下功能：

  • 通过跳过授权字段，在存在有效令牌时进行授权检查。注意：在生产环境中请保持此项未勾选。
  • 授权服务器元数据发现：通过切换显示授权服务器元数据字段。
  • 动态客户端注册：通过切换启用动态客户端注册字段。
  • 资源服务器元数据发现：通过切换显示受保护资源元数据。

其余字段（在资源部分中）仅在响应 /.well-known/oauth-protected-resource 上的请求时使用

关于公共客户端

公共客户端（例如 SPA）默认具有受限访问权限。此
限制通过 CORS 实现。

若要为某些受信任的客户端绕过此限制，你可以将其
主机名添加到允许的公共客户端来源字段中。

微软Office365邮箱OAuth

本指南帮助你在 Frappe 中验证 Outlook 电子邮件账户。

注意：用户应以其 Frappe 账户中的电子邮件账户用户身份登录。例如，如果电子邮件账户是 [email protected]，那么他们应使用站点上的用户 [email protected] 登录。

  1. 前往你的 Frappe 实例，创建一个新的已连接应用并保存（只需输入名称并保存），然后复制重定向 URI 以备后用。


  1. 登录 Microsoft Azure，搜索并选择Microsoft Entra ID（以前称为 Azure Active Directory）。

  1. 点击添加 -> 应用注册

  1. 输入相应的详细信息（应用名称、账户类型），粘贴之前从 Frappe 实例复制的重定向 URI，并将平台选择为“Web”。

要了解有关账户类型的更多信息，请点击此处

  1. 点击注册，你将被重定向到你创建的应用。复制你的应用程序 ID——这是你需要粘贴到 Frappe 实例上已连接应用中的客户端 ID。

  1. 前往应用中的API 权限部分，添加 Microsoft Graph 权限。

  1. 为 IMAP.AccessAsUserAll、SMTP.Send 和 offline_access 选择委派权限，然后点击“添加权限”




  1. 前往证书和密码以创建客户端密码

添加描述并点击添加，即可看到新生成的客户端密码。

复制值——将其粘贴到 Frappe 实例上新已连接应用中的 Client Secret 字段中。

  1. 点击“终结点”并复制“OpenID Connect 元数据文档”。这应粘贴到你的 Frappe 已连接应用的“OpenID 配置”字段中。之后，在已连接应用上点击“获取 OpenID 配置”，这将填充终结点。



然后，添加这些作用域，并保存文档。

  • https://outlook.office.com/IMAP.AccessAsUser.All
  • https://outlook.office.com/SMTP.Send
  • offline_access
  1. 点击右上角的“连接到 {你的已连接应用名称}”按钮，这将启动 Microsoft 的 OAuth 流程。

请确保你正在授权的电子邮件账户与你将在 Frappe 中添加的账户相同。

  1. 如果一切按计划进行，你将被重定向回你的已连接应用页面，并且应该能够看到连接到你的已连接应用的令牌缓存，前往你创建的令牌缓存，检查你是否同时拥有刷新令牌和访问令牌。

  1. 前往电子邮件账户 DocType 并创建一个新的电子邮件账户。选择方法为 OAuth，添加你的已连接应用和创建了令牌缓存的用户，并像往常一样设置你的电子邮件账户。

请确保你的 Microsoft 账户允许 IMAP/POP 连接。你可以在此处找到相关信息以及 Outlook 服务器的设置：https://support.microsoft.com/en-us/office/pop-imap-and-smtp-settings-8361e398-8af4-4e97-b147-6c6c4ac95353

注意：Microsoft 限制从除验证它的电子邮件地址以外的任何其他电子邮件地址发送邮件。为此，你可以在电子邮件账户文档本身中检查这两个选项

如需任何其他信息，请访问 Microsoft 的官方文档：https://learn.microsoft.com/en-us/exchange/client-developer/legacy-protocols/how-to-authenticate-an-imap-pop-smtp-application-by-using-oauth

服务主体身份验证

电子邮件账户需要以用户身份访问。这导致无法使用专用于 Frappe 的共享邮箱，因为需要向登录 Frappe 的用户授予完全访问权限。

此功能允许 Frappe 向例如 Exchange Online 验证自身身份，以便它可以从共享邮箱发送和接收电子邮件，而无需向访问 Frappe 的每个用户委派完全访问权限。

如果你希望使用此方法进行身份验证，Email Account 中有一个可用的复选框

设置LDAP

轻量级目录访问协议（LDAP）是一种对象目录，通常用于集中式身份验证，也就是大家常说的单点登录（SSO）。许多从小型到大型的组织都部署了 LDAP。

在 Frappe 中设置 LDAP 集成后，你就可以使用 LDAP 凭据登录你的 Frappe 应用了。

  1. 配置

LDAP 设置页面上的许多字段都是必填的。这些字段在下方会以粗体显示，方便你辨认。

配置 LDAP 设置时，如果勾选了“启用”复选框，Frappe 会验证你填入字段的数据。如果有任何数据看起来无效，设置将无法保存，并会显示一条错误信息。修正所有错误后，你就可以成功启用 LDAP 身份验证了。

LDAP 设置配置页面被分成了几个小部分。请参阅下面的标题，了解如何配置每个部分。

要设置 LDAP，请导航到：

主页 > 集成 > LDAP 设置

:memo: 提醒
在配置页面输入设置后，别忘了勾选页面顶部的启用复选框。

1.1 LDAP 服务器

Frappe 已在 OpenLDAP 和 Active Directory 上测试过。不过，任何符合标准的 LDAP 目录都可以用作 LDAP 身份验证源。

  • LDAP 目录服务器：（下拉菜单）选择与你的 LDAP 目录匹配的选项。可用选项有：

Active Directory 用于 Microsoft Active Directory

OpenLDAP 用于 OpenLDAP

自定义 如果你需要调整 LDAP 组属性，请选择此选项。例如，你的 LDAP 组设置是 groupofnames 或 uniquegroupofnames 等

  • LDAP 服务器 URL：这是你的 LDAP 服务器的 URL。格式必须为 ldap://yourserver:port 或 ldaps://yourserver:port

1.2 LDAP 身份验证

此部分包含将绑定到目录服务器的用户详细信息。

  • 基础可分辨名称（DN）：这是将绑定到 LDAP 的用户。该用户需要有权查看你在下方输入的搜索路径。
  • 基础 DN 的密码：这是上述用户的密码，用于在 LDAP 服务器上查找用户详细信息。

1.3 LDAP 搜索路径

此部分是每个 LDAP 目录对象的搜索路径。只要采用 LDAP FDN（完整可分辨名称）格式，任何 LDAP 容器对象路径都可以使用。例如 ou=my frappe objects,dc=example,dc=com。此处提供的任何路径都要求绑定用户具有读写权限。

绑定用户需要写权限，以便最终用户可以重置密码。

  • 用户 LDAP 搜索路径：这是 LDAP 服务器中所有用户必须属于的搜索路径，才能登录 Frappe 应用。
  • 组 LDAP 搜索路径：这是 LDAP 服务器中所有组必须属于的搜索路径，才能登录 Frappe 应用。
  • LDAP 搜索字符串：此字段允许 Frappe 将 Frappe 登录界面中输入的用户/电子邮件与 LDAP 服务器进行匹配。例如，你可以根据偏好使用电子邮件地址或用户名。

你可以在此处使用复杂的 LDAP 搜索过滤器，只要它们包含登录名占位符 {0} 并用大括号 () 括起来即可。它会被放在搜索过滤器中你希望匹配登录名的位置。ldap3 Python 模块支持且你的 LDAP 目录支持的任何过滤器都应该可用。例如：

(uid={0})

(SamAccountName={0}) – （Active Directory）

(&(description=*ACCESS:Frappe*)(uid={0}) – 在 OpenLDAP 中使用过滤器描述可以实现类似 Active Directory 的过滤 memberOf，因为它只会选择描述字段中包含 ACCESS:Frappe 的用户。

(&(SamAccountName={0})(memberof=cn=Domain Users,ou=Groups,DC=example,dc=com)) – （Active Directory）

1.4 LDAP 用户创建与映射

此部分包含将从目录服务器读取并映射到 Frappe 用户的 LDAP 属性。

  • LDAP 电子邮件字段：指定包含用户电子邮件地址的 LDAP 属性。mail 是常用的 LDAP 属性。
  • LDAP 用户名字段：指定包含用户用户名的 LDAP 属性。Active Directory 使用 sAMAccountName，OpenLDAP 使用 uid。
  • LDAP 名字字段：指定包含用户名字的 LDAP 字段。通常使用 givenName 或 sn。

还有许多其他非必填的 LDAP 属性可用于映射到 Frappe 用户。它们是：

  • 中间名
  • 电话
  • 手机

安全警告 请注意，如果您将 LDAP 属性 mail 用于用户名字段，这可能会带来安全隐患。mail 在 LDAP 中不是唯一值。启用 mail 属性用于登录目的超出了本文档的范围。请查阅您的目录服务器文档以了解如何操作。

1.5 LDAP 安全

本节为可选内容。但是，如果您想配置与目录服务器的安全连接，可以在此处输入 TLS 连接详情。

  • 在 LDAP 设置区域中，有两个下拉菜单。

    1. SSL/TLS 模式 – 将其设置为 StartTLS 以使用 StartTLS 连接到您的 LDAP 服务器。如果您的 LDAP 服务器不支持 StartTLS，将其设置为 StartTLS 将导致错误 StartTLS is not supported。如果您收到此错误，请检查 LDAP 服务器上的配置。
    2. 要求受信任的证书 – 如果您将其更改为

    Yes 则 LDAP 服务器提供的证书必须被 Frappe 服务器信任。

    No 不建议使用此设置，因为它绕过了确保证书由受信任的证书颁发机构签名的检查。

如果您希望使用 StartTLS 配合自签名（不受信任的）证书，请将其设置为 否。如果您不使用 StartTLS，此设置将被忽略。

  • SSL/TLS 模式
    指定您是否希望在初始连接到 LDAP 服务器时启动 TLS 会话。
  • 要求受信任的证书
    指定您是否要求使用受信任的证书来连接 LDAP 服务器

如果您指定了受信任的证书，您需要指定证书文件的路径。这些文件需要放置在您的 Frappe 服务器上，以下字段应为服务器上文件的绝对路径。证书字段包括：

  • 私钥文件路径
  • 服务器证书路径
  • CA 证书文件路径

要将您的 Frappe 实例配置为接受由您自己的”证书颁发机构”或”自签名证书”签名的证书，请查阅您的操作系统文档，了解如何将”证书颁发机构”/”自签名”证书添加到您的”受信任证书存储”中。

1.6 LDAP 自定义目录

如果您选择自定义目录服务器，本节为必填项。此处只有两个选项，它们与您的目录服务器使用的组相关。它们是：

  • 组对象类 这是您目录服务器中组的对象类。
  • 组成员属性 这是组中包含用户通用名称（CN）的 LDAP 属性。
  • 自定义组搜索 可用于指定自定义 LDAP 组搜索，某些 LDAP 提供商需要此设置。

1.7 LDAP 组映射

本节包含映射 LDAP 组的详细信息。用户所属的任何组都将映射到指定的 Frappe 角色。

Frappe 功能：如果您配置了组映射，每次用户登录时，系统都会检查其角色并根据需要添加/移除角色。

  • 创建时的默认角色：当用户在您的 Frappe 应用中创建时，将被分配此默认角色。
  • LDAP 组映射表 您可以将多个 LDAP 组映射到 Frappe 角色。输入的 LDAP 组必须与 LDAP cn 属性匹配。即 ‘Domain Users’ 而不是 ‘cn=Domain Users,ou=Groups,dc=example,dc=com’，后者是 LDAP FDN 条目。

示例

序号 LDAP 组 角色
1 Domain Users Guest
2 Domain Administrators Administrator
  • LDAP 组字段 （弃用警告） 这是用户 LDAP 对象中包含用户所属组列表的 LDAP 属性。如果您已按照上述内容配置了所有设置，此设置将不会生效。此字段仅为在当前布局之前配置了 LDAP 的用户保留。此字段将在 Frappe 的未来版本中移除。
  1. 使用 LDAP 登录 Frappe

设置并启用 LDAP 后，在登录屏幕上，系统会启用通过 LDAP 登录选项。

图 1. 配置并启用 LDAP 后的 Frappe 应用登录屏幕。

谷歌云端硬盘

Google Drive 是 Google 开发的一款文件存储和同步服务。它允许用户存储、同步和共享文件。Google Drive 是 Google Workspace 的重要组成部分，后者是 Google 面向企业推出的按月订阅服务。

你可以使用 Frappe 框架的文件选择器从 Google Drive 中选择任意文件，并将其附加到当前的 DocType 上。例如，你可以将存储在 Google Drive 中的发票 PDF 附加到 Frappe 应用中的采购发票上。

设置

Google Cloud Console

首先，我们需要获取一些凭据，以便访问 Google Drive。你可以使用设置工具，它会引导你在 Google Cloud Console 中创建项目、启用 API 并创建凭据。

如果你还没有创建应用的 API 密钥，请点击创建凭据 > API 密钥。接下来，在API 密钥部分找到你的 API 密钥。你可以打开 API 密钥并对其进行限制。

  1. 在应用限制下选择“HTTP 来源”，
  2. 在网站限制下添加你的 Frappe 实例的主机名，
  3. 在API 限制下选择“限制密钥”并勾选“Google Picker API”。

如果你还没有创建 OAuth 2.0 凭据，请点击创建凭据 > OAuth 客户端 ID。

  1. 在应用类型下选择“Web 应用”，
  2. 在已授权的 JavaScript 来源下添加你的 Frappe 实例的主机名。

创建凭据后，你可以在“凭据”页面上看到你的客户端 ID。

最后但同样重要的是，你需要配置 OAuth 同意屏幕。这是用户首次使用 Google Drive 选择器时会看到的页面。它会请求用户授权访问其 Google Drive。你可以根据自己的需要进行配置，只需注意在范围页面上添加范围 https://www.googleapis.com/auth/drive.readonly。

你还需要准备好你的应用 ID。这是你的项目编号，可以在IAM 和管理 > 设置下找到。

本节的某些内容基于 Google 创建并共享的作品进行了修改，并根据 Creative Commons 4.0 署名许可中描述的条款使用。

Frappe 实例

现在 Google Picker API 已启用，并且我们拥有了必要的凭据，接下来就可以在你的 Frappe 实例中配置Google 设置了。

  1. 打开Google 设置。
  2. 勾选启用复选框。
  3. 在“Google Drive 选择器”部分，勾选启用 Google Drive 选择器复选框。
  4. 输入你的应用 ID、客户端 ID 和 API 密钥。
  5. 保存Google 设置并重新加载浏览器窗口。

现在，当你点击侧边栏中的“附加文件”时，你应该能看到 Google Drive 图标。

如果你是第一次点击它，需要授权 Frappe 应用访问你的 Google Drive 文件。

然后 Google Drive 选择器会打开，你可以选择一个文件。

点击左下角的蓝色按钮，将该文件的链接附加到当前 DocType 上。

如果你在寻找技术细节，Google Drive 是在拉取请求 #12715 中引入的。

RazorPay

Razorpay 是印度一款广受欢迎的支付解决方案，企业可以通过其产品套件来接收、处理和发放付款。它让你可以使用信用卡、借记卡和网上银行等支付方式。

集成 Razorpay 客户端结账

Razorpay 支付

集成步骤

在你的代码中引入结账脚本

将以下脚本插入到你的页面中 <script type="text/javascript" src="/assets/js/checkout.min.js"></script>
结账脚本会自动获取 Razorpay 结账脚本，并对其 API 进行封装，提供一些语法糖。

在后端创建订单控制器

def get_razorpay_order(self):
 controller = get_payment_gateway_controller("Razorpay")

 payment_details = {
 "amount": 30000,
 ...
 "reference_doctype": "Conference Participant",
 "reference_docname": self.name,
 ...
 "receipt": self.name
 }

 return controller.create_order(**payment_details)

在客户端使用结账 API 发起支付

function make_payment(ticket) {
 var options = {
 "name": "<checkout modal title>",
 "description": "<checkout modal description>",
 "image": "<checkout modal logo>",
 "prefill": {
 "name": "<customer name>",
 "email": "<customer email>",
 "contact": "<customer phone>"
 },
 "theme": {
 "color": "<modal color>"
 },
 "doctype": "<reference doctype>", // Mandatory
 "docname": "<reference docname mandatory razorpay="new" frappe.checkout.razorpay razorpay.on_open="()"> {
 // SCRIPT TO RUN WHEN MODAL OPENS
 }
 razorpay.on_success = () => {
 // SCRIPT TO RUN ON PAYMENT SUCCESS
 }
 razorpay.on_fail = () => {
 // SCRIPT TO RUN ON PAYMENT FAILURE
 }
 razorpay.init() // Creates the order and opens the modal
}
</reference></reference></modal></customer></customer></customer></checkout></checkout></checkout>

生命周期

  1. 在后端创建订单

订单首先在服务器端创建，由 razorpay.init() 触发，为此必须为该文档类型创建一个控制器 get_razorpay_order。服务器方法会设置要收取的金额以及一个唯一的收据 ID，供 Razorpay API 使用。

get_razorpay_order 内部会调用 Razorpay 设置文档类型的 create_order 控制器，然后创建一个集成请求并向 https://api.razorpay.com/v1/orders 发送 POST 请求。

  1. 在客户端处理结账

订单创建成功后，会返回 order_id，该值会与集成请求中的订单关联存储。这个 order_id 会被传递给客户端，从而触发 Razorpay 弹窗。支付完成后，根据支付状态调用成功或失败的 API 方法，并将支付 ID 传递给它。

  1. 验证支付

API 方法被调用后，交易详情会保存在集成请求中。如果成功，则会调用 authorize_payment 控制器，该控制器使用支付 ID 从 Razorpay API 检查支付状态。一旦授权通过，集成请求会被标记为已完成，随后会调用 reference_doctype 的支付成功钩子。

你可以在他们的文档中了解更多关于 Razorpay 自定义结账的信息