# 配置API的OIDC认证 APIG提供一种支持OIDC协议的鉴权方式。当用户选择以这种鉴权方式来通过网关访问后端服务时，API网关会与IDP服务交互获取token和用户信息，将得到的信息附加到后端服务请求中。不仅可以获取访问权限，还能确认用户的真实身份，并确保身份信息在传输过程中的安全性和完整性。 - OIDC（OpenID Connect）：是一种身份认证协议，它在提供授权的同时，也提供了一种标准化的方式去验证终端用户的身份。OIDC引入了ID Token的概念，这是一种包含用户身份信息的JWT（JSON Web Token），使得应用可以确信"谁"正在访问，而不仅仅是可以访问什么。 - IDP（Identity Provider）：指身份认证提供者，支持与API网关交互认证信息。 - 重定向API（redirect_api）：重定向API提供给IDP服务调用，将用户重定向到预先配置的IDP进行登录。 - 登出API（logout_api）：登出API提供给用户退出登录时调用，即当用户调用该API时退出登录。 - 认证API：配置OIDC认证策略的API。 ![](https://support.huaweicloud.com/usermanual-apig/public_sys-resources/note_3.0-zh-cn.png) 如果此策略在当前实例中不支持，可[提交工单](https://support.huaweicloud.com/usermanual-ticket/zh-cn_topic_0127038618.html)升级实例到最新版本。 #### 前提条件 - 后端服务支持标准的OIDC协议。 - 已部署IDP服务。 - 同一分组中已创建三个API，分别为认证API、重定向API和登出API。具体操作，请参考[创建API](https://support.huaweicloud.com/usermanual-apig/apig_03_0128.html)。 #### 约束与限制 - 同一个环境中，一个API只能被一个OIDC认证策略绑定，但一个OIDC认证策略可以绑定多个API。 - 同一个APIG实例内最多可创建5个OIDC认证策略。如需调整配额，请[提交工单](https://support.huaweicloud.com/usermanual-ticket/zh-cn_topic_0127038618.html)，申请修改。 - IDP的token_endpoint_auth_methods_supported必须支持client_secret_basic。 - 当请求携带access_token来进行OIDC认证时，access_token的请求头名必须为Authorization。 - 任何需要绑定OIDC认证策略进行认证的API的请求路径都不能与OIDC认证策略中的重定向API和登出API的请求路径相同。 - 重定向API和登出API都是仅作为实现OIDC认证逻辑的一环而存在，重定向API提供给IDP服务调用，登出API给用户在退出登录时调用，两者都不实现具体业务逻辑，用户不能在脱离OIDC认证流程的情况下直接调用，否则报错。 - 重定向API和登出API必须使用绝对匹配、类型为公开API、请求方法为GET、请求协议为HTTPS、安全认证为无认证、后端服务类型为Mock类型（实际请求不会调用到后端服务）。 - Token校验支持的加密算法包含RS256，RS384，RS512，公钥支持使用IDP的jwks获取或者自行配置public_key。 - 访问令牌的大小最大为5KB。 - 必须保证IDP和APIG实例网络互通，且在IDP配置了重定向url（域名 + 路径）后，IDP端需要能够解析重定向url的域名。 - 策略和API本身相互独立，只有为API绑定策略后，策略才对API生效。为API绑定策略时需指定发布环境，策略只对指定环境上的API生效。 - API的下线操作不影响策略的绑定关系，再次发布后仍然会带有下线前绑定的策略。 - 如果策略与API有绑定关系，则策略无法执行删除操作。 - 当前仅广州友好、新加坡、约翰内斯堡、上海一和贵阳一区域支持OIDC认证策略。 #### 创建OIDC认证策略 1. 进入[API网关控制台](https://console.huaweicloud.com/apig2/#/overview)页面。 2. 根据实际业务在左侧导航栏上方选择实例。 3. 在左侧导航栏选择"API管理 \> API策略"。 4. 在"策略管理"页面，单击"创建策略"。 5. 在"选择策略类型"弹窗中，选择"插件策略 \> OIDC认证"。 6. 在"创建策略"弹窗中，根据下表参数说明，配置策略信息。 表1OIDC认证参数说明 | 参数 | 说明 | |:---|:---| | 策略名称 | 填写策略的名称，根据业务规划自定义。建议您按照一定的命名规则填写策略名称，方便您快速识别和查找。 | | 策略类型 | 固定为"OIDC认证"。 | | 描述 | 填写策略的描述信息。长度为1\~255个字符。 | | 策略内容 | 策略的配置内容，支持表单配置和脚本配置两种方式。 | | client_id | IDP中的客户端ID。 | | client_secret | IDP中的客户端Secret。 | | discovery | IDP开放的服务发现地址。 | | redirect_api | redirect_api为重定向API。该API会与本策略绑定，作为IDP重定向回来的入口。 - 用户需要自行将该API的URL配置为IDP client的重定向地址，如keycloak的client中的"Valid redirect URIs"参数。 - 与本策略绑定的其它业务API的路径不能与重定向API的路径相同，否则会调用失败。 - 重定向API作为OIDC认证策略功能的一环，在策略生命周期内不能删除。 | | 高级选项 || | scope | 授权码流程中应返回的身份验证用户信息。默认值是openid email profile，可以附加其他范围并用空格分隔，例如openid email profile phone。 | | logout_api | logout_api为登出API。该API会与本策略绑定，作为用户退出登录的路径，即当用户调用该API时退出登录。 - 与本策略绑定的其它业务API的路径不能与登出API的路径相同，否则会调用失败。 - 登出API作为OIDC认证策略功能的一环，在策略生命周期内不能删除。 | | public_key | Token所使用的非对称算法的公钥。 - 策略会使用public_key或者IDP的jwk来校验token，即public_key和jwks_enable这两个参数至少有一个被配置，否则无法校验token。 - 当同时配置了public_key和jwks_enable，策略会使用public_key作为公钥进行校验。 | | jwt_cache_enabled | 是否在API网关缓存token认证的认证结果。 | | jwks_enabled | 是否使用discovery服务发现地址中的jwks_uri来获取公钥进行token校验。 当IDP提供了相关的jwk配置时可以设置为true，否则需要自行配置public_key才能进行token校验。 | | auth_header_name | 用于JWT认证的token请求头名称，默认为Authorization。 | | access_token_expires_in | 访问令牌的过期时间，单位为秒。 当从IDP获取的令牌响应信息中没有过期时间时使用该值作为token过期时间，默认为3600秒。 | | redirect_after_logout_uri | 当用户调用了该插件的logout_api时，页面会重定向到该地址。 | | slient_renew_access_token_enabled | 是否在访问令牌过期时由API网关静默地更新访问令牌。 | | set_access_token_header_enabled | 是否将访问令牌设置为Authorization请求头透传到业务后端。 | | set_userinfo_header_enabled | 在授权码流程中，是否将用户信息设置为X-Userinfo请求头透传到业务后端。 | 7. 单击"确定"。 - 在策略列表中显示已创建的策略，表示策略创建成功。 - 如果您需要复制已创建的策略，请在已创建策略的"操作"列中单击"克隆"配置参数即可。**克隆策略的名称不能与已创建的策略名称重复。** 8. 策略创建后，您还需要[为策略绑定API]，才能使策略对API生效。 **策略的绑定、解绑、更新会实时生效，不需要重新发布API。** #### 脚本配置示例 ``` { "discovery": "https://example.com/realms/myrealm/.well-known/openid-configuration", "redirect_api_id": "8aa097****9843e****9c593d11b****", "scope": "openid email profile", "client_id": "myclient", "client_secret": "N9TX****wo4Lt****6iRYMDoCSux****", "logout_api_id": "8aa0****0e984****bc9c593d11b****", "access_token_expires_in":3000 } ``` #### 为策略绑定API 1. 单击策略名称，进入策略详情。 2. 在API列表区域选择环境后，单击"绑定API"。 3. 筛选API分组以及发布环境，勾选所需的API。 支持通过API名称或标签筛选API，标签为创建API时定义的标签。 4. 单击"确定"，绑定完成。 - 如果单个API不需要绑定此策略，单击API所在行的"解绑"。 - 如果批量API不需要绑定此策略，则勾选待解绑的API，单击列表上方"解绑"。最多同时解绑1000个API。 #### 相关文档 如果您希望通过API创建OIDC认证策略，请参考[创建插件](https://support.huaweicloud.com/api-apig/CreatePlugin.html)。