认证

在线编辑

要访问REST服务，您必须通过身份验证成为活跃的Targetprocess用户或系统用户。 不允许匿名访问。 请求者账户不被授予访问API的权限。

Targetprocess REST API 客户端可使用 Cookie、基本或令牌认证模式。

HTTP 若身份验证失败，则返回401状态码（401：未授权）。

令牌认证

令牌认证模式使用随附的自定义安全 URL 令牌。 使用该令牌，您的REST客户端应用程序将获得与令牌所有者用户相同的项目和团队成员资格及安全权限。

Targetprocess 目前提供并支持两种不同类型的代币：

资源 服务令牌 访问令牌
参数名 &token=xxxxxxxxxxxxxx &access_token=xxxxxxxxxxxxxx
获取来源 查询API端点：GET /api/v1/Authentication 目标流程界面： 设置 -> 身份验证与安全 -> 个人访问令牌
用户可自行获取 是 是
管理员可以为其他用户获取它 是 获取 /api/v1/Authentication?login=mwhite 否
系统用户可以拥有它 是 获取 /api/v1/Authentication?login=System 否
密码无关的 当关联用户的密码被更改时，该权限即失效 是
支持每个用户拥有多个应用程序专用令牌 否 是
发行日期和最后使用日期均被追踪并显示 否 是
可停用 是，将关联用户登录设为非活动状态 是

用户界面中设置的个人访问令牌

个人访问令牌的角色权限

要获取和使用个人访问令牌，用户的默认角色必须启用 “允许创建和使用访问令牌”权限。

默认情况下，所有角色均允许使用个人访问令牌。 在确定访问权限时，仅评估用户的默认角色。 如果用户（无论是否具有管理员权限）在其默认角色中不具备此权限，则无法：
  • 访问“个人访问令牌”选项卡
  • 创建新令牌
  • 使用现有令牌进行身份验证（例如在撤销权限前签发的令牌）

个人访问令牌的管理与控制

同时拥有管理员权限和 “允许创建和使用访问令牌 ”权限的用户可以访问 “个人访问令牌 ”管理页面。 在此页面上，他们可以查看所有已发行代币的相关信息，包括：
  • 用户
  • 令牌名称
  • 发布日期
  • 最后使用日期

获取个人访问令牌

  • 非管理员：没有管理权限的用户在此选项卡中只能查看自己的令牌。
  • 管理员：具有管理权限的用户可访问系统中的所有个人访问令牌，包括其他用户的令牌。

有关更多信息，请参阅“个人访问令牌管理与控制”部分。

个人访问令牌

获取令牌

用户可在 “设置”->“身份验证与安全 ”中的 “个人访问令牌 ”选项卡下添加令牌。 管理员无法为其他用户添加令牌。

令牌

你可以随心所欲地使用它们。 当令牌不再需要时，可以将其删除。

出于安全考虑，新令牌仅在生成后才会显示，且仅可在此之后进行复制。 若您不记得旧令牌，可将其删除。 并且你可以在需要时随时生成新的令牌。

您可直接在同一标签页中追踪代币使用情况。

使用令牌

接收到的令牌可通过在URI中添加 {token} access_token= 请求参数，用于任何REST服务。

GET /api/v1/UserStories/?access_token=YWRtaW46QUFBMEEwQTAwMEFBQTBBMDBBMEEwQTBBMEEwMEFBMDA=
个人访问令牌管理与控制同时拥有管理员权限和" 允许创建及使用访问令牌 "权限的用户可访问个人访问令牌管理页面。 从那里，他们可以查看所有已发行代币的详细信息，包括：
  • 用户
  • 令牌名称
  • 发布日期
  • 最后使用日期

管理员可在必要时删除任何用户令牌，以撤销访问权限或防止未经授权的数据使用。

令牌

身份验证服务生成的令牌

获取令牌

要获取令牌，您必须先登录 Targetprocess。 要获取安全令牌，您需要通过以下URI查询身份验证REST服务：

GET /api/v1/Authentication

而你将获得属于自己的信物：

<Authentication Token="YWRtaW46OTRDRDg2Qzg1NjgzQUZDMzg3Qjg2QTVERTAxRTZEQzY="/>

只要用户不更改其登录名或密码，该令牌就始终有效。 如果用户更改了登录名和/或密码，系统将自动为其生成新的令牌。

活跃用户的令牌始终处于活跃状态。

认证服务同时支持XML和JSON格式。

使用令牌

在 URI 中添加请求参数 token= {token} ，即可将收到的令牌用于任何 REST 服务。

GET /api/v1/UserStories/?token=YWRtaW46QUFBMEEwQTAwMEFBQTBBMDBBMEEwQTBBMEEwMEFBMDA=

为其他用户和系统用户获取令牌

Targetprocess 中的管理员也可以为其他用户获取令牌。 在参数中传递他们的登录名：

GET /api/v1/Authentication?login=mwhite

系统用户的令牌获取方式相同：

GET /api/v1/Authentication?login=System

该用户在账户中拥有与任何管理员用户相同的权限。 凭此令牌可执行任何数据修改操作。

注意： 可以禁用目标进程账户的服务令牌生成和使用。 请联系我们的支持团队以禁用此身份验证方式。

Cookie认证

若您已登录Targetprocess用户账户，则您的网页浏览器会通过Cookie记住您的用户登录信息。 当您尝试通过浏览器的地址栏访问 /api/v1/UserStories/ 资源时，系统会向 REST API 发送一个 GET 请求，并使用您的 Cookie 进行身份验证。

默认情况下，若从混合应用程序代码中调用REST API服务，也会发生同样的情况。 登录的Targetprocess用户的Cookie用于身份验证。

当您使用网页浏览器插件发送REST API请求时，可以使用网页浏览器的Cookie。 例如，在 Chrome 网页浏览器中，有一个名为 Advanced REST Client 的插件。 要获取Cookie，请在REST客户端设置中开启"使用XHR"模式。 此外，还应安装 ARC Cookie 交换插件。

Cookie认证

基本认证

警告： 对于使用 Single Sign On 和/或 Frontdoor 作为用户登录方式的实例，不建议使用基本身份验证。 相反，请使用 token 或 access_token 进行身份验证。

要使用基本身份验证，您需要在每次请求中发送一个 Authorization: Basic 标头。 例如，若需以 admin:admin（登录名:密码）身份进行身份验证，应发送以下请求：

GET /api/v1/UserStories/ HTTP/1.1
Authorization: Basic YWRtaW46YWRtaW4=
警告：YWRtaW46YWRtaW4= key 包含以 Base64 Base64 编码的登录凭据，即 admin:admin，这是任何新 Targetprocess 账户所有者的默认凭据。 您可以在网上生成这样的密钥。 在编码登录名:密码对时，请确保复制粘贴的行首行尾没有多余空格或换行符。 若通信通道未通过 HTTPS 加密 HTTPS ，请勿使用基本认证，因为传输的凭据仅采用 Base64 编码 Base64 ，而非加密或哈希处理。

使用 cURL 该工具时，您无需手动编码基本身份验证的登录名和密码， cURL 它会自动为您完成编码。

curl --user login:password /api/v1/userstories/

此外，您还可以在编程语言中使用特殊函数。

例如，在.NET /C# 中，它将呈现如下形式：

var webClient = new WebClient();
webClient.Credentials = new NetworkCredential("admin", "admin");

要在 Ruby 中调用 REST 服务，您可以使用 HTTParty gem。

class UserStoryResource
  include HTTParty
  base_uri 'testaccount.tpondemand.com'
  format :xml
  def initialize(u, p)
    @auth = {:username => u, :password => p}
  end
  def all_stories(options={})
    options.merge!({:basic_auth => @auth})
    self.class.get("/api/v1/UserStories/", options)
  end
end
...
storyResource = UserStoryResource.new('admin', 'admin')
stories = storyResource.all_stories

当登录表单启用时，系统用户支持基本身份验证模式。 当在单点登录设置中禁用登录表单时，此类身份验证将被阻止。 改用基于令牌的身份验证。

通过API检索已登录用户的详细信息

成功认证后，您可以获取已登录用户ID和角色的详细信息。 通过以下路径查询 LoggedUser 资源：

/api/v1/users/LoggedUser/

它将为您提供已登录用户的详细信息。

<User ResourceType="User" Id="334">
  <Kind>User</Kind>
  <FirstName>Teddy</FirstName>
  <LastName>Bear</LastName>
  <Email>xxx@xxx.com</Email>
  <Login>xxx</Login>
  <CreateDate>2006-10-02T16:19:42</CreateDate>
  <ModifyDate>2016-11-17T00:01:16</ModifyDate>
  <DeleteDate nil="true"/>
  <IsActive>true</IsActive>
  <IsAdministrator>true</IsAdministrator>
  <LastLoginDate>2016-11-17T00:00:00</LastLoginDate>
  <WeeklyAvailableHours>20.0000</WeeklyAvailableHours>
  <CurrentAllocation>100</CurrentAllocation>
  <CurrentAvailableHours>0.0000</CurrentAvailableHours>
  <AvailableFrom nil="true"/>
  <AvailableFutureAllocation>0</AvailableFutureAllocation>
  <AvailableFutureHours>0.0000</AvailableFutureHours>
  <IsObserver>false</IsObserver>
  <IsContributor nil="true"/>
  <Locale>en</Locale>
  <Skills>ui</Skills>
  <ActiveDirectoryName>TP\falcon</ActiveDirectoryName>
  <Role ResourceType="Role" Id="8" Name="Head"/>
  <CustomFields>
    <Field Type="Text">
      <Name>Skill Set</Name>
      <Value nil="true"/>
    </Field>
  </CustomFields>
</User>

故障诊断

在Excel集成中使用令牌

问： 我在一个 Excel 文件中有一个 Web 查询，用于从 Targetprocess 提取数据。 如何将密码保存到查询字符串中——这样我打开文件更新数据时就不用登录三次了？

A： 请通过“个人访问令牌”选项卡创建访问令牌：

创建访问令牌

然后将 附加 &access_token=token_value 到您的 Excel API 请求中。

了解有关 Excel 与 Targetprocess 集成的更多详情。

系统用户未授权错误

问： 我为我的系统用户获取了一个令牌。 但当我尝试使用它时，却收到401未授权的响应。 如何继续？

答： 若要建立任何使用系统用户凭据的集成，您必须设置其密码。 您似乎尚未为系统用户设置密码。 请在 “设置” > “身份验证和安全” > “系统用户”面板中将其设置为“Targetprocess”，然后保存更改。

系统用户凭证