API 教程：獲取經過身份驗證的 ORCID iD

我們建議開發人員在 沙盒測試服務器 在使用生產版本之前。 以下是有關如何在沙盒和生產環境中註冊公共 API 憑證的步驟。

• 登錄你的 ORCID 記錄：
  生產服務器： https://orcid.org/signin
  沙盒測試服務器： https://sandbox.orcid.org/signin
• 在右上角點擊你的名字
• 點擊 開發者工具 從菜單選項
  注意： 為了訪問開發人員工具，您必須驗證您的電子郵件地址。 如果您尚未驗證您的電子郵件地址，系統會提示您進行驗證，然後才能註冊公共 API 憑據
• 閱讀並同意‘ORCID 公共 API 服務條款
• 點擊“註冊 ORCID 公共 API 憑證”按鈕。

填寫申請詳情表

• 註冊公共 API 憑證後，您將被引導回開發人員工具（https://orcid.org/developer-tools or https://sandbox.orcid.org/developer-tools).
• 您需要填寫提交的申請詳細信息表以註冊新申請。
  • 名稱：您的應用程序的名稱。 當用戶授予您的應用程序權限以獲取他們的權限時，這將顯示給用戶 ORCID iD，它將顯示在他們的 受信任組織列表. 我們建議使用您的組織或服務的名稱（例如期刊名稱）。
  • 申請網址： 用戶可以訪問該網站以了解有關您的應用程序的更多信息。 這也將顯示在他們的 受信任組織列表.
  • 應用說明：有關您正在開發的應用程序以及您將如何使用用戶的應用程序的信息 ORCID ID。 這將在 OAuth 屏幕上向用戶顯示。

將 重定向 URI

用戶授權您的應用程序後，他們將返回到您指定的 URI。 您必須提前提供這些 URI，否則您的集成用戶將遇到錯誤。

• 在提供的框中輸入您的重定向 URI
• 如果您需要輸入超過 1 個重定向 URI，請單擊“添加另一個重定向 URI”

請注意：

• 只 HTTPS URI 已在生產中接受
• 已註冊的域 必須（MUST） 與使用的域完全匹配，包括子域
• 盡可能完整註冊所有重定向 URI。 這是最安全的選項，也是我們推薦的選項。 有關重定向 URI 的更多信息，請參閱我們的 重定向 URI 常見問題解答

保存您的申請

填寫完申請表並添加重定向 URI 後，您可以保存您的申請。

• 點擊“儲存我的申請並產生我的客戶端 ID 和密碼”

您將被引導回開發人員工具頁面，該頁面現在將包含您的公共 API 客戶端憑據

更新您的憑據

更改您的申請信息非常簡單。

• 編輯相關信息，然後點擊“保存申請”

使用您的憑據

現在您已擁有憑據，是時候開始使用 ORCID 公共API！

請注意，如果您成為會員，我們可以將您的憑據傳輸到會員 API ORCID 會員 。

您可以 請求沙箱會員 API 憑證 建立並測試您的應用程式。這些憑證可讓您呼叫沙盒高級會員 API 來讀取、寫入和更新 ORCID 記錄。 任何人都可以免費訪問沙盒測試環境，即使您不是 ORCID 會員組織。

備註：如果您使用的是 ORCID 已支援的認證服務提供者係統 ORCID，您不需要註冊沙盒 API 憑證，除非您想嘗試 ORCID 沙盒環境中的整合功能。 

沙箱讓您可以創建測試用戶帳戶並開發您的集成，而不必擔心影響實時（生產）上的數據 ORCID 註冊表。 沙箱的行為方式與生產相同 ORCID 註冊與 一些例外.

創建測試帳戶

為了測試 ORCID API 和 API 調用，例如讀取和添加信息到 ORCID 記錄，您還需要創建一個測試 ORCID 記錄在沙箱中。 這可以通過用戶界面完成，就像在生產中一樣 ORCID 註冊表。 去 https://sandbox.orcid.org/register 並註冊一個帳戶。

郵寄者電子郵件地址

沙盒伺服器僅將電子郵件發送至 Mailinator (@mailinator.com) 電子郵件地址，以免無意中向郵件服務器發送垃圾郵件。 除非您使用@mailinator.com 地址，否則您不會收到驗證電子郵件或密碼重置通知，並且需要驗證才能對沙盒記錄進行任何手動編輯。 詳細了解他們免費使用的公共收件箱 並點選這裡。 如果您不想使用 Mailinator 地址，然後請記下您的用戶名和密碼（因為您將在測試時使用它們向您的應用程序授予授權），並聯繫我們請求驗證幫助。

Mailinator 是一種具有公共免費服務和私人付費服務的電子郵件服務。 對於測試，您可以使用完全免費的公共服務。 了解更多關於他們的等級 這裡.

Mailinator 是第三方服務，不受管理或維護 ORCID. 我們建議您在使用這些地址之前查看此服務的工作原理及其限制。

什麼是重定向 URI，它們是如何使用的？
我們的 OAuth 身份驗證服務使用重定向 URI 作為安全措施。  ORCID 只會將身份驗證用戶發送到請求身份驗證的客戶端註冊的 URI。 這可以防止服務相互模仿。

請注意 僅 HTTPS URI 在生產中被接受。 您可以使用 HTTP URI 進行測試，但您需要註冊 HTTPS URI 當您申請生產成員 API 憑證時。

我們如何匹配重定向 URI？

• 您必須將子域註冊為單獨的 URI. https://anythingelse.thirdparty.com 將不起作用。  
• 鼓勵完全註冊所有重定向 URI，包括路徑, 是大多數第三方所做的，也是最安全的選擇。
• 如果客戶端應用程序註冊的重定向 uri 只是主機名，則可以使用該主機上的任何重定向 uri. 因此，例如，如果註冊了以下重定向 uri： https://thirdparty.com 那麼以下所有 redirect_uris 都將起作用：
  • https://thirdparty.com/oauth/callback1
  • https://thirdparty.com/callback2
  • https://thirdparty.com/anything-else-as-long-as-the-host-is-the-same

但是，https://anythingelse.thirdparty.com 不管用。  您 必須（MUST） 將子域註冊為單獨的 URI。

如果我的重定向 URI 不正確會怎樣？

發送到驗證的用戶 ORCID 使用不正確的重定向 URI 將看到類似於此的錯誤消息：

管理成員的重定向 URI

如果您使用會員 API 並需要對重定向 URI 進行任何更改，請聯繫我們的參與團隊

管理公共客戶端的重定向 URI

如果您使用的是公共 API，那麼您將需要按照以下步驟更新與您的關聯的重定向 URI 列表 ORCID 公共 API 客戶端 ID。 您可以按照以下步驟執行此操作：

• 登錄到您的 ORCID 記錄
• 點擊右上角你的名字
• 選擇開發者工具
• 點擊客戶名稱旁邊的編輯鉛筆
• 編輯現有的重定向 URI 或單擊“添加另一個重定向 URI”編輯現有的
• 完成更改後，您需要單擊保存圖標

僅 HTTPS URI 在生產中被接受。 您可以使用 http URI 進行測試，但在申請生產成員 API 憑證時需要註冊 HTTPS URI。

ORCID 集成使用“3 legged OAuth”來驗證用戶並請求與他們的記錄交互的權限。 任何集成都可以使用公共 API 請求讀取權限。 ORCID 會員可以使用會員 API 請求更新權限。 它是這樣工作的：

• 您創建了一個特殊鏈接
• 單擊時，用戶將被發送到 ORCID
  • ORCID 要求用戶登錄
  • ORCID 要求用戶授予您的應用程序權限
  • ORCID 使用授權碼將用戶發送回您的系統
• 您的系統將該代碼交換為訪問令牌

定制的授權 URL 包括您的客戶信息，以及指定您希望訪問的他們記錄的特定區域的“範圍”。 登錄後，用戶授權與您的系統連接，並與授權代碼一起返回到您的登錄頁面。 然後使用此代碼獲取他們的 ORCID iD 以及對請求的範圍有效的訪問令牌。

建立授權鏈接並獲取授權碼

您可以透過指定 API 憑證的用戶端 ID 和關聯的登入頁面（重定向 URI）來建立授權連結。您可以透過設定來選擇請求哪些權限 範圍參數.

下面的示例請求讀取限制訪問數據的權限 ORCID 沙盒測試服務器。 在現實世界中，您會在您的網站上顯示此鏈接，或者在要求用戶進行身份驗證和授權時將其包含在電子郵件中。 但是，出於測試目的，您可以簡單地將其粘貼到您的網絡瀏覽器中。 用您的客戶信息替換括號中的數據，並確保刪除方括號！

https://sandbox.orcid.org/oauth/authorize?client_id=[Your client ID]&response_type=code&scope=/read-limited&redirect_uri=[Your landing page]

一個用戶點擊了鏈接，登錄於 ORCID 並授予權限，他們將被重定向回您的網站，如下所示：

https://[Your landing page]?code=Q70Y3A

交換授權碼 ORCID iD 和訪問令牌

您應該立即交換授權碼 ORCID iD 和訪問令牌。 授權碼在使用時過期。 請求看起來像這樣 不能在網絡瀏覽器中製作，它必須由您的服務器製作。

 URL=https://sandbox.orcid.org/oauth/token
  HEADER: Accept: application/json
  HEADER: Content-Type: application/x-www-form-urlencoded
  METHOD: POST
  DATA: 
    client_id=[Your client ID]
    client_secret=[Your client secret]
    grant_type=authorization_code
    code=Six-digit code
    redirect_uri=[Your landing page]

ORCID 然後將返回研究人員的認證 ORCID iD 和一個 JSON 格式的訪問令牌：

{"access_token":"f5af9f51-07e6-4332-8f1a-c0c11c1e3728","token_type":"bearer",
"refresh_token":"f725f747-3a65-49f6-a231-3e8944ce464d","expires_in":631138518,
"scope":"/read-limited","name":"Sofia Garcia","orcid":"0000-0001-2345-6789"}

默認情況下，訪問令牌是長期存在的，並在發行後 20 年到期。 令牌在到期前可以多次使用。

使用訪問令牌

三足訪問令牌鏈接到特定的 ORCID 記錄。 要使用它們，您可以將它們包含在您為讀取或更新該記錄而發出的 API 請求中。

隱式 OAuth 是 OAuth 的輕量級版本，旨在供沒有或不想使用服務器端組件的系統使用。 隱式 OAuth 可以完全在瀏覽器中單獨使用 javascript 實現。 它適用於會員和非會員，工作方式如下：

• 您創建了一個特殊鏈接
• 單擊時，用戶將被發送到 ORCID
  • ORCID 要求用戶簽署我
  • ORCID 要求用戶授予您的應用程序權限
  • ORCID 將用戶發送回您的系統 ORCID iD、存取令牌和 ID 令牌。
• 您的系統提取並存儲經過身份驗證的 ORCID iD 從響應。

出於安全原因，在使用隱式 OAuth 時， ORCID 不會返回具有更新權限的訪問令牌。

隱式流

隱式流程的設計使得客戶端不需要使用他們的秘密密鑰來啟動 ORCID 登錄。通過將客戶端限製到其註冊的 redirect_url 來強制執行安全性。 這種較低的安全級別意味著 ORCID 使用隱式流時僅支持 /authenticate 和 openid 範圍。 代幣也是短暫的，只有 10 分鐘的壽命。 建議將此流程用於無法訪問後端服務器的客戶端應用程序，例如電話應用程序或單頁 javascript web 應用程序。

https://localhost/#access_token=24c11342-f5da-4cf9-94a4-f8a72a30da00&token_type=bearer&expires_in=599&tokenVersion=1&persistent=false&id_token=eyJraWQiOiJxYS1vcmNpZC1vcmctcjlhZmw3cWY2aG2c5bmdzenU1bnQ3Z3pmMGVhNmkiLCJhbGciOiJSUzI1NiJ9.eyJhdF9oYXNoIjoiMW52bXZBbVdwaVd0Z3ZKZW1DQmVYUSIsImF1ZCI6IkFQUC02TEtJSjNJNUIxQzRZSVFQIiwic3ViIjoiMDAwMC0wMDAyLTUwNjItMjIwOSIsImF1dGhfdGltZSI6MTUwNTk4Nzg2MiwiaXNzIjoiaHR0cHM6XC9cL29yY2lkLm9yZyIsIm5hbWUiOiJNciBDcmVkaXQgTmFtZSIsImV4cCI6MTUwNTk4ODQ2MywiZ2l2ZW5fbmFtZSI6IlRvbSIsImlhdCI6MTUwNTk4Nzg2Mywibm9uY2UiOiJ3aGF0ZXZlciIsImZhbWlseV9uYW1lIjoiRGVtIiwianRpIjoiY2U0YzlmNWUtNTBkNC00ZjhiLTliYzItMmViMTI0ZDVkNmNhIn0.hhhts2-4-ibjXPW6wEsFRaNqV_A-vTz2JFloYn7mS1jzQt3xuHiSaSIiXg3rpnt1RojF_yhcvE9Xe4SOtYimxxVycpjcm8yT_-7lUSrc46UCt9qW6gV7L7KQyKDjNl23wVwIifpRD2JSnx6WbuC0GhAxB5-2ynj6EbeEEcYjAy2tNwG-wcVlnfJLyddYDe8AI_RFhq7HrY4OByA91hiYvHzZ8VzoRW1s4CTCFurA7DoyQfCbeSxdfBuDQbjAzXuZB5-jD1k3WnjqVHrof1LHEPTFV4GQV-pDRmkUwspsPYxsJyKpKWSG_ONk57E_Ba--RqEcE1ZNNDUYHXAtiRnM3w

請參閱我們的 技術文檔 獲取更多訊息

OpenID Connect 1.0 是 OAuth 2.0 協議之上的一個簡單的身份層。 它補充了現有的 OAuth 身份驗證流程，並以良好描述的方式向客戶端提供有關用戶的信息。

OpenID 連接是實現 OAuth 和共享有關已驗證用戶的信息的標準化方法。 現在可以配置要使用的服務 ORCID 與其他符合標準的 OpenID 連線提供者一起「開箱即用」。 OpenID connect 還提供可共享的 ID 令牌，這些令牌是簽名對象，可以證明使用者已通過身份驗證 ORCID 在特定時間。 用戶界面元素可以使用這些令牌來維護用戶會話。

ORCID 支持 Basic OpenID Provider 一致性配置文件，它是 OAuth 授權代碼流的擴展。 ORCID 還支持“/authenticate”和“openid”範圍的隱式令牌流。

這意味著 ORCID:

• 將簽署的 id 令牌嵌入令牌回應中，以取得使用「openid」範圍產生的授權代碼
• 使用“token”或“token id_token” response_types 和“openid”範圍時支持隱式流。
• 支持包含“openid”範圍的授權請求的“prompt”、“nonce”和“max_age”參數。
• 支持 Openid Connect 發現和 userinfo 端點
• 支持集成商使用成員 API 進行包含“openid”範圍的授權請求的“amr”字段。 這可用於發現用戶是否使用兩因素身份驗證進行身份驗證。

啟動 OpenID Connect 身份驗證的工作方式與常規 OAuth 身份驗證相同。 所需要的只是客戶端請求“openid”範圍如果您使用/authenticate 範圍，請將其替換為openid，因為authenticate 和openid 具有相同的授權，只能使用一個或另一個。 如果您正在使用任何其他範圍，請將 openid 添加到請求的範圍列表中。 當包含 openid 範圍時，註冊表將在令牌響應中返回一個 id_token 並授予客戶端訪問該用戶的用戶信息端點的權限。

請注意，“openid”範圍不像其他範圍那樣以“/”開頭 ORCID API 範圍。 這是因為“openid”範圍不是由 ORCID，而是由 OpenID Connect 規範定義。

請參閱我們的 技術文檔 獲取更多訊息

ORCID 提供了一個簡單的 Java 腳本小部件 可用於獲取經過身份驗證的 ORCID 使用 OAuth 和 OpenID Connect 的 ID。

請注意，該小部件使用隱式 OAuth，因此不會收集任何寫入權限。 這意味著它不適合希望更新記錄的成員集成。 請參閱我們的教程 添加和更新數據 ORCID 紀錄。