Moodle之OAuth认证配置与实现

Posted 2023-02-16 禹爸爸

Moodle之OAuth认证配置与实现

• • 参考文档
  • 引言
  • 创建Github OAuth App
  • 配置OAuth2认证服务
  • • 第一步，创建自定义认证服务
    • • 添加服务端点
      • 用户字段映射
    • 第二步，启用OAuth 2身份认证插件
  • 验证OAuth 2配置
  • 结论

Moodle 自身提供了 CAS 和 OAuth2 两种认证插件。本文记录了我在 Moodle 中配置与实现 OAuth2 的过程与步骤，供小伙伴们参考。如果错误的地方，还请斧正。

参考文档

• OAuth 2 API
• OAuth 2 services
• OAuth 2 authentication
• OAuth2 Github Service
• Availabel Scopes for Github

引言

在 Moodle 中实现 OAuth 认证的前提是我们必须有一个能够提供 OAuth 服务的平台，可以是微信、微软、脸书这样公共平台，也可以是自建的单点登录或是统一身份认证平台。本文使用 GitHub 提供的身份认证服务为例进行阐述。

创建Github OAuth App

在 GitHub 上创建OAuth App，获取客户端ID及以密钥。操作步骤就不赘述了，直接上截图。


注册完OAuth App之后，就可以看到客户端ID及以密钥了，需要先复制出来，后面配置Moodle时需要使用到。

在满足了这个前提之后，我们只需要在 Moodle 上完成以下两步操作即可实现 OAuth 认证。

1. 配置OAuth2认证服务
2. 开启OAuth2认证插件

配置OAuth2认证服务

第一步，创建自定义认证服务

以管理员身份登录 Moodle ，依次点击 Site Administration / Server / OAuth 2 Services，进入到 OAuth 2 Services 页面。这个页面中会罗列出所有已定义好的OAuth2服务，同时页面下方提供了创建相应认证服务的功能按钮 创建Google服务 、创建Miscrosoft服务 、创建Facebook服务 、创建Next Cloud服务 和 创建自定义服务 。

点击页面下方的 Create new customer service 按钮，进入到添加服务页面（以下截图是已创建好的认证服务的编辑页面）。

带有感叹号的是必填字段，其他字段根据需求填写，下表给出了每个字段的详细解释。

字段名称	字段说明	必填
Name	服务名称，如LinkedIn、Google等。如果勾选了 在登陆页上展示 ，该名称会显示在登录页面中	是
Client ID	OAuth2服务中对应的应用编号	是
Client Secret	OAuth2服务对应的密钥	是
Authenticate token requests via HTTP headers	允许通过HTTP协议获取授权令牌，对于大多数配置，将此复选框禁用，除非明确建议您选中它	否
Scopes included in a login request	有些服务可能需要在登录请求中添加额外的授权范围才会允许读取用户的基本资料。对于遵循 OpenID Connect 规范的服务，标准的授权范围是“openid profile email”	是
Scopes included in a login request for offline access	每个OAuth服务获取无人值守授权的方式不同。比如微软平台需要添加 offline_access 的范围	是
Additional parameters included in a login request	有些服务可能需要在登录请求中添加额外的参数才会允许读取用户的基本资料	否
Additional parameters included in a login request for offline access	有些服务请求无人值守授权的方式可能会不同。比如 Google 需要额外添加 access_type=offline&prompt=consent 的参数。请使用 URL 查询参数的格式指定这些参数	否
Service base URL	用于访问服务的基地址	否
Login domains	指定允许使用该服务登陆的账户域名，以英文半角逗号分隔。留空不限制	否
Logo URL	显示在登录按钮上的图标URL	否
Show on login page	启用OAuth 2认证插件后，用户可以在登陆页面上选择此服务进行登陆	否

添加服务端点

在添加好自定义认证服务之后，我们需要添加 服务端点。什么是 服务端点呢？我可以把这个理解为单点登录平台提供的服务函数入口，每个 服务端点 实现一个具体的功能，如获取和交换访问令牌、获取用户信息等。

根据 Moodle 的官方文档说明，认证服务至少要提供三个 服务端点，并且要按照约定的命名规则进行命名。这三个端点分别是：

• authorization_endpoint ：获取授权端点，这个是统一身份认证平台提供用户登录的页面地址，通常会包含两个参数：

  • client_id ：应用ID，该应用程序在统一身份认证平台的唯一标识，由统一身份认证平台提供。
  • redirect_uri ：重定向地址，授权成功后浏览器会转向该地址。

• token_endpoint ： 获取令牌端点，确认授权还在有效期。这个服务会被多次调用，用以获取最新的令牌。

• userinfo_endpoint ：获取用户信息端点，用于获取用户相关属性信息，如用户名、邮箱、电话号码等，具体的返回内容由统一身份认证平台定义。

以下时序图可以清晰地展示出上述三个 服务端点 的使用。

敲黑板

在 OAuth 服务中定义重定向地址应该是 DOMAIN_NAME/admin/oauth2callback.php。如果你的域名是 https://moodle.example.com ，那么重定向地址就应该是 https://moodle.example.com/admin/oauth2callback.php。

以管理员身份登录 Moodle ，依次点击 Site Administration / Server / OAuth 2 Services，进入到 OAuth2服务 页面，点击相应认证服务右侧的图标按钮（如下图所示）。

点击页面下方 Create new endpoint for issuer “Github” 按钮，逐一添加上文提到的三个 服务端点。

用户字段映射

如果希望在完成身份认证的同时也在 Moodle 数据库中创建相应的本地用户帐号，那就需要完成 用户字段映射。这一步是告诉 Moodle 如何将统一身份认证平台提供的用户数据与本地帐户字段做一个对应关系。

以管理员身份登录 Moodle ，依次点击 Site Administration / Server / OAuth 2 Services，进入到 OAuth2服务 页面，点击相应认证服务右侧的图标按钮（如下图所示）。

点击页面下方 Create new user field mapping for issue “Github” 按钮，逐一添加上字段映射关系。红色框圈中的六个字段分别对应着用户的城市、邮件、名、头像、GitHub用户信息对应的URL地址和用户名。

第二步，启用OAuth 2身份认证插件

完成了第一步的配置工作之后，我们需要在 Moodle 中开启OAuth 2身份认证插件。

以管理员身份登录 Moodle ，依次点击 Site Administration / Plugins / Authentication，进入到 管理身份认证 页面，找到 oAuth 2 插件点击“眼睛”图标启用该插件。（如下图所示）。

在该页面的下面，还有两个选项是需要关心一下的。

• Prevent account creation when authenticating，这个选项默认是“否”，这意味着在通过LDAP、OAuth等其他身份认证方式登录时，会在 Moodle 本地数据库中创建一个同名的用户帐户。如果勾选了此选项，则在不会在本地数据库中创建同名用户帐号。
• Alternate login URL，这里可以填写单点登录或是统一身份认证的地址，这样就会使用指定的登录页面代替 Moodle 自带的登录页面。留空表示使用 Moodle 默认的登录页面。一定要在OAuth配置正确且可以正常登录的情况填写该字段，否则有可能再也无法登录系统。
  

验证OAuth 2配置

在开启OAuth 2身份认证插件之后，我们就可以在 Moodle 默认的登录页面中看到我们配置的OAuth认证服务的入口按钮（如下图所示）。

点击 GitHub 按钮，浏览器会导航到github的登录页面。

输入GitHub的用户名和密码并点击 Sign in 按钮完成身份认证。通过认证后浏览器会打开如下页面，要求用户确认授权第三方应用读取GitHub的用户信息。

同意授权之后，浏览器会跳转回 Moodle 页面，并告之用户到邮箱中收取邮件以确认使用该邮件地址创建Moodle帐号。

点击邮件中的的链接地址完成帐号注册确认步骤，如果在浏览器中看到以下页面说明帐号确认完成。

结论

以上，就是我在 Moodle 中配置 OAuth 服务认证的完整过程。在此在总结一下注意点：

1. 需要在提供OAuth服务的平台上注册需要接入的业务系统，填写正确的回调地址，并获取 client ID 和 secret Key 。
2. 为认证服务添加服务端点。如果是自定义服务，请一定要保证有以下三个必须的服务端点：authorization_endpoint、token_endpoint和userinfo_endpoint 。
3. 维护用户字段映射关系，以确保能够正确在 Moodle 中创建新的用户帐号。
4. 需要在 Moodle 中配置好邮件服务，确保系统能够正确发送确认邮件给用户。