<img class="image" id="oauth2__image_lvw_xnw_2sb" src="https://obs-cn-shanghai.fincloud.pinganyun.com/pacloud/20220910180811-149ff119922c.png" width="800"> <section class="section" id="oauth2__section_s1k_znw_2sb"><h2 class="doc-tairway">准备工作</h2> <p class="p">1、登录界面，在使用oauth2插件前，系统需要保证使用的用户已登录业务系统。（第2步）</p> <p class="p">2、授权界面，系统需要收集oauth2插件需要的内容，然后post到kong服务器获取token信息和跳转信息。（第3-7步）</p> <p class="p">即Kong的oauth2插件认证接口只是负责业务逻辑端的认证，不负责界面。</p> </section> <section class="section" id="oauth2__section_fsn_c4w_2sb"><h2 class="doc-tairway">流程说明</h2> <ol class="ol" id="oauth2__ol_spw_q4w_2sb"> <li class="li">如果需要用到oauth2授权，客户端需要将用户重定向到授权界面（并且需要带有client_id/response_type/scope这些参数）。这是一个授权示例界面：<img class="image" id="oauth2__image_bbw_j4w_2sb" src="https://obs-cn-shanghai.fincloud.pinganyun.com/pacloud/20220910180811-153bedd59cd0.png"></li> <li class="li">在进入授权界面前，业务系统需要保证用户已经成功登录了业务系统。</li> <li class="li">客户端需要发送类似如下请求到后端接口。<pre class="pre codeblock" id="oauth2__codeblock_tr2_l4w_2sb"><code>curl kong:8001/oauth2?client_id=XXX</code></pre></li> <li class="li">如果用户同意授权，则客户端将发送请求到后端接口（包括client_id/response_type/scope等参数）</li> <li class="li">后端接口添加provision_key和authenticated_userid这些参数到请求中，然后POST请求到Kong服务器/oauth2/authorize接口（如果已经有认证header Authorization，则需要一起加到header中）。<p class="p">示例如下:</p><pre class="pre codeblock" id="oauth2__codeblock_ezw_m4w_2sb"><code>curl https://your.service.com/oauth2/authorize \ --header "Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW" \ --data "client_id=XXX" \ --data "response_type=XXX" \ //支持code和token --data "scope=XXX" \ //此处scope必须是在Kong插件中配置确定，可以通过空格添加多个 --data "provision_key=XXX" \ // 此处必须是在Kong插件中配置确定 --data "authenticated_userid=XXX" //授权通过的用户ID --data "redirect_uri=XXXXXX" //如果需要跳转链接则传入。</code></pre><p class="p">provision_key是在Kong插件端配置的，authenticated_userid是已经被授权通过的用户ID。</p></li> <li class="li">Kong服务器会返回一个JSON结果。认证成功是200状态码，认证失败是401状态码。<pre class="pre codeblock" id="oauth2__codeblock_lxp_p4w_2sb"><code> { "redirect_uri": "http://some/url" } { "code": "XXXXXXXXX" }</code></pre></li> <li class="li">后端需要将用户请求重定向到Kong服务器返回的跳转地址。</li> <li class="li">客户端后续只与Kong服务器交互获取access token，不会再与后端服务交互。</li> <li class="li">如果已经获取了Access Token，客户端可以发送请求到upstream service获取数据。</li> <li class="li">如果Access Token过期了，客户端程序可以调用Kong服务器重新获取Access Token。<p class="p">grant_type支持authorization_code、client_credentials、refresh_token、password</p><p class="p">client_id与相关的redirect_uri需要在服务治理端管理。</p></li> </ol> </section> <section class="section" id="oauth2__section_f3p_cpw_2sb"><h2 class="doc-tairway">插件配置字段</h2> <table class="table" id="oauth2__table_mw1_fpw_2sb"><caption></caption><colgroup><col><col><col><col><col></colgroup><thead class="thead"> <tr class="row"> <th class="entry align-left" id="oauth2__table_mw1_fpw_2sb__entry__1">字段名</th> <th class="entry align-left" id="oauth2__table_mw1_fpw_2sb__entry__2">字段类型</th> <th class="entry align-left" id="oauth2__table_mw1_fpw_2sb__entry__3">默认值</th> <th class="entry align-left" id="oauth2__table_mw1_fpw_2sb__entry__4">是否必填</th> <th class="entry align-left" id="oauth2__table_mw1_fpw_2sb__entry__5">说明</th> </tr> </thead><tbody class="tbody"> <tr class="row"> <td class="entry align-left" headers="oauth2__table_mw1_fpw_2sb__entry__1 ">scopes</td> <td class="entry align-left" headers="oauth2__table_mw1_fpw_2sb__entry__2 ">string array</td> <td class="entry align-left" headers="oauth2__table_mw1_fpw_2sb__entry__3 "></td> <td class="entry align-left" headers="oauth2__table_mw1_fpw_2sb__entry__4 "></td> <td class="entry align-left" headers="oauth2__table_mw1_fpw_2sb__entry__5 ">用户端权限范围名称列表</td> </tr> <tr class="row"> <td class="entry align-left" headers="oauth2__table_mw1_fpw_2sb__entry__1 ">mandatory_scope</td> <td class="entry align-left" headers="oauth2__table_mw1_fpw_2sb__entry__2 ">boolean</td> <td class="entry align-left" headers="oauth2__table_mw1_fpw_2sb__entry__3 ">true</td> <td class="entry align-left" headers="oauth2__table_mw1_fpw_2sb__entry__4 ">Y</td> <td class="entry align-left" headers="oauth2__table_mw1_fpw_2sb__entry__5 ">是否必须选择一个权限范围</td> </tr> <tr class="row"> <td class="entry align-left" headers="oauth2__table_mw1_fpw_2sb__entry__1 ">provision_key</td> <td class="entry align-left" headers="oauth2__table_mw1_fpw_2sb__entry__2 ">string</td> <td class="entry align-left" headers="oauth2__table_mw1_fpw_2sb__entry__3 "></td> <td class="entry align-left" headers="oauth2__table_mw1_fpw_2sb__entry__4 ">Y</td> <td class="entry align-left" headers="oauth2__table_mw1_fpw_2sb__entry__5 ">唯一，授权请求必传，用于和此配置做匹配。</td> </tr> <tr class="row"> <td class="entry align-left" headers="oauth2__table_mw1_fpw_2sb__entry__1 ">token_expiration</td> <td class="entry align-left" headers="oauth2__table_mw1_fpw_2sb__entry__2 ">number</td> <td class="entry align-left" headers="oauth2__table_mw1_fpw_2sb__entry__3 ">7200</td> <td class="entry align-left" headers="oauth2__table_mw1_fpw_2sb__entry__4 ">Y</td> <td class="entry align-left" headers="oauth2__table_mw1_fpw_2sb__entry__5 ">Token有效时间，超过这个时间后需要刷新token</td> </tr> <tr class="row"> <td class="entry align-left" headers="oauth2__table_mw1_fpw_2sb__entry__1 ">enable_authorization_code</td> <td class="entry align-left" headers="oauth2__table_mw1_fpw_2sb__entry__2 ">boolean</td> <td class="entry align-left" headers="oauth2__table_mw1_fpw_2sb__entry__3 ">false</td> <td class="entry align-left" headers="oauth2__table_mw1_fpw_2sb__entry__4 ">Y</td> <td class="entry align-left" headers="oauth2__table_mw1_fpw_2sb__entry__5 "></td> </tr> <tr class="row"> <td class="entry align-left" headers="oauth2__table_mw1_fpw_2sb__entry__1 ">enable_implicit_grant</td> <td class="entry align-left" headers="oauth2__table_mw1_fpw_2sb__entry__2 ">boolean</td> <td class="entry align-left" headers="oauth2__table_mw1_fpw_2sb__entry__3 ">false</td> <td class="entry align-left" headers="oauth2__table_mw1_fpw_2sb__entry__4 ">Y</td> <td class="entry align-left" headers="oauth2__table_mw1_fpw_2sb__entry__5 "></td> </tr> <tr class="row"> <td class="entry align-left" headers="oauth2__table_mw1_fpw_2sb__entry__1 ">enable_client_credentials</td> <td class="entry align-left" headers="oauth2__table_mw1_fpw_2sb__entry__2 ">boolean</td> <td class="entry align-left" headers="oauth2__table_mw1_fpw_2sb__entry__3 ">false</td> <td class="entry align-left" headers="oauth2__table_mw1_fpw_2sb__entry__4 ">Y</td> <td class="entry align-left" headers="oauth2__table_mw1_fpw_2sb__entry__5 "></td> </tr> <tr class="row"> <td class="entry align-left" headers="oauth2__table_mw1_fpw_2sb__entry__1 ">enable_password_grant</td> <td class="entry align-left" headers="oauth2__table_mw1_fpw_2sb__entry__2 ">boolean</td> <td class="entry align-left" headers="oauth2__table_mw1_fpw_2sb__entry__3 ">false</td> <td class="entry align-left" headers="oauth2__table_mw1_fpw_2sb__entry__4 ">Y</td> <td class="entry align-left" headers="oauth2__table_mw1_fpw_2sb__entry__5 "></td> </tr> <tr class="row"> <td class="entry align-left" headers="oauth2__table_mw1_fpw_2sb__entry__1 ">hide_credentials</td> <td class="entry align-left" headers="oauth2__table_mw1_fpw_2sb__entry__2 ">boolean</td> <td class="entry align-left" headers="oauth2__table_mw1_fpw_2sb__entry__3 ">false</td> <td class="entry align-left" headers="oauth2__table_mw1_fpw_2sb__entry__4 ">Y</td> <td class="entry align-left" headers="oauth2__table_mw1_fpw_2sb__entry__5 ">是否隐藏credentials，因为credentials是kong层面的概念，此处控制是否不传递到后端。</td> </tr> <tr class="row"> <td class="entry align-left" headers="oauth2__table_mw1_fpw_2sb__entry__1 ">accept_http_if_already_terminated</td> <td class="entry align-left" headers="oauth2__table_mw1_fpw_2sb__entry__2 ">boolean</td> <td class="entry align-left" headers="oauth2__table_mw1_fpw_2sb__entry__3 ">false</td> <td class="entry align-left" headers="oauth2__table_mw1_fpw_2sb__entry__4 "></td> <td class="entry align-left" headers="oauth2__table_mw1_fpw_2sb__entry__5 ">默认情况下，只接收HTTPS请求。如果不是HTTPS请求，则需要是可信IP，并且在header中存在x-forwarded-proto=https</td> </tr> <tr class="row"> <td class="entry align-left" headers="oauth2__table_mw1_fpw_2sb__entry__1 ">anonymous</td> <td class="entry align-left" headers="oauth2__table_mw1_fpw_2sb__entry__2 ">string</td> <td class="entry align-left" headers="oauth2__table_mw1_fpw_2sb__entry__3 "></td> <td class="entry align-left" headers="oauth2__table_mw1_fpw_2sb__entry__4 "></td> <td class="entry align-left" headers="oauth2__table_mw1_fpw_2sb__entry__5 "></td> </tr> <tr class="row"> <td class="entry align-left" headers="oauth2__table_mw1_fpw_2sb__entry__1 ">global_credentials</td> <td class="entry align-left" headers="oauth2__table_mw1_fpw_2sb__entry__2 ">boolean</td> <td class="entry align-left" headers="oauth2__table_mw1_fpw_2sb__entry__3 ">false</td> <td class="entry align-left" headers="oauth2__table_mw1_fpw_2sb__entry__4 "></td> <td class="entry align-left" headers="oauth2__table_mw1_fpw_2sb__entry__5 ">是否所有代理服务共用credential</td> </tr> <tr class="row"> <td class="entry align-left" headers="oauth2__table_mw1_fpw_2sb__entry__1 ">auth_header_name</td> <td class="entry align-left" headers="oauth2__table_mw1_fpw_2sb__entry__2 ">string</td> <td class="entry align-left" headers="oauth2__table_mw1_fpw_2sb__entry__3 ">authorization</td> <td class="entry align-left" headers="oauth2__table_mw1_fpw_2sb__entry__4 "></td> <td class="entry align-left" headers="oauth2__table_mw1_fpw_2sb__entry__5 ">AccessToken从这个header中获取值</td> </tr> <tr class="row"> <td class="entry align-left" headers="oauth2__table_mw1_fpw_2sb__entry__1 ">refresh_token_ttl</td> <td class="entry align-left" headers="oauth2__table_mw1_fpw_2sb__entry__2 ">number</td> <td class="entry align-left" headers="oauth2__table_mw1_fpw_2sb__entry__3 ">1209600</td> <td class="entry align-left" headers="oauth2__table_mw1_fpw_2sb__entry__4 ">Y</td> <td class="entry align-left" headers="oauth2__table_mw1_fpw_2sb__entry__5 "></td> </tr> </tbody></table> </section> <section class="section" id="oauth2__section_fm5_gpw_2sb"><h2 class="doc-tairway">开启的接口</h2> <p class="p">启动插件后会自动开启如下接口接收请求。</p> <table class="table" id="oauth2__table_uxh_3pw_2sb"><caption></caption><colgroup><col><col></colgroup><thead class="thead"> <tr class="row"> <th class="entry align-left" id="oauth2__table_uxh_3pw_2sb__entry__1">接口名</th> <th class="entry align-left" id="oauth2__table_uxh_3pw_2sb__entry__2">接口说明</th> </tr> </thead><tbody class="tbody"> <tr class="row"> <td class="entry align-left" headers="oauth2__table_uxh_3pw_2sb__entry__1 ">/oauth2/authorize</td> <td class="entry align-left" headers="oauth2__table_uxh_3pw_2sb__entry__2 ">只支持POST形式。为Authorization Code流程提供authorization codes。或者是为</td> </tr> <tr class="row"> <td class="entry align-left" headers="oauth2__table_uxh_3pw_2sb__entry__1 ">/oauth2/token</td> <td class="entry align-left" headers="oauth2__table_uxh_3pw_2sb__entry__2 ">POST请求用于获取AccessToken</td> </tr> </tbody></table> </section>