API

LinkedIn

Be great at what you do.

dismiss this message

OAuth 2.0 验证

    在领英,我们重视会员数据的完整性和安全性胜于一切。如果您的应用想要访问领英会员的数据和/或代表他们采取行动,则必须获得授权。为了简化流程,领英根据行业标准 OAuth 2.0 协议授予访问权限。

    在开始授权之前,可以参考下面的简图理解领英OAuth 2.0验证的原理。如果您已经对OAuth 2.0非常熟悉,可以跳过此图,直接按照此后的步骤操作,向领英发起获授权的 请按照以下步骤操作,以便您的应用使用 OAuth 2.0 向领英发起获授权的 API 调用: 

    第 1 步 — 配置您的领英应用

    如果您还没有创建应用,请先创建一个应用。 如果您已创建应用,请选择此应用并修改其设置。

    为了避免在授权过程中发生欺诈性交易,我们仅会与您确定为信任端点的网址通信。确保应用的“OAuth 2.0 重定向网址”字段包含一个有效的回调网址,指向为完成部分授权工作流程而负责监听的服务器。

    请注意:

    • 强烈建议您使用 HTTPS
    • 网址必须是绝对网址 (例如: “https://example.com/auth/callbac”,而不是“/auth/callback”)
    • 网址参数会被忽略 (即 https://example.com/?id=1 与 https://example.com/ 相同)
    • 网址中不得包含 #'s (即“https://example.com/auth/callback#linkedin”是无效网址)

    保存配置后,系统将为应用分配一个唯一的“客户端 ID” (也称为“用户密钥”或“API 密钥”) 和“客户端密钥”值。请记录这些值,因为您在应用的配置文件或实际代码过程中需要使用这些值,例如:

    请注意:

    切勿与任何人分享您的客户端密钥值,否则会对应用的安全性构成风险!您也不得将密钥值发布在支持论坛,以获取应用帮助。

    第 2 步 — 请求授权代码

    妥善配置应用后,您便可请求授权代码。  此授权代码不是您向领英发起调用所用的最终令牌。  您将在 OAuth 2.0 流程最后一步使用此代码交换实际的访问令牌。  此步骤非常关键,因为它表示领英直接向用户保证正为正确的应用授予权限,并按照协定提供对会员领英个人资料的访问权限。

    重定向用户

    如需请求授权代码,您必须将用户浏览器定向至领英 OAuth 2.0 授权端点。完成请求后,将会发生以下任一种情况:

    • 如果用户之前未接受应用的权限请求,或授权过期或用户手动撤销授权,浏览器将被重定向至领英授权屏幕 (如下所示)。用户完成授权流程后,浏览器将重定向至 redirect_uri 查询参数中提供的网址。
    • 如果系统当前已有用户授予的有效权限,则会跳过授权屏幕,立即将用户重定向至 redirect_uri 查询参数中提供的网址。

    注意,如果您曾更改应用要求的 scope 权限,则用户需要重新授权,确保他们明确授予此应用代表他们请求的所有权限。

    GET
    https://www.linkedin.com/uas/oauth2/authorization
    参数
    说明
    必填
    response_type此字段值必须为: code  
    client_id注册应用时生成的“API 密钥”值。

    redirect_uri

    将在授权后向用户发送的地址。此值必须与应用配置中某个定义的 OAuth 2.0 重定向网址匹配。

    例如: https://www.example.com/auth/linkedin


    state

    由您选择且不易被猜中的唯一字符串值。 用于阻止跨站请求伪造攻击。

    例如: state=DCEeFWf45A53sdfKef424


    scope

    由网址编码组成且限定长度的会员权限列表,表示应用代表用户请求的权限。如果您在调用中未指定范围,我们将使用您在应用配置中定义的默认会员权限。

    例如: scope=r_fullprofile%20r_emailaddress%20w_share

    请参见了解应用权限和最佳实践指南,了解有关范围的更多信息。

    可选
    调用示例
    https://www.linkedin.com/uas/oauth2/authorization?response_type=code&client_id=123456789&redirect_uri=https%3A%2F%2Fwww.example.com%2Fauth%2Flinkedin&state=987654321&scope=r_basicprofile

    用户体验

    重定向后,用户会看到领英授权对话框。  这可以识别您的应用,并概要列出应用请求的特定会员权限。  如有需要,您可在应用配置中更改标志和应用名称。

    应用获批准

    用户只需提供有效的领英授权,然后单击“允许访问”按钮,即可批准应用访问其会员数据并代表他们与领英互动。根据此批准,领英将用户重定向至您在 redirect_uri 参数中定义的回调网址。

    Redirect_uri 中随附两个重要的网址参数,您需从请求中阅读:

    • code — OAuth 2.0 授权代码。
    • state — 用来测试是否存在跨站请求伪造攻击可能性的值。

    code 是您在授权流程后续步骤中与领英交换实际 OAuth 2.0 访问令牌所用的值。鉴于安全原因,授权代码的使用期限极短,必须在收到后立即使用以免其过期。如需请求新的授权代码,您必须重复执行以上所有步骤。

    接受授权代码之前,您应确保应用的 state 参数中返回的值与您原始授权代码请求的 state 值相匹配。 这样可确保您与真正的原始用户交流,且没有恶意脚本以某种方式进入授权流程。如果状态值不匹配,说明您可能已受到跨站请求伪造攻击,请在响应中提供 HTTP 401 错误代码。

    应用被拒绝

    如果用户选择取消,或此请求因任何其他原因失败,则其客户端将重定向至您的 redirect_uri 回调网址,并随附以下详细查询参数:

    • error — 表示错误类型的代码。
    • error_description — 用于总结此错误的网址编码文本描述。

    第 3 步 — 使用授权代码交换访问令牌

    获取访问令牌的最后一步是,应用使用刚刚获取的授权代码请求提供访问令牌。这是通过提出以下 “x-www-form-urlencoded” HTTP POST 请求进行的:

    POST
    https://www.linkedin.com/uas/oauth2/accessToken
    参数
    说明必填
    grant_type此字段值必须为: authorization_code

    code您在第 2 步中获取的授权代码。

    redirect_uri您在上一步中发送的相同“redirect_uri”值。

    client_id第 1 步中生成的“API 密钥”值。

    client_secret

    第 1 步中生成的“秘密密钥”值。

    请按照最佳实践指南处理 client_secret 值。


    调用示例
    POST /uas/oauth2/accessToken HTTP/1.1
    Host: www.linkedin.com
    Content-Type: application/x-www-form-urlencoded
    
    grant_type=authorization_code&code=987654321&redirect_uri=https%3A%2F%2Fwww.myapp.com%2Fauth%2Flinkedin&client_id=123456789&client_secret=shhdonottell

    访问令牌响应

    访问令牌请求成功后,系统将返回一个包含以下字段的 JSON 对象:

    • access_token — 用户的访问令牌。根据您所签署的 《API 使用条款》,您必须确保此值的安全性。
    • expires_in — 从提出请求开始到令牌失效之前剩余的秒数。目前,所有访问令牌的使用寿命均为 60 天。

    第 4 步 — 发出获授权的请求

    获得访问令牌后,您便可开始代表用户发出获授权的 API 请求。 您只需在向领英 API 发起的 HTTP 调用中,包含一个“Authorization”标头,即可完成此步骤。以下是 HTTP 请求示例,包含具有以下令牌的标头值:


    调用示例
    GET /v1/people/~ HTTP/1.1
    Host: api.linkedin.com
    Connection: Keep-Alive
    Authorization: Bearer AQXdSP_W41_UPs5ioT_t8HESyODB4FqbkJ8LrV_5mff4gPODzOYR

    无效令牌

    如果您使用无效令牌进行 API 调用,则会收到服务器发送的“401 未经授权”响应消息。令牌可能会因以下原因无效,需要重新生成:

    • 令牌过期。
    • 用户撤消了他们最初为应用授予的权限。
    • 您更改了应用请求的会员权限 (范围)。
    • 后续 OAuth2 流程会生成新访问令牌。 之前的令牌将失效。

    由于可预见的过期时间不是导致令牌无效的唯一因素,因此请务必对应用进行编码,将用户重定向回授权工作流程的开端,以便正确处理遇到的 401 错误。

    第 5 步 — 刷新访问令牌

    为了保护会员的数据,领英不会生成使用期限过长的访问令牌。您应确保应用在构建时能够于到期前刷新用户令牌,避免频繁打扰用户为您授予访问其领英个人资料的权限。

    刷新令牌

    如需刷新访问令牌,请再次遵循本文档中概述的授权流程以获取新令牌。在刷新过程中,假如满足以下条件,系统会自动略过流程的授权对话部分,将用户重定向至您的调用网址,使获取刷新访问令牌变成一次无缝式幕后操作:

    • 用户仍在登录 www.linkedin.com
    • 用户当前的访问令牌尚未到期

    如果用户此时没有登录 www.linkedin.com,或者其访问令牌已到期,他们将需要完成本文档开头部分概述的正常授权流程。

    了解应用权限

    进行所有 REST API 调用之前,您必须首先获得领英会员授予的权限。此系统可确保会员在授权之前充分了解应用将代表他们访问的内容或采取的行动。

    请求会员授予的权限,取决于您在 OAuth 2.0 授权流程期间要求应用请求的权限。您可以在领英应用配置中指定这些权限,也可以在 OAuth 2.0 流程授权步骤期间使用范围参数明确请求的权限。

    如果应用请求获得多个权限以访问其所需的全部数据,则用户需要接受所有此类权限请求才能继续操作。用户不能仅接受其中一部分应用权限的请求。请确保应用仅请求必要的权限,以便为用户打造优质体验。