使用 OAuth: 在 WebSphere Application Server 中启用 OAuth 服务提供程序

IBM® WebSphere® Application Server 7.0.0.25、8.0.0.5 和 8.5.0.1 添加了 OAuth 2.0 服务提供程序支持。本文简述了 OAuth 支持,重点强调了支持该功能所需的架构、新特性和最低配置步骤要求。本文还提供了调试技巧、资源链接和高级配置指南。 本文来自于 IBM WebSphere Developer Technical Journal 中文版

Jeff Hoy, 高级安全架构师, IBM

Jeff Hoy 是 IBM Security Solutions CTO 办公室的一位高级安全架构师。他在 IBM 的工作经验超过 10 年,拥有门户、协作、新一代技术和跨产品安全性支持方面的丰富经验。Jeff 与他的妻子和女儿居住在北卡罗来纳州郊区,他热爱高崖跳伞运动。



Bill O'Donnell, 高级技术专家, IBM

Author photoBill O'Donnell 是一位高级技术专家,也是 WebSphere 产品开发团队的首席 WebSphere Foundation 安全架构师。他负责 WebSphere 产品的安全架构。Bill 在大规模大型机和分布式系统方面拥有超过 25 年的从业经验,他特别关注开发架构和基础架构。Bill 擅长端到端的架构和应用程序安全性。他发表过大量红皮书,还是 “Secrets of SOA” 一书的作者。Bill 是 WebSphere Application Server 安全性网站的创办人之一。



Shane B. Weeden, 高级安全架构师, IBM

Shane WeedenShane Weeden 是 IBM 安全解决方案团队的一名高级软件工程师和产品架构师。他从 1992 年起开始钻研 IT 安全性,自 2000 年起开始从事 IBM 安全产品相关工作,这些产品包括 IBM Security Access Manager 和 Federated Identity Manager。Shane 现在负责关注客户的合作项目和核心产品开发工作。他拥有澳大利亚昆士兰大学的信息技术学士学位。


developerWorks 专家作者

2013 年 6 月 18 日

简介

OAuth 一直是 Web 应用程序委托授权的事实标准。除了委托访问权限之外,OAuth 也越来越多地用于传统身份验证和授权角色,云和移动技术的普遍化趋势更推动了这种形势。2012 年,OAuth 2.0 规范最终敲定,许多企业很快就采用了新协议。

为了支持该规范,IBM WebSphere Application Server 7.0.0.25、8.0.0.5 和 8.5.0.1 增加了对 OAuth 2.0 服务提供程序功能的支持。要利用此功能,必须启用和配置 OAuth 特性。

本文介绍了将 WebSphere Application Server 配置为 OAuth 服务提供程序所需的关键步骤。

先决条件

本文假设您对 OAuth 2.0 协议有基本认识,例如,了解 OAuth 客户端与 OAuth 服务提供程序之间的差别。尽管不了解协议也能按照本文所述的配置步骤完成学习,但大体了解本协议对于评估 OAuth 对企业安全性的影响有着重要意义。参考资料 部分提供了出色的简介材料。

此外,本文还假设您对 WebSphere Application Server 有大体了解,特别是安装 WebSphere Application Server、创建配置文件、启动和停止服务器。

要使用 WebSphere Application Server 内的 OAuth 2.0 支持,您必须具备以下先决条件:

  • WebSphere Application Server V7.0.0.25、V8.0.0.5、V8.5.0.1 或更高的版本
  • 完整的配置文件。

高级架构和特性

首先,我们将简单介绍 WebSphere Application Server 中的 OAuth 实现,帮助您了解配置步骤对 WebSphere Application Server 的影响。这对于调试和调优配置设置有很大的帮助。

WebSphere Application Server 以全新运行时服务的形式提供了 OAuth 服务提供程序支持。如果系统中配置了任何 OAuth 提供程序,则将在服务器启动时初始化 OAuth 服务。

如图 1 所示,WebSphere Application Server 中的 OAuth 组件包括:

  • OAuth 运行时:OAuth 数据和终端控制器。
  • 配置 XML:定义 OAuth 配置。
  • 客户端数据库或文件存储:用于注册新客户端。
  • 令牌存储(数据库或文件)。
  • 授权和 Consent servlet:处理 http://servername /oauth2/endpoint/<provider_name>/authorize 处用于人机浏览器交互的 OAuth 终端。
  • 令牌请求 servlet:处理 http://servername /oauth2/endpoint/<provider_name>/token 处用于客户端编程交互的 OAuth 终端。
  • OAuth MBean:编程配置服务。
图 1. WebSphere Application Server 中的 OAuth 组件
WebSphere Application Server 中的 OAuth 组件

WebSphere Application Server 中可用的 OAuth 相关特性包括:

  • 完整的 OAuth 2.0 规范合规性,包括对所有核心授权类型的支持:授权代码、隐式授权、资源所有者密码凭据和客户端凭据。
  • Bearer 令牌规范合规性。
  • 对公开和机密客户端的支持。
  • 刷新令牌支持。
  • 对通过终端和数据隔离区分的多个 OAuth 提供程序的多租户支持。
  • 完整的集群支持。
  • 令牌和客户端的内存中动态缓存。
  • 令牌和客户端的 XML 文件或数据库存储。
  • 通过直接 XML 编辑、wsadmin 命令或运行时 MBean 进行配置。
  • 可定制的 servlet UI。
  • 样例配置文件。
  • 管理员或用户执行的令牌撤销。
  • 样例管理页面和 API。
  • 无需重新启动服务器即可重新配置。
  • 支持身份验证的可配置 Trust Association Interceptor (TAI),包括各提供程序的受保护 URL 和令牌处理。
  • 定义 TAI 配置参数的高级规则语法。

尽管 WebSphere Application Server 提供了保护托管应用程序所需的全部 OAuth 功能,但并未全面覆盖所有可能的 OAuth 配置。对于高级部署(例如将托管 OAuth 作为非 WebSphere Application Server 产品的 SSO 解决方案,或者将 OAuth 与高度定制的数据存储库一起使用),请考虑 IBM Tivoli® Federated Identity Manager 产品。

以下内容仅介绍了基本配置所需的最基础的设置步骤,这里所说的基本配置是指独立服务器以及使用基于文件的持久存储的单一 OAuth 提供程序。有关高级设置的信息,请参阅 WebSphere Application Server 信息中心内的 OAuth 主题。


启用 OAuth 提供程序

第 1 步:初始设置

  1. 确保您的 WebSphere Application Server 版本与 上文 列出的最低版本相符。
  2. 本文使用 WebSphere Application Server DefaultApplication 中的 “snoop” servlet 进行 OAuth 验证。DefaultApplication 随 WebSphere Application Server 自动安装,但生产环境中通常会移除它。就 OAuth 配置而言,这是一个可选组件;但考虑到验证 OAuth 网络活动的目的,建议使用此组件。
  3. 验证您的应用服务器中已经启用了应用程序安全性。WebSphere Application Server 默认情况下并未启用应用程序安全性。
  4. 在 WebSphere Application Server 管理控制台中,导航到 Security > Global security(如图 2 所示)。管理控制台的默认 URL 是 https://<server_name>:9043/admin
  5. 选择 Enable application security,保存更改,然后重新启动服务器。如果跳过这一步,在 WebSphere Application Server 中依然会启用 OAuth 令牌生成,但服务器不会处理 OAuth 令牌请求。
图 2. 启用应用程序安全性
启用应用程序安全性

第 2 步:定义 OAuth 提供程序

  1. 在 app_server_root/properties 文件夹中,复制一个 OAuthConfigSample.xml 文件的副本,重命名该副本,然后将其存储在相同的文件夹中。您选择的文件名将成为 OAuth 提供程序的名称。例如,本例中的提供程序名称为 “DemoProvider”,其配置文件名为 “DemoProvider.xml”。(请注意,OAuth 提供程序名称是区分大小写的。)
  2. 打开提供程序的 XML 文件,花几分钟时间熟悉其中的内容(参见图 3)。这个 XML 文件包含一系列 OAuth 参数,它们以名称值对 (name:value) 的形式存储在 XML 中。这些参数使用合理的默认值,创建 OAuth 提供程序时大多不需更改这些参数。
    图 3. OAuth 配置设置
    OAuth 配置设置
  3. 为启用易于验证的基本配置,请对配置文件作出以下更新(如图 4 所示):
    1. 第 79 行至第 83 行:删除 “implicit” 和 “client_credentials” 值。oauth20.grant.types.allowed 参数控制可用的 OAuth 授权类型,作为一项安全性最佳实践,OAuth 提供程序应该仅启用将用到的授权类型。这里启用了 authorization_code,作为通用的三分支 OAuth 流,此外还启用了密码流,以简化默认配置的测试。所有配置值都可以在初始设置之后进行更改。
    2. 第 105 行至第 110 行:注释掉 filter 和 oauthOnly 参数。这些参数告知 OAuth 提供程序保护包含字符串 “snoop” 的 URL,并为受保护的 URL 启用其他身份验证方法。这些设置也可在 OAuth Trust Association Interceptor 配置参数中指定,但在 OAuth 配置文件中启用设置要更容易一些,能够更快地投入正常运行。
    3. 第 122 行:注释掉 oauth20.mediator.classnames 参数及其值。该参数支持根据资源所有者密码凭据流中已经配置的用户注册库验证用户。
    图 4. 更新后的 OAuth 配置参数
    更新后的 OAuth 配置参数
  4. 保存文件。该配置现在就代表着一个保护 /snoop servlet 的简单 OAuth 服务提供程序。

第 3 步:启用 OAuth 提供程序

为了根据新创建的配置文件启用 OAuth 提供程序,需要执行两组操作。首先,需要在整个系统中启用 OAuth 功能。在 WebSphere Application Server 中启用 OAuth 之后,之后的步骤就是注册新 OAuth 配置。

若要启用 OAuth 服务,请执行以下操作:

  1. 停止服务器。
  2. 导航到 app_server_root/bin 目录。
  3. 运行清单 1 中的命令。
    清单 1. 运行 wsadmin
    wsadmin -conntype NONE -f
    installOAuth2Service.py install <nodeName> <serverName>
    -profileName <profileName>

    在上述命令中:
    • nodeName 是目标应用服务器的节点名称。
    • serverName 是目标应用服务器的服务器名称。
    • profileName 是安装了 OAuth 服务提供程序的配置文件名称。
    • clusterName 是安装了 OAuth 服务提供程序的集群名称。

运行完成后,该命令应显示如下消息: ADMA5013I:Application WASOauth20SP installed successfully.

若要启用 OAuth Trust Association Interceptor,请执行以下操作:

  1. 如果尚未停止服务器,请先停止服务器。
  2. 输入以下命令,从 app_server_root/bin 目录启动 wsadmin 命令行实用工具:
    wsadmin -lang jython -conntype NONE
  3. 在 wsadmin 提示符中输入以下命令:
    AdminTask.enableOAuthTAI()
  4. 使用以下命令保存配置:
    AdminConfig.save()
  5. 使用以下命令退出 wsadmin 命令实用工具: quit

这些命令在成功运行时不会打印任何有意义的输出。

现在,WebSphere Application Server 中已经启用了 OAuth 功能。

接下来,在 <was_profile_root>/config/cells/<cell_name> 中找到 cell configuration 文件夹。其中的 oauth20 子文件夹用于存储 OAuth 配置。如果您的部署中没有此文件夹,您可以创建这个文件夹:
<was_profile_root>/config/cells/<cell_name>/oauth20

最后,将 app_server_root/properties 文件夹中的两个配置文件复制到 <was_profile_root>/config/cells/<cell_name>/oauth20 文件夹中:

  • OAuthProvider.xml,请使用您选择的文件名。将这个文件复制到 oauth20 文件夹会导致 WebSphere Application Server 在服务器启动过程中生成一个 OAuth 提供程序。
  • base.clients.xml。此文件用于在文件系统中存储 OAuth 客户端。

新创建的 OAuth 提供程序现已可以使用。该提供程序将在服务器启动时载入。然而,为了有效利用提供程序,您首先需要添加 OAuth 客户端。

第 4 步:添加 OAuth 客户端

您可以使用 base.clients.xml 文件手动定义 OAuth 客户端。打开 oauth20 文件夹中的这个新文件,查看定义 OAuth 客户端的语法。花一分钟时间熟悉语法,然后根据您需要的设置添加新客户端(如图 5 所示)。

图 5. 添加客户端
添加客户端

切记,出于基本安全方面的原因,不应以明文形式存储客户端密码。在实际测试环境中,应该使用 WebSphere Application Server 插入式加密功能加密和存储密码。在生产环境中,也可以使用安全数据库作为替代方案,在文件系统中存储客户端凭据。为配置 OAuth 客户端和令牌的数据库持久性,请参见 WebSphere Application Server 信息中心内的 持久 OAuth 服务的 SQL 语句

id、secret 和 displayname 字段包含您根据所需客户端属性选择的值。“component” 必须与第 2 步中的 OAuth 提供程序名称匹配(并且区分大小写)。“redirect” 是 OAuth 协议中指定的客户端重定向终端。redirect 是客户端属性中对应于授权和隐式授权流的强制部分,用作安全措施,且基于 OAuth 客户端配置。(由于本文中使用客户端凭据流进行验证,因此 redirect 值无需准确体现客户端 URL。)

添加客户端之后,启动服务器。现在即可开始使用 OAuth 服务提供程序。

第 5 步:验证 OAuth 功能

典型的三分支授权 OAuth 流涉及三个方面:

  • 您刚刚配置的 OAuth 服务提供程序。
  • 最终用户(您)。
  • 通常处于单独的安全域中的 OAuth 客户端。

本文仅关注配置 OAuth 时涉及到 WebSphere Application Server 的部分,因此未介绍 OAuth 客户端的配置和使用步骤。但您的环境中应该已经具备一个可用于测试的 OAuth 客户端,如果确实具备此客户端,那么现在就可以开始投入使用。

为测试授权流,您的客户端需要用到几个配置参数:

  • Client ID:base.clients.xml 文件中指定的 OAuth 客户端 ID,在本例中是 SuperOAuthArticle。
  • Client Secret:base.clients.xml 文件中指定的 OAuth 客户端密码,在本例中是 YourFeedbackIsAppreciated。
  • Authorization Endpoint:在 WebSphere Application Server 中,授权终端始终是 http://servername/oauth2/endpoint/<provider_name>/authorize。提供程序的名称是可配置的,本例中的授权终端是 https://example.com:9443/oauth2/DemoProvider/authorize。
  • Token Endpoint:http://servername/oauth2/endpoint/<provider_name>/token;在本例中是 https://example.com:9443/oauth2/DemoProvider/token。

为快速执行设置和验证,在定义 OAuth 提供程序时启用了两分支的 Resource Owner Password Credentials 流。在这个流中,客户端凭据和资源所有者凭据均直接传递给服务器,有效地将 OAuth 客户端从协议中移除。这种方法非常适合快速执行此类测试。

在使用令牌终端请求 OAuth 令牌时,强制要求使用 HTTP POST。使用 cURL 命令行工具轻松运行 HTPP POST 命令,并从服务器获取访问令牌。(大多数基于 Linux® 和 UNIX® 的系统都提供了 cURL。如果使用基于 Windows® 的 WebSphere Application Server,可以直接 下载 cURL。)

使用 cURL,对令牌终端运行 HTTP POST,使用密码凭据流,使用您的客户端 ID、密码、用户 ID 和密码替代其参数。用户 ID 和密码应该是 WebSphere Application Server 存储库中的用户凭据。清单 2 和清单 3 分别提供了示例命令和输出。

清单 2. 示例命令
curl -k -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8"
-d "grant_type=password&client_id=SuperOAuthArticle
&client_secret=YourFeedbackIsAppreciated&username=admin&password=admin"
https://example.com:9443/oauth2/endpoint/DemoProvider/token
清单 3. 示例输出
{"access_token":"ej3yNolPszGOzyO5FIJ1pExKktnvtE8N26NnCdua","token_type":"bearer",
"expires_in":3599,"scope":"","refresh_token":
"wX6LoFw6Il6RKpN4AzDbZxNK5Tzt6Chhkpiy9ocYjfcmQodMFn"}

如果响应与此不同,例如 403 或 401 HTTP 错误,请检查 OAuth 规范,了解错误结果的意义。WebSphere Application Server 系统日志也应包含错误说明。

不同于令牌请求,使用访问令牌访问受保护的终端时,可以通过多种方法提供访问令牌:作为标头值、作为 HTTP POST 参数或者作为 URL 参数。URL 参数较容易在浏览器中测试,因此本例将在 URL 中提供 OAuth 令牌,从而验证 OAuth 的功能。

首先,使用 Web 浏览器,尝试访问服务器 https://<server_name>:9443/snoop 处安装的 snoop servlet:

  • 如果载入了 snoop servlet,并且显示 HTTP 请求信息,那么您可能忘记了在 WebSphere Application Server 管理控制台中启用应用程序安全性。snoop servlet 不允许未经授权的访问。
  • 另外也有可能是由于您在该浏览器会话中已经登录了 WebSphere Application Server。如果是这种情况,请注销管理控制台、清理会话 cookie,或者尝试使用另一个尚未通过 WebSphere Application Server 身份验证的浏览器。

snoop servlet 的响应应该是身份验证提示,或者消息 “Error 403:AuthenticationFailed”。这是正确的响应,表示 snoop servlet 是受保护的 URL。现在,尝试使用 OAuth 令牌访问 servlet。

获取 cURL 命令打印到控制台中的 access_token 参数值,将其作为 URL 参数附加到 snoop URL。在本例中,OAuth 访问令牌是 “ej3yNolPszGOzyO5FIJ1pExKktnvtE8N26NnCdua”,因此 URL 就是:

https://<server_name>:9443/snoop?access_token=ej3yNolPszGOzyO5FIJ1pExKktnvtE8N26NnCdua

在浏览器中载入此 URL,snoop 应用程序现在应该正确呈现,无任何问题。在 Request Information 部分末尾处的 “User Principal” 行中,servlet 应该打印出最初请求访问令牌的用户 ID,如图 6 所示。

图 6. snoop servlet 打印出的 OAuth 用户主体
snoop servlet 打印出的 OAuth 用户主体

如果您看到的结果与此相似,那么祝贺您!您的 OAuth 服务提供程序已经启用,功能完全正常。


调试

如果需要调试 OAuth 功能,请启用跟踪字符串 “com.ibm.ws.security.oauth20.*” 的所有跟踪消息。产生配置问题的最常见原因就是受保护 URL 的 TAI 配置错误。启用跟踪后,WebSphere Application Server trace.log 文件将给出 TAI 在何时、何处处理了(或未处理) OAuth 请求的详细信息。


结束语

本文介绍了将 WebSphere Application Server 配置为 OAuth 2.0 服务提供程序所需的最基本的步骤。本文跳过了许多您可能关注的细节,例如:令牌将在多长时间内保持有效?是否启用了刷新令牌?以及其他一些细节。作为提供程序,OAuth 具有许多调优选项和部署考虑事项。

简而言之,您进行了如下配置:

  • 启用授权和资源所有者密码凭据流的 OAuth 服务提供程序。
  • oauth20 文件夹的 base.clients.xml 中存储的客户端。在投入生产之前,请务必将客户端密码加密。
  • 存储在内存中的令牌。令牌由动态缓存提供支持,而缓存由文件系统提供支持,因此令牌将在服务器重新启动后保持有效。只要 WebSphere Application Server 正确关闭,动态缓存就能维持数据完整性。在生产环境中运行 OAuth 时,建议使用数据库。
  • 令牌的有效时间为 1 小时。
  • 刷新令牌的有效时间为一周。
  • OAuth 提供程序保护 “/snoop” URL。
  • 所有这些设置均可以通过修改 oauth20 文件夹中 OAuthProvider.xml 文件的值进行更改。

如本文所述,您可以利用许多高级 OAuth 配置设置,WebSphere Application Server 信息中心提供了其他许多详细信息。如果您计划在高级部署中实现 OAuth,请考虑采用 Tivoli Federated Identity Manager,该产品为所需定制程度较低的 OAuth SSO 环境添加了许多细粒度调优选项,支持多种不同类型的 OAuth 实施点,并且具有内置高可用性。

参考资料

学习

获得产品和技术

讨论

条评论

developerWorks: 登录

标有星(*)号的字段是必填字段。


需要一个 IBM ID?
忘记 IBM ID?


忘记密码?
更改您的密码

单击提交则表示您同意developerWorks 的条款和条件。 查看条款和条件

 


在您首次登录 developerWorks 时,会为您创建一份个人概要。您的个人概要中的信息(您的姓名、国家/地区,以及公司名称)是公开显示的,而且会随着您发布的任何内容一起显示,除非您选择隐藏您的公司名称。您可以随时更新您的 IBM 帐户。

所有提交的信息确保安全。

选择您的昵称



当您初次登录到 developerWorks 时,将会为您创建一份概要信息,您需要指定一个昵称。您的昵称将和您在 developerWorks 发布的内容显示在一起。

昵称长度在 3 至 31 个字符之间。 您的昵称在 developerWorks 社区中必须是唯一的,并且出于隐私保护的原因,不能是您的电子邮件地址。

标有星(*)号的字段是必填字段。

(昵称长度在 3 至 31 个字符之间)

单击提交则表示您同意developerWorks 的条款和条件。 查看条款和条件.

 


所有提交的信息确保安全。


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=10
Zone=WebSphere
ArticleID=934411
ArticleTitle=使用 OAuth: 在 WebSphere Application Server 中启用 OAuth 服务提供程序
publish-date=06182013