使用OAuth客户端

cybozu发表于:2018年03月06日 18:36:27更新于:2022年04月11日 20:48:59

Index

使用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客户端”。

    0015bda9575f0f4a36143ea99cc6e58

  4. 输入以下的信息。

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

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

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

    0015bdabac649ef84c42df0624e0d4e

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

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

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

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

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

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

0015bdabf3cf2250b495172f696b75b

7. "整合的使用用户的设置"这个页面里,我们可以选择允许使用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.cn/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. 发行令牌

使用获得的授权码,获取令牌。
运行以下的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

Scope说明方法/URI

k:app_record:read

获取应用的记录

GET:

/k/v1/record.json

/k/v1/records.json

/k/v1/record/comments.json

/k/v1/records/acl/evaluate.json

k:app_record:write

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

POST:

/k/v1/record.json

/k/v1/records.json

/k/v1/record/comment.json


PUT:

/k/v1/record.json

/k/v1/records.json

/k/v1/record/status.json

/k/v1/records/status.json

/k/v1/record/assignees.json


DELETE:

/k/v1/record/comment.json

/k/v1/records.json

k:app_settings:read

获取应用的设置

GET:

/k/v1/app.json

/k/v1/apps.json

/k/v1/form.json

/k/v1/preview/form.json

/k/v1/app/form/layout.json

/k/v1/preview/app/form/layout.json

/k/v1/app/form/fields.json

/k/v1/preview/app/form/fields.json

/k/v1/app/status.json

/k/v1/preview/app/status.json

/k/v1/app/views.json

/k/v1/preview/app/views.json

/k/v1/app/customize.json

/k/v1/preview/app/customize.json

/k/v1/app/settings.json

/k/v1/preview/app/settings.json

/k/v1/app/acl.json

/k/v1/preview/app/acl.json

/k/v1/record/acl.json

/k/v1/preview/record/acl.json

/k/v1/field/acl.json

/k/v1/preview/field/acl.json

/k/v1/preview/app/deploy.json

k:app_settings:write

更新应用的设置

POST:

/k/v1/preview/app/form/fields.json

/k/v1/preview/app/deploy.json

/k/v1/preview/app.json


PUT:

/k/v1/app/acl.json

/k/v1/preview/app/acl.json

/k/v1/record/acl.json

/k/v1/preview/record/acl.json

/k/v1/field/acl.json

/k/v1/preview/field/acl.json

/k/v1/preview/app/form/fields.json

/k/v1/preview/app/form/layout.json

/k/v1/preview/app/settings.json

/k/v1/preview/app/customize.json

/k/v1/preview/app/views.json

/k/v1/preview/app/status.json


DELETE:

/k/v1/preview/app/form/fields.json

k:file:read文件的下载

GET:

/k/v1/file.json

k:file:write

文件的上传

POST:

/k/v1/file.json


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

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

限制事项

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

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

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

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

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


回复(4)

  • 您好,由于我希望token是通过外部Java程序,每次执行时从kintone中取得,而不是在Java程序中写死的,您推荐我用OAuth认证的方式,但关于OAuth,我有以下几个问题,麻烦帮我解答一下:


    1.往kintone系统中添加OAuth客户端时,需要设置【重定向端点】,应该是一个URL,可是我们这边是一个kintone以外的Java Applet 程序,不是网页的,可以设置那个重定向端点吗?可以的话,请问应该设置成什么?


    2.网站上写的【redirect_uri:必须。指定重定向端点。请加密URL。】


    重定向端点那个URL需要加密,请问需要用什么方式加密?解密部分是由kintone那边做吗?不然怎么跳转到正确的URL吧


    3.使用OAuth授权中有一个步骤,发送完授权申请之后,需要【用户授权】。


    【用户授权】这个步骤,是否是在kintone系统上,显示一个【用户授权】的页面,然后用户手动点击【允许】。


    4.外部Java系统,每次通过用户授权的方式,访问kintone系统的API时,是否都要发送【用户授权申请】,客户都要点击【允许】,才能取得授权码?


    5.使用kintone Java client jar包,开发的外部Java程序,其中包括OAuth授权,以及取得授权码和token的相关方法吗?有的话,可以给我个例子吗?


    谢谢

  • 您好,由于我希望token是通过外部Java程序,每次执行时从kintone中取得,而不是在Java程序中写死的,您推荐我用OAuth认证的方式,但关于OAuth,我有以下几个问题,麻烦帮我解答一下:

    1.往kintone系统中添加OAuth客户端时,需要设置【重定向端点】,应该是一个URL,可是我们这边是一个kintone以外的Java Applet 程序,不是网页的,可以设置那个重定向端点吗?可以的话,请问应该设置成什么?

    2.网站上写的【redirect_uri:必须。指定重定向端点。请加密URL。】

    重定向端点那个URL需要加密,请问需要用什么方式加密?解密部分是由kintone那边做吗?不然怎么跳转到正确的URL吧

    3.使用OAuth授权中有一个步骤,发送完授权申请之后,需要【用户授权】。

    【用户授权】这个步骤,是否是在kintone系统上,显示一个【用户授权】的页面,然后用户手动点击【允许】。

    4.外部Java系统,每次通过用户授权的方式,访问kintone系统的API时,是否都要发送【用户授权申请】,客户都要点击【允许】,才能取得授权码?

    5.使用kintone Java client jar包,开发的外部Java程序,其中包括OAuth授权,以及取得授权码和token的相关方法吗?有的话,可以给我个例子吗?

    谢谢

    引用 betsy_yan 的回复:

    如果仅仅添加数据的话,不需要什么oauth认证,你只需要在应用后台页面添加token,只使用api token认证就行了 参照https://cybozudev.kf5.com/hc/kb/article/1383387/?page=1&unique=1642674270#usage_create-client 中的  用API令牌验证创建 kintone Client, 其他认证你用不到的话 不需要都加上

  • betsy_yan

    如果仅仅添加数据的话,不需要什么oauth认证,你只需要在应用后台页面添加token,只使用api token认证就行了 参照

    https://cybozudev.kf5.com/hc/kb/article/1383387/?page=1&unique=1642674270#usage_create-client

    中的  用API令牌验证创建 kintone Client, 其他认证你用不到的话 不需要都加上


    引用 的回复:

    我要做一个kintone以外的Java程序,通过调用kintone的API,实现往kintone的某个app中添加数据。是否可以用OAuth授权的方式,取得token,调用API。如果可以的话,可以给我一个Java的通过OAuth授权,取得token,调用添加数据api的例子吗?谢谢

  • 我要做一个kintone以外的Java程序,通过调用kintone的API,实现往kintone的某个app中添加数据。是否可以用OAuth授权的方式,取得token,调用API。

    如果可以的话,可以给我一个Java的通过OAuth授权,取得token,调用添加数据api的例子吗?谢谢

注意:贴代码时请注意格式并使用"代码语言",与本文无关的问题请至“讨论社区”提问。