Index

• 在cybozu.cn里添加OAuth客户端

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

• 范围

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

• 限制事项

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

Client type仅支持Confidential Client，grant type仅支持Authorization Code Grant（授权码模式）。

在cybozu.cn里添加OAuth客户端

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

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

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

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

   
   

4. 输入以下的信息。

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

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

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

  

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

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

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

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

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

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

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

只有在此设为有效的用户，才可以使用OAuth客户端。  
请注意：新添加的用户此默认值为不勾选。

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

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

Authorization Code Grant Flow（授权码模式步骤）

执行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.cn/oauth2/authorization
?client_id={your_client_id}&redirect_uri={your_redirect_url}&state=state1&response_type=code&scope=g%3aschedule%3aread

2. 用户授权

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

3. 获取授权码

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

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

4. 发行令牌

使用获得的授权码，获取令牌。
运行以下的curl命令。

请求头部

• Authorization 头部中指定以下值：
  “Basic”和通过将客户端ID和客户端密钥以“:”（半角冒号）连接而获得的 Base64 编码值。
  例如，客户端ID为“clientid”且客户端密钥为“clientsecret”时，请指定“Basic Y2xpZW50aWQ6Y2xpZW50c2VjcmV0”。

请求正文

• grant_type：必须。指定"authorization_code"。

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

• code：必须。指定在3.中获得的授权码。

curl -X POST https://{subdomain}.cybozu.cn/oauth2/token \
 -H "Content-Type: application/x-www-form-urlencoded" \
 -H "Authorization: Basic Y2xpZW50aWQ6Y2xpZW50c2VjcmV0" \
 -d "grant_type=authorization_code&redirect_uri={your_redirect_url}&code={your_code}"

# 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 https://{subdomain}.cybozu.cn/oauth2/token \
 -H "Content-Type: application/x-www-form-urlencoded" \
 -H "Authorization: Basic Y2xpZW50aWQ6Y2xpZW50c2VjcmV0" \
 -d "grant_type=refresh_token&refresh_token={your_refresh_token}"

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

5. 执行API

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

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

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

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

范围

kintone

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

在启用了cybozu.cn共通管理的Basic认证或者SecureAccess的环境下，不可使用OAuth的客户端功能。
要使用的话，需要在『OAuth客户端』里设置可允许访问的IP地址。

限制事项

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

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

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

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

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