使用OAuth客户端

cybozu发表于:2018年03月06日 18:36:27更新于:2019年02月03日 11:22:26

Index

使用OAuth 2.0,我们在应用里向cybozu.cn发送API请求的时候,可以得到授权。

只对应了Client type是Confidential Client,grant type是Authorization Code Grant(授权码模式)。

cybozu.cn里注册OAuth客户端

为了能正常向cybozu.cn发送API请求,并得到授权,我们需要注册一个可用的OAuth客户端。

  1. 1. 登陆 “cybozu.cn共通管理”。

  2. 2. “cybozu.cn共通管理” 页面的 “系统管理”,点击 “外部整合服务”。

  3. 3. 点击 “设置高级整合” 下的 “添加OAuth客户端”。

  4. 0015bda9575f0f4a36143ea99cc6e58

      4. 输入以下的信息。

  • 客户端名称:必须。客户端的名字。

  • 客户端图标:可省略。客户端的图标图片。

  • 重定向端点:必须。发送给OAuth客户端的带有授权码的URL。当cybozu.cn的访问被授权后,将会重定向到这个URL。

  • 0015bdabac649ef84c42df0624e0d4e

点击 “保存”,添加客户端后,会生成下面的项目。

  • 客户端ID:cybozu.cn里注册应用后,生成的唯一ID。

  • 客户端密钥:cybozu.cn里注册应用后,生成的密钥。

  • 授权端点:OAuth的授权端点URL。

  • 令牌端点:OAuth的令牌端点URL。

点击追加好的客户端的 “整合的使用用户的设置” 。

0015bdabf3cf2250b495172f696b75b
整合的使用用户的设置” 这个页面里,我们可以选择允许使用OAuth的用户,然后点击 “保存”。

只有这个设定有效的用户,才可以使用OAuth客户端。  
请注意:新添加的用户此默认值为不勾选。

0015bdac008385bd6efb9869bf35252

在应用里实现OAuth的授权步骤

cybozu.cn使用的是Authorization Code Grant(授权码模式)。

Authorization Code Grant Flow(授权码模式步骤)

0015bdbe953a3c65b756516a9acc179

执行API的必要操作如下:

  1. 发送授权申请

  2. 用户授权

  3. 获取授权码

  4. 发行令牌

  5. 执行API

下面是使用curl来执行各种OAuth协议API的操作范例。

1. 发送授权申请

客户端向用户请求授权,访问以下的URL。
例,范围里指定 “g:schedule:read”。

  • client_id:必须。指定客户端ID。

  • redirect_uri:必须。指定重定向端点。请加密URL。

  • state:必须。根据OAuth 2.0的式样,为了防止CSRF,需要指定一个任意值。比如,指定 “state1”。

  • response_type:必须。指定code。

  • scope:必须。指定申请的权限范围。权限范围请参考本文的权限范围章节

https://{subdomain}.cybozu.com/oauth2/authorization
?client_id={your_client_id}&redirect_uri={your_redirect_url}&state=state1&response_type=code&scope=g%3aschedule%3aread

2. 用户授权

页面将会显示下面的授权页面,点击 “允许”,给予授权。

0015be40205e6302b3892368c796937

3. 获取授权码

用户授权以后,页面将会重定向到客户端事先指定的URL。 
这时候,URL里还会附上state参数和code参数,code参数就是授权码。
请复制并保存好code参数的值。

{your_redirect_url}?code={your_code}&state=state1

4. 发行令牌

cybozu.cn得到授权码之后,将会发行令牌。
运行以下的curl命令。
code参数使用之前复制好的code。

  • grant_type:必须。指定使用的授权模式,此处的值固定为"authorization_code"。

  • redirect_uri:必须。指定重定向端点。记得URL加密。

  • code:必须。指定上一步获得的授权码。

  • client_id:指定客户端ID。OAuth客户端的认证使用Basic认证的时候,不需要指定。

  • client_secret:指定客户端密钥。OAuth客户端的认证使用Basic认证的时候,不需要指定。

curl -X POST 
-H "Content-Type: application/x-www-form-urlencoded" "https://{subdomain}.cybozu.com/oauth2/token"
-d "grant_type=authorization_code&
    redirect_uri={your_redirect_url}&
    code={your_code}&
    client_id={your_client_id}&
    client_secret={your_client_secret}"

# response 
{
 "access_token" : "P8RSOtjFudcBkpPMjcFKjkxIy_XdctPG",
 "refresh_token" : "p51R155m0aj-XR2WV1TABR5NA9s3TAT0",
 "token_type" : "bearer",
 "expires_in" : 3600,
 "scope" : "g:schedule:read"
}

应答里包含了access_token,我们使用这个来执行API。
令牌(access_token)的有效期为1小时。
如果用户访问的时候,客户端的"访问令牌"已经过期,则需要使用"更新令牌"申请一个新的访问令牌。

curl -X POST 
-H "Content-Type: application/x-www-form-urlencoded" "https://{subdomain}.cybozu.com/oauth2/token"
-d "grant_type=refresh_token&
    refresh_token={your_refresh_token}&
    client_id={your_client_id}&
    client_secret={your_client_secret}"

# response 
{
 "access_token":"2YotnFZFEjr1zCsicMWpAA",
 "token_type" : "bearer",
 "expires_in":3600,
 "scope" : "g:schedule:read"
}

补充: 使用client_id和client_secret的客户端认证,POST参数以外也可以进行Basic认证。

5. 执行API

使用令牌运行API。在Authorization头部的Bearer处可以制定令牌。1.只有在申请授权的请求API范围里才可以运行。

例如:执行「/v1/schedule/events/{id}」。

curl -H "Authorization: Bearer {your_access_token}" "https://{subdomain}.cybozu.com/g/api/v1/schedule/events/{id}"

# response
{
  "id": [...]
}

范围

kintone

Scope说明

k:app_record:read

应用的记录查看

k:app_record:write

应用的记录添加、变更、删除

k:app_settings:read

应用设置的查看

k:app_settings:write

应用设置的更新

k:file:read文件的下载

k:file:write

文件的上传

k:file:read


Garoon

Scope说明

g:schedule:read

日程预定、设备、设备组的获取

g:schedule:write

日程预定的添加、更新、删除

g:notification:read

通知的获取

g:notification:write

通知的添加

g:base:read

用户、组织信息的获取

使用cybozu.cn共通管理的IP地址限制时的注意事项

OAuth的客户端功能必须要在cybozu.com共通管理的Basic认证或者具备安全访问的环境情况下,才可以使用。
在使用的时候,需要在『OAuth客户端』里设置可允许访问的IP地址。

限制事项

  • OAuth客户端最多可以添加20个。

  • 每个用户的1个OAuth客户端里最多可以发行10个更新令牌。

  • 授权码和令牌也有有效期。如果失效的话会返回错误信息。

    • 授权码的有效期为10分钟。

    • 令牌的有效期为1小时。


回复(1)

  • Geisa

    ds

您需要登录后才可以回复