OAuth

Về OAuth2.0

Mô tả

Authorization flow

Trong các Authorization flow (Authorization Grant) được định nghĩa trong RFC6749, chỉ support với Authorization Code Grant.

Chức năng

Có thể sử dụng tất cả các API ChatWork hiện đang public.

Cách sử dụng API ChatWork từ Client program

1. Đăng ký Client

Hãy đăng ký Client từ Màn hình tạo Client OAuth.
Đăng ký các tham số bên dưới với thông tin Client.

Parameter Required Description
Tên client Tên của client
Redirect URI Có thể đăng ký tối thiểu 1, và tối đa 5 URI. Và nó phải là https.
Scope Cần phải đăng ký ít nhất 1 scope. Scope cần thiết để gọi tất cả API ChatWork, xin hãy tham khao ở Appendix scope list.

2. Lấy Authorization Code

Để lấy được Authorization Code, bạn cần phải access vào consent screen thông qua một Web browser.

Cách truy cập vào consent screen

Sau khi thiết lập Parameters Query cần thiết và access vào Consent screen, consent screen sẽ hiện ra.
* Trường hợp màn hình login hiện ra thì nhập thông tin xác nhận rồi login, web browser sẽ chuyển hướng đến consent screen.

Query parameters
Parameter Specified Value Required Description
response_type Strings Hiện tại chỉ xử lý với "code".
client_id Strings Hãy chỉ định client ID.
redirect_uri Strings

Hãy chỉ định trong URL được set khi đăng ký client.

Ví dụ: https://example.com/callback

Nếu có nhiều redirect_uri được set thì sẽ bắt buộc, nhưng nếu chỉ có 1 redirect_uri được set thì sẽ tùy chọn.

scope Strings (Space Delimited )

rooms.all:read_write

Appendix Scope list

state String

Là string được sử dụng như một biện pháp chống lại tấn công CSRF, và được quản lý bằng cách kết hợp với session của resource owner. Khi resource owner cho phép hoặc từ chối truy cập, state của string đã set ở đây sẽ được set thành query parameter và web browser được chuyển hướng đến redirect_uri.
Sau đó sẽ đối chiếu state kết hợp với session và state đã được chuyển qua Query parameter, phải luôn thực hiện các biện pháp chống tấn công CSRF khi chạy production.

Ví dụ. 343ab3341331218786ef

The OAuth 2.0 Authorization Framework 10.12. Cross-Site Request Forgery

Ví dụ: URL dùng để hiển thị consent screen
https://www.chatwork.com/packages/oauth2/login.php?
response_type=code
&redirect_uri=https://example.com/callback.php
&client_id=Lvo0YN92ga5kP
&state=811435b3683ae95c1cf3197deaf1bfe4b411f587
&scope=rooms.all:read_write%20users.profile.me:read

Phát hành Authorization code

Khi resource owner nhấn vào button "Cho phép" trên consent screen, Authorization code sẽ được cấp, và sau khi thiết lập Authorization code thành Query parameter xong web browser sẽ chuyển hướng đến redirect_uri.

Ví dụ: Hướng chuyển tới sau khi cấp Authorization code
code
Authorization code sẽ có hiệu lực trong 1 phút.
state
Gía trị của state đã chỉ định khi hiển thị consent screen.
https://example.com/callback.php?
code=a2f0c1fe96af8c3a46fa0
&state=811435b3683ae95c1cf3197deaf1bfe4b411f587

Từ chối authorization

Khi resource owner nhấn vào button "Từ chối" trên consent screen, authorization sẽ bị bác bỏ và web browser sẽ chuyển hướng đến redirect_uri.

error
Set thành access_denied
state
Gía trị của state đã chỉ định khi hiển thị consent screen.
https://example.com/callback.php?
error=access_denied

Ràng buộc ở màn hình login

Màn hình login dành cho OAuth2 không hỗ trợ SAML sử dụng chứng thực. Nên hãy log in SAML sử dụng chứng thực ở màn hình thường rồi sau đó access đến consent screen lại.

Màn hình login

3. Cấp/ cấp lại access token

Request

Endpoint

Hãy sử dụng HTTP POST để truy cập vào endpoint bên dưới.

https://oauth.chatwork.com/token
Xác thực

Dựa trên Basic Authentication, hãy đặt client ID làm username, và client secret làm password, merge lại bằng colon (:) rồi encode string với Base64. Có thể xác thực những thông tin này từ màn hình quản lý client.

Ví dụ:
Authorization: Basic THZvMFl1OO==
Format của request body
application/x-www-form-urlencoded
Body parameters
Trường hợp phát hành từ một authorization code
Parameter Specified Value Required Description
grant_type Strings Hãy set authorization_code
code Strings Hãy set Authorization Code cho authorization
redirect_uri Strings

Hãy set giá trị đã chỉ định khi hiển thị consent screen.

Ví dụ: https://example.com/callback

Nếu có nhiều redirect_uri được set thì sẽ bắt buộc, nhưng nếu chỉ có 1 redirect_uri được set thì sẽ tùy chọn.

Trường hợp sử dụng Refresh token để cấp lại
Parameter Specified Value Required Ví dụ
grant_type Strings Hãy set refresh_token.
refresh_token Strings Hãy set giá trị của refresh_token được tạo ra khi cấp token.
scope Strings users.profile.me:read

Response

Format của response body
application/json
Response body (khi cấp mới và khi cấp lại token đều như nhau)
JSON
Field Name
JSON
Value
nullable Ví dụ Description
access_token String Có hiệu lực trong 30 phút
refresh_token String Có hiệu lực trong 14 phút (Có khả năng sẽ thay đổi)
token_type String Bearer
expires_in Int Thời gian hiệu lực của token (giây)
scope String
error String "invalid_grant" Field trả về khi bị lỗi.
error_description String Field trả về khi bị lỗi.
error_uri String Field trả về khi bị lỗi. Hiện tại luôn là null.

Ví dụ: Cấp token với curl command

Request
curl  -v --user 'Lvo0YN92ga5kP:secret' \
-X POST -d 'grant_type=authorization_code \
&code=26d13798facc9a0ca05a8cb7246020f15a311 \
&redirect_uri=https://127.0.0.1/callback'  \
https://oauth.chatwork.com/token
Response
> POST /token HTTP/1.1
> Host: 127.0.0.1
> Authorization: Basic THZvMFlOOTJnYTVrUDphYmNkZWZnaGlqa2xu
bW9wcXJzdHV2d3h5ejAxMjM0NTY3ODk=
> Accept: */*
> Content-Length: 199
> Content-Type: application/x-www-form-urlencoded
>

< HTTP/1.1 200 OK
< Cache-Control: no-store
< Pragma: no-cache
< Content-Type: application/json
< Content-Length: 989

{
  "access_token": "eyJjdHkiOiJKV1QiLCJ0eXAiOiJKV1QiL
CJhbGciOiJSUzI1NiIsImtpZCI6ImlOUVh0dFR2RHZhcDVkSW
pGQzA5ZHZadHFXaGQ2WmFRb2pKenVuUS1vV28ifQ.eyJh
dWQiOiJodHRwczovL2FwaS5jaGF0d29yay5jb20iLCJzdWIi
OiIzIiwiYWNjb3VudF9pZCI6IjMiLCJzY29wZSI6WyJhbGwiXS
wiaXNzIjoiaHR0cHM6Ly9vYXV0aC5jaGF0d29yay5jb20iLC
JleHAiOjE1MDExMzgwNDEsImlhdCI6MTUwMTEzNzE0MSw
ianRpIjoiOTcwNDAwOWItNTdlNi00NDU5LTg5NzMtNjc3Zm
M5YjA5MjgyIiwiY2xpZW50X2lkIjoiTHZvMFlOOTJnYTVrUCJ9.
BIS8QvyTHz7KK_fnmvc0fa8NQDOWy7v8Ni0LvLyuROE5UEi
7l_HxDT8tHLTQLELIm3jOw4SiW94KPYwduRL467vJ2j2eNT
-zTkCXtEN8pxbA0HtnBrtCcp0dRJEMnfBegzkoAe8BTB6gee
3rrXy6sQcLb19WBrrHNbjICFL0--SG3IvPanOzABqiNMqfScn
asTtj7xtIaNpbxf8LDIH3EF150Iif4BqSczJr-XppBTBYuP32Ul
BnRlQOXvXqymGijQXgqDOo3LLFY_k62OoPYAQ3UXkaum8
6Al-DJM6iC-043kBINbYLLPo0uwwsolmjRDG5zBzPC0GtcjXiLy4Gqg",
  "token_type": "Bearer",
  "expires_in": "1501138041000",
  "refresh_token": "86277ab4fd9d111bd3225215d96d6
22c9ae6810d82cd6d0e9530bf35adda67ab7d3c24e2a0
052e9d3b442ce212ca17ecf07ddbd8c3477aa3abde15e4ebcf7b53",
  "scope": "rooms.all:read_write"
}

4. Truy cập vào API ChatWork

Request

Khi gửi request lên ChatWork API, hãy sử dụng Bearer authentication scheme để set access token (access_token) trong Authorization request header thay vì dùng ChatWork API authentication method như trước giờ.

Ví dụ: Set Authorization header
Authorization: Bearer eyJjdHkiOiJKV1QiLCJ0eXAiOiJKV1QiLCJh
bGciOiJSUzI1NiIsImtpZCI6ImlOUVh0dFR2RHZhcDVkSWpGQzA5Z
HZadHFXaGQ2WmFRb2pKenVuUS1vV28ifQ.eyJhdWQiOiJodHRwcz
ovL2FwaS5jaGF0d29yay5jb20iLCJzdWIiOiIzIiwiYWNjb3VudF9pZC
I6IjMiLCJzY29wZSI6WyJhbGwiXSwiaXNzIjoiaHR0cHM6Ly9vYXV0a
C5jaGF0d29yay5jb20iLCJleHAiOjE1MDExMzgwNDEsImlhdCI6MTU
wMTEzNzE0MSwianRpIjoiOTcwNDAwOWItNTdlNi00NDU5LTg5NzMt
Njc3ZmM5YjA5MjgyIiwiY2xpZW50X2lkIjoiTHZvMFlOOTJnYTVrUCJ9.
BIS8QvyTHz7KK_fnmvc0fa8NQDOWy7v8Ni0LvLyuROE5UEi7l_Hx
DT8tHLTQLELIm3jOw4SiW94KPYwduRL467vJ2j2eNT-zTkCXtEN
8pxbA0HtnBrtCcp0dRJEMnfBegzkoAe8BTB6gee3rrXy6sQcLb19
WBrrHNbjICFL0--SG3IvPanOzABqiNMqfScnasTtj7xtIaNpbxf8LDIH3E
F150Iif4BqSczJr-XppBTBYuP32UlBnRlQOXvXqymGijQXgqDOo3LLFY
_k62OoPYAQ3UXkaum86Al-DJM6iC-043kBINbYLLPo0uwwsolmjRD
G5zBzPC0GtcjXiLy4Gqg

Response

Hãy tham khảo tài liệu về Endpoint của API ChatWork.

Errors

Trường hợp access token bị unvalid hoặc không đúng thì thông tin error sẽ được set ở WWW-Authenticate header.

Ví dụ: Trường hợp access token bị unvalid
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer error="invalid_token",
error_description="The access token expired"
Ví dụ: Truy cập vào API ChatWork với curl command

curl -v -H 'Authorization: Bearer eyJjdHkiOiJKV1QiLCJ0eXAiOiJKV1
QiLCJhbGciOiJSUzI1NiIsImtpZCI6ImlOUVh0dFR2RHZhcDVkSWpGQz
A5ZHZadHFXaGQ2WmFRb2pKenVuUS1vV28ifQ.eyJhdWQiOiJodHR
wczovL2FwaS5jaGF0d29yay5jb20iLCJzdWIiOiIxNzMiLCJhY2NvdW5
0X2lkIjoiMTczIiwic2NvcGUiOlsiYWxsIl0sImlzcyI6Imh0dHBzOi8vb2F1
dGguY2hhdHdvcmsuY29tIiwiZXhwIjoxNTAyMjUxNDU4LCJpYXQiOjE1
MDIyNDk2NTgsImp0aSI6IjRlNzg5ZTAzLTk2NjAtNDc4MC1hYThkLTV
mZjk2YmU0MzMyNSIsImNsaWVudF9pZCI6Ikx2bzBZTjkyZ2E1a1AifQ.
Y14Sr0SmtgwLegwWPMeQlPut2XmP74y3QdupCAN7Hc5Id10Qvgq-
csuYVxxAYStqZUO4sZ_j9SeE7-rqhuNowDMwqVaTGfDvAvtQLitPKD
Ub2g6x87c-lfffkJkIiL1xcH3lHrmQkBa_H81-_a3VFJila8hFptvygOp1
9OSDSrUIlcq6PeHlfNQtXjs2VFREQydQNE2cdLe68Nh5F5V4HX20C4
49MKNWK4ybwmFrnX-o9KgERaP1rjrCcWYrZ-lK8TquHti9XMfSaj71e
DkfPVOLyCOe1_zBEEH8NRFtN2OcVQWJFPy09rz1yw7a1YARdsU4
DukrhWvWcVxIad8ygA' \
'https://api.chatwork.com/v2/me'
> GET /v2/me HTTP/1.1
> Host: api.chatwork.com
> Accept: */*
> Authorization: Bearer eyJjdHkiOiJKV1QiLCJ0eXAiOiJKV1QiLCJ
hbGciOiJSUzI1NiIsImtpZCI6ImlOUVh0dFR2RHZhcDVkSWpGQzA5Z
HZadHFXaGQ2WmFRb2pKenVuUS1vV28ifQ.eyJhdWQiOiJodHRwc
zovL2FwaS5jaGF0d29yay5jb20iLCJzdWIiOiIxNzMiLCJhY2NvdW50
X2lkIjoiMTczIiwic2NvcGUiOlsiYWxsIl0sImlzcyI6Imh0dHBzOi8vb2F1
dGguY2hhdHdvcmsuY29tIiwiZXhwIjoxNTAyMjUxNDU4LCJpYXQiOjE
1MDIyNDk2NTgsImp0aSI6IjRlNzg5ZTAzLTk2NjAtNDc4MC1hYThkL
TVmZjk2YmU0MzMyNSIsImNsaWVudF9pZCI6Ikx2bzBZTjkyZ2E1a1
AifQ.Y14Sr0SmtgwLegwWPMeQlPut2XmP74y3QdupCAN7Hc5Id10
Qvgq-csuYVxxAYStqZUO4sZ_j9SeE7-rqhuNowDMwqVaTGfDvAvtQ
LitPKDUb2g6x87c-lfffkJkIiL1xcH3lHrmQkBa_H81-_a3VFJila8hFpt
vygOp19OSDSrUIlcq6PeHlfNQtXjs2VFREQydQNE2cdLe68Nh5F5V4
HX20C449MKNWK4ybwmFrnX-o9KgERaP1rjrCcWYrZ-lK8TquHti9X
MfSaj71eDkfPVOLyCOe1_zBEEH8NRFtN2OcVQWJFPy09rz1yw7a1
YARdsU4DukrhWvWcVxIad8ygA
>
< HTTP/1.1 200 OK
< Content-Type: application/json; charset=utf-8
< Content-Length: 412
< Connection: keep-alive
< X-RateLimit-Limit: 100
< X-RateLimit-Remaining: 99
< X-RateLimit-Reset: 1502250163
< Vary: Accept-Encoding,User-Agent
<
{"account_id":1, ..... }

Appendix

A. Scope list

Chữ đậm: Danh sách các scopes

Name API Description
users.all:read
  • users.profile.me:read
  • users.status.me:read
  • users.tasks.me:read
Truy cập thông tin tài khoản cá nhân
users.profile.me:read Truy cập thông tin profile
users.status.me:read Truy cập để lấy số message chưa đọc
users.tasks.me:read Truy cập vào danh sách các task
rooms.all:read_write
  • rooms.all:read
  • rooms.all:write
Truy cập, sửa đổi tin nhắn, tasks, files, description, thông tin thành viên trong Chatroom.
rooms.all:read
  • rooms.info:read
  • rooms.members:read
  • rooms.messages:read
  • rooms.tasks:read
  • rooms.files:read
Truy cập vào tin nhắn, tasks, files, description, thông tin thành viên trong Chatroom.
rooms.all:read
  • rooms.info:read
  • rooms.members:read
  • rooms.messages:read
  • rooms.tasks:read
  • rooms.files:read
Truy cập vào tin nhắn, tasks, files, description, thông tin thành viên trong Chatroom.
rooms.all:write
  • rooms:write
  • rooms.info:write
  • rooms.members:write
  • rooms.messages:write
  • rooms.tasks:write
Sửa đổi tin nhắn, tasks, files, description, thông tin thành viên trong Chatroom.
rooms:write Tạo Chatroom và xóa Chatroom đang tham gia.
rooms.info:read Truy cập vào danh sách Chatroom đang tham gia.
rooms.info:write Update thông tin trong Chatroom đang tham gia.
rooms.members:read Truy cập vào thông tin member trong Chatroom đang tham gia.
rooms.members:write Upadate quyền, delete, add member trong Chatroom đang tham gia.
rooms.messages:read Truy cập vào message trong Chatroom đang tham gia.
rooms.messages:write Post message lên Chatroom đang tham gia.
rooms.tasks:read Truy cập vào task trong Chatroom đang tham gia.
rooms.tasks:write Tạo task trong Chatroom đang tham gia.
rooms.files:read Truy cập vào thông tin được upload lên Chatroom đang tham gia.
contacts.all:read_write
  • contacts.all:read
  • contacts.all:write
Truy cập, chỉnh sửa thông tin contact, request contact đang chờ xác nhận.
contacts.all:read Truy cập thông tin contact, request contact đang chờ xác nhận.
contacts.all:write Chỉnh sửa thông tin contact, request contact đang chờ xác nhận.

B. Danh sách lỗi phát sinh khi cấp quyền.

Error Code
(error_code)
Error Description
(error_description)
Bổ sung
1001 `response_type` parameter is missing. Khi hiển thị consent screen, parameter response_type không được chỉ định.
3001 The resource owner denied the request. Resource owner từ chối chứng thực ở màn hình login hoặc màn hình consent.
4001 `token` response type is not supported. Khi hiển thị consent screen, response_type không support được chỉ định.
4002 `foo` response type is unknown. Khi hiển thị consent screen, response_type không xác định được chỉ định.
5001 Scope is missing. Scope không được chỉ định.
5002 The scope is unknown. Scope không xác định được chỉ định.
11000 `client_id` is missing. client_id không được chỉ định.
13000 `redirect_uri` is missing. redirect_uri không được chỉ định.
14000 The redirect URI is malformed. Format của client_id không đúng.
15000 The redirect URI is unregistered. client_id chưa được đăng ký.