OAuth 2.0

1. 概述

BeTalk的 API 使用 OAuth 2.0 协议,一种通用的开放标准,大多数 API 用于身份验证和授权用户。本文档概述了由 BeTalk 支持 OAuth 2.0 授权方案。

如果你正在生成只包含客户端组件的应用程序,那么你应该使用 Client-Side (Implicit) Flow model。

如果你的应用程序有服务器端组件,那么你应该使用Server-Side (Explicit) Flow。

在大多数情况下选择这两种身份验证模式之一来使用。

2. 请求端点

注:以下链接地址仅为示例,实际地址以项目为准。

BeTalk OAuth 端点地址 ( production模式): https://api.BeTalk.com/

BeTalk OAuth 端点地址 (sandbox模式): https://apisandbox.BeTalk.com/

3. 注册

与 BeTalk使用 OAuth2 身份验证的所有应用程序,必须通过我们的应用程序注册控制台进行注册。已注册的应用程序都将获得一个独立的客户端 ID 和客户端秘钥。

4. 客户端 (Implicit) 组件

你将使用这个组件,来创建一个没有服务器组件的程序。

4.1 开始授权 & 请求访问令牌

引导用户到BeTalk去

https://apisandbox.betalk.com/oauth/authorize?client_id=CLIENT-ID&redirect_uri=REDIRECT-URI&response_type=token

请求参数

名称 类型 描述
client_id String 在注册时,从 BeTalk 接收客户端 ID
response_type String For the implicit flow, this should always be set to ‘token’
redirect_uri String Optional: Determines where the response is sent. The value of this parameter must exactly match to the value you specified when registering your app.

4.2 获取访问令牌

如果用户的认证请求成功,BeTalk 将按照redirect_uri中指定的路径,引导用户回到他的程序中。参数在URI的hash表中,被传递回来;

这个参数不是平时所用的query string。它的格式是这样的:

http://redirect_uri#access_token=ACCESS-TOKEN&token_type=bearer&expires_in=EXPIRATION-TIME

请求参数

名称 描述
access_token Access token for use in BetalkAPI calls.
token_type This always has the value of bearer.
expires_in Expiration time (in seconds)

4.3 进行API调用

当你的程序从URI的hash中获取到token后,你可以使用token来请求BeTalk的接口。

在你请求BeTalk接口的时候,必须要加上token。请注意,这个token不能被配置,并且有效期很短,当token过期后,你需要重新登录和验证身份。

5. 服务器端 (Explicit) 组件

服务器端工作原理是将你的用户发送给BeTalk,授权使用以下过程:

5.1 开始授权&请求授权代码

引导用户到BeTalk去

https://apisandbox.betalk.com/oauth/authorize?client_id=CLIENT-ID&redirect_uri=REDIRECT-URI&response_type=code

请求参数

名称 类型 描述
client_id String The client ID you received from Betalk when you registered.
esponse_type String For the explicit flow, this should always be set to ‘code’
redirect_uri String Optional: Determines where the response is sent. The value of this parameter must exactly match to the value you specified when registering your app.

5.2 获取授权码和请求访问令牌

如果用户的认证请求成功,BeTalk 将按照带有一个认证code的rect_uri中指定的路径,引导用户。

http://redirect_uri?code=CODE

请求参数

名称 描述
code Temporary code which will be used to get the access token.

授权代码交换访问令牌和刷新令牌通过HTTPS请求,如下所示:

POST https://apisandbox.BeTalk.com/oauth/token
client_id=CLIENT-ID&
client_secret=CLIENT-SECRET&
grant_type=authorization_code&     
code=CODE 

请求参数

名称 类型 描述
client_id String The client ID you received from Betalk when you registered.
client_secret String The client secret you received from Betalk when you registered.
grant_type String This should always be set to ‘authorization_code’
code String The exact authorization code you received from the previous step

5.3 获得访问令牌

身份验证成功并获得验证授权码,将在 JSON 响应中返回访问令牌。它的格式是这样的:

{    
   "access_token": "F6YwMQAAATp7lE9TAACowENMLWNsaWVudCAgICAgICAgICAgICAgAAAAAw", 
"token_type": "bearer",     
"refresh_token": "VcgxMQAAATp7M06eACeNAFVpYWR1RVNXc2J6Rm9LOVRPbGRDNnpGAAAAAw",    
 "expires_in": 43199,    
 "scope": "read write"}

请求参数

名称 描述
access_token Access token for use in Betalk API calls.
token_type This always has the value of bearer.
refresh_token Refresh token may be used to refresh the access token when it expires (good for 30 days)
expires_in Expiration time (in seconds)

5.4 进行API 调用

当你的应用程序从上述步骤获取到token后,你可以使用token来请求BeTalk的API接口。请注意,这个token有效期很短,当token过期后,你需要重新登录和验证身份。

6. 刷新token

刷新Token 允许你的应用程序继续授予访问,不强迫用户重新授权你的应用程序。适用于每一个请求,除了重新获取一个新的refresh_token,但新的refresh_token也会被返回,新refresh_token寿命为它产生后的30天。

你可以刷新Token来通过HTTPS POST请求,如下所示:

curl \-F 'client_id=CLIENT-ID' \ 
-F 'client_secret=CLIENT-SECRET' \
-F 'grant_type=refresh_token' \ 
-F 'refresh_token=REFRESH-TOKEN' \https://apisandbox.betalk.com/oauth/token 

请求参数

名称 类型 描述
client_id String The client ID you received from Betalk when you registered.
client_secret String The client secret you received from Betalk when you registered.
grant_type String This should always be set to ‘refresh_token’.
refresh_token String The exact refresh token you received from the original request with the access token.

成功请求, 样例相应结果,如下所示:

{     
"access_token": "vI0wMgAAAVHLaPAcACeNAFV0a2ozWUM1QnhSSENDYXE5d2lkUDY3IAAAAAdU", 
"token_type": "bearer",     
"refresh_token": "YHcxMgAAAVHLaPAcACeNAFV0a2ozWUM1QnhSSENDYXE5d2lkUDY3IAAAAAd",     
"expires_in": 43199,    
"scope": "read write"
 }

7. 撤销 Access Token

可以通过 HTTPS POST 请求,撤销Access token,如下所示:

curl \-F 'access_token=ACCESS-TOKEN' \https://apisandbox.betalk.com/oauth/revoke

请求参数

名称 类型 描述
access_token String A valid access token.

8. SAML Bearer

The OAuth 2.0 SAML bearer assertion flow defines how a SAML assertion can be used to request an OAuth access token when a client wishes to utilize a previous authorization, more details can be found at http://tools.ietf.org/html/draft-ietf-oauth-saml2-bearer.

8.1 配置

配置同样记录在我们的SAML 单点登录文档中,以下情况除外

  • SP entityID for Audience – http://api.betalk.com
  • SP Access Consumer Service endpoint for Recipient – “https://api.betalk.com/oauth/token”

8.2 创建 SAML Bearer Assertion

从身份提供者哪里获取assertion ,这个assertion 必须按照XML数字签名规范签名,使用RSA和SHA-1或者SHA-256加密。

如下所示:

<?xml version="1.0" encoding="UTF-8"?>     
<Assertion xmlns="urn:oasis:names:tc:SAML:2.0:assertion" ID="maegkddcbcljpaddamchldbfgmifaabmchfiehoh" IssueInstant="2013-06-05T01:22:41Z" Version="2.0">         <Issuer>sampleidptest</Issuer> 
        <ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">    
        <ds:SignedInfo>   
               <ds:CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#" />        
               <ds:SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1" />           
                <ds:Reference URI="#maegkddcbcljpaddamchldbfgmifaabmchfiehoh">            <ds:Transforms>          
                      <ds:Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature" />        
                </ds:Transforms>       
                <ds:DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1" />       
                <ds:DigestValue>WP4hmTbZ4rNf9mLdXR6mijCTqns=</ds:DigestValue> 
            </ds:Reference> 
           </ds:SignedInfo>  
           <ds:SignatureValue>
 hEnxtDX+mSyljDvkWPfy//5XTuygRLUJ3hIzhVfv/c7vm/WvLVpftSc3LSeVIII9bHAM2hwoT/5T9WYOoFFGl6+2/fiQXS+L1kPx3enX6SQOZJuZh6NZrwj6O0F1fts8ZEmRs1zAfhBxrLjOmIjEWhC+A0iuHJeSs1sE8teK04Zv4eu4Ir/xZSrnmL4cH03EZo9NJdKMWmTKoY1Fp+i7fjHEa6MiPcUSznuDQilMDeW3ECbqqwEgZwyyvSscPZgr/s5ZUsOYeFwD3MhtpAzM+DF/a5k4Q+wA5POIyGYJZ4aCXw4u77S7RATCbNgsZaOPLLgyrwf7SIT4DTGZfFrSZg==         </ds:SignatureValue>   
<ds:KeyInfo>    
         <ds:X509Data>  
               <ds:X509SubjectName> CN=*.betalk.com,OU=Terms of use at www.verisign.com/rpa (c)05,O=Betalk\, Inc.,L=Cupertino,ST=California,C=US                
 </ds:X509SubjectName>
                 <ds:X509Certificate> MIIFWDCCBECgAwIBAgIQckTX7Th3KRVw+5W/TTM+EDANBgkqhkiG9w0BAQUFADCBtTELMAkGA1UEBhMCVVMxFzAVBgNVBAoTDlZlcmlTaWduLCBJbmMuMR8wHQYDVQQLExZWZXJpU2lnbiBUcnVzdCBOZXR3b3JrMTswOQYDVQQLEzJUZXJtcyBvZiB1c2UgYXQgaHR0cHM6Ly93d3cudmVyaXNpZ24uY29tL3JwYSAoYykxMDEvMC0GA1UEAxMmVmVyaVNpZ24gQ2xhc3MgMyBTZWN1cmUgU2VydmVyIENBIC0gRzMwHhcNMTMwMTI5MDAwMDAwWhcNMTcwMTI5MjM1OTU5WjCBmTELMAkGA1UEBhMCVVMxEzARBgNVBAgTCkNhbGlmb3JuaWExEjAQBgNVBAcUCUN1cGVydGlubzEVMBMGA1UEChQMTW94dHJhLCBJbmMuMTMwMQYDVQQLFCpUZXJtcyBvZiB1c2UgYXQgd3d3LnZlcmlzaWduLmNvbS9ycGEgKGMpMDUxFTATBgNVBAMUDCoubW94dHJhLmNvbTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBANSILv9Jysk5zCGBAdArLLOGtmRjWaLOixLUdQORnHF0VqwlVr6UYmTTQLsnbbS7uFp32Xm/fd18k6Wlydyl64XkqHYlbNcMErM6prlN5tN0MvTvOygOCTlLdmOqmf7KqASGAtZ32DkDIHlmArTTRSmhfWk/PgK2RjWGDgz1pXrpGCIZXJbgtA6a2E4mJr8g0+3h7HLA/VKJpkrWKhgt9aJewzf+p2Ab0EDfTrdJ9LhSXUMkgR+2CfIkVHEsksPiB+TlTTgnlJ9+d6t6iCSWXYBGCZB33wtWgtCHkDsq5GtEPoiUpbagO6LtYoxltjhdfLiZdwI7aqRHHn8UMDG3XT0CAwEAAaOCAXwwggF4MBcGA1UdEQQQMA6CDCoubW94dHJhLmNvbTAJBgNVHRMEAjAAMA4GA1UdDwEB/wQEAwIFoDBFBgNVHR8EPjA8MDqgOKA2hjRodHRwOi8vU1ZSU2VjdXJlLUczLWNybC52ZXJpc2lnbi5jb20vU1ZSU2VjdXJlRzMuY3JsMEMGA1UdIAQ8MDowOAYKYIZIAYb4RQEHNjAqMCgGCCsGAQUFBwIBFhxodHRwczovL3d3dy52ZXJpc2lnbi5jb20vY3BzMB0GA1UdJQQWMBQGCCsGAQUFBwMBBggrBgEFBQcDAjAfBgNVHSMEGDAWgBQNRFwWU0TBgn4dIKsl9AFj2L55pTB2BggrBgEFBQcBAQRqMGgwJAYIKwYBBQUHMAGGGGh0dHA6Ly9vY3NwLnZlcmlzaWduLmNvbTBABggrBgEFBQcwAoY0aHR0cDovL1NWUlNlY3VyZS1HMy1haWEudmVyaXNpZ24uY29tL1NWUlNlY3VyZUczLmNlcjANBgkqhkiG9w0BAQUFAAOCAQEAkKwB3bMdqJbKUDVOI9VgH8adRqw50djPyxme7/XL+v507txaQnSFa9KMUtzn7lvB8E4C7yU51SFBHJyMfygEig2yLcqsjAor4z4i9lr4KcOA0tV7iT3Q67JPsVPENqEXk+LngZZhHSdvrss0+frGUVn0shFrZzRSXWzaz/E8+xiDBQ3g3kuo2p9bLjL8HmhZQSDwCbL74UsuJmSaw57XODzdcGg+Fm7V6gx3pXGcdoU/a8rJz7Sea0TSHc+Q7SgnFsvulwGZktZN21oNHLJ7k9RvLfx3AeSp7S1J4lvdDPnAoJfaWrIIjve/pUaCcuofAYPIjUN+E3jR2yIxpmHcTw==  
               </ds:X509Certificate> 
            </ds:X509Data> 
        </ds:KeyInfo> 
        </ds:Signature>
         <Subject>
             <NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified">                 test@xyz.com
             </NameID> 
            <SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer"> 
                <SubjectConfirmationData NotOnOrAfter="2013-06-05T01:32:41Z" Recipient="https://api.betalk.com/oauth/token" />
             </SubjectConfirmation>
         </Subject>
         <Conditions NotBefore="2013-06-05T01:17:41Z" NotOnOrAfter="2013-06-05T01:32:41Z">
             <AudienceRestriction> 
                <Audience>http://api.betalk.com</Audience>
             </AudienceRestriction> 
        </Conditions>
         <AuthnStatement AuthnInstant="2013-06-05T01:22:41Z">             <AuthnContext>
                 <AuthnContextClassRef>
                     urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport 
                </AuthnContextClassRef> 
            </AuthnContext>
         </AuthnStatement>
 </Assertion> 

 8.3 请求并获取访问授权

如果要获取token,必须使用SAML bearer assertion来发起一个https请求,地址是https://api.betalk.com/oauth/token

POST https://api.betalk.com/oauth/token
client_id=CLIENT-ID&
client_secret=CLIENT-SECRET&
 grant_type=urn:ietf:params:oauth:grant-type:saml2-bearer& 
 idpid=IDP-ID&
       orgid=ORD-ID&
  assertion=PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNv... 

请求参数

名称 类型 描述
client_id String The client ID you received from Betalk when you registered.
client_secret String The client secret you received from Betalk when you registered.
grant_type String This should always be set to ‘urn:ietf:params:oauth:grant-type:saml2-bearer’.
idpid String Issuer Entity ID.
assertion String SAML bearer assertion as created in the previous step, encoded using base64.
orgid String Optional: Organization ID received from Betalk; Required for Org based SSO.
partnerid String Optional: Partner ID received from Betalk; Required for Partner based SSO.

在身份验证请求成功后,Betalk将返回一个JSON

{
"access_token": "F6YwMQAAATp7lE9TAACowENMLWNsaWVudCAgICAgICAgICAgICAgAAAAAw",
     "token_type": "bearer",
     "expires_in": 43199, 
    "scope": "read write" }

请求参数

名称 描述
access_token Access token for use in Betalk API calls.
token_type This always has the value of bearer.
expires_in Expiration time (in seconds)