Reactor API的秘密

在Reactor API中,密碼是代表驗證認證的資源。 在事件轉送中使用密碼來驗證到另一個系統的安全資料交換。 因此,只能在事件轉送屬性(platform屬性設定為edge的屬性)中建立密碼。

type_of屬性中目前表示三種支援的密碼型別:

密碼型別
說明
token
代表兩個系統已知且瞭解的驗證Token值的單一字元字串。
simple-http
包含使用者名稱和密碼的兩個字串屬性。
oauth2-client_credentials
包含數個屬性以支援OAuth驗證規格。 事件轉送會要求您提供必要資訊,然後以指定間隔為您處理這些權杖的續約。

本指南提供如何設定用於事件轉送的密碼的整體概觀。 如需有關如何在Reactor API中管理秘密的詳細指引,包括秘密結構的JSON範例,請參閱秘密端點指南

認證

每個密碼都包含儲存其個別認證值的credentials屬性。 在在API中建立密碼時,每種型別的密碼都有不同的必要屬性,如以下小節所示:

token token

type_of值為token的密碼只需要credentials下的單一屬性:

認證屬性
資料類型
說明
token
字串
目的地系統可識別的秘密權杖。

權杖會儲存為靜態值,因此在建立密碼時,密碼的expires_atrefresh_at屬性會設定為null

simple-http simple-http

type_of值為simple-http的密碼需要credentials下的下列屬性:

認證屬性
資料類型
說明
username
字串
使用者名稱。
password
字串
密碼。 API回應中不包含此值。

建立密碼時,兩個屬性會以username:password的BASE64編碼交換。 交換之後,密碼的expires_atrefresh_at屬性設定為null

oauth2-client_credentials oauth2-client_credentials

type_of值為oauth2-client_credentials的密碼需要credentials下的下列屬性:

認證屬性
資料類型
說明
client_id
字串
OAuth整合的使用者端ID。
client_secret
字串
OAuth整合的使用者端密碼。 API回應中不包含此值。
token_url
字串
Oauth整合的授權URL。
refresh_offset
整數
(選擇性) ​要位移重新整理作業的值(秒)。 如果在建立密碼時省略此屬性,則預設值會設為14400 (4小時)。
options
物件

(選擇性) ​指定OAuth整合的其他選項:

建立或更新oauth2-client_credentials密碼時,會根據OAuth通訊協定的「使用者端認證」流程,在POST要求中將client_idclient_secret (可能還有options)交換給token_url

NOTE
預期授權服務回應本文與OAuth通訊協定相容。

如果授權服務以200 OK和JSON回應本文回應,則會剖析本文並將access_token推送至邊緣環境,並使用expires_in計算密碼的expires_atrefresh_at屬性。 如果密碼上沒有環境關聯,則會捨棄access_token

在以下條件下,憑證交換被視為成功:

  • expires_in大於28800 (8小時)。
  • refresh_offset小於expires_in減去14400的值(四個小時)。 例如,如果expires_in36000 (十小時),而refresh_offset28800 (八小時),則交換會被視為失敗,因為28800大於36000 - 14400 (21600)。

如果交換成功,密碼的狀態屬性會設為succeeded,且會設定expires_atrefresh_at的值:

  • expires_at為目前的UTC時間加上expires_in的值。
  • refresh_at為目前的UTC時間加上expires_in的值減去refresh_offset的值。 例如,如果expires_in43200 (十二小時),而refresh_offset14400 (四個小時),則refresh_at屬性會在目前的UTC時間之後設定為28800 (八個小時)。

如果交換因任何原因失敗,meta物件中的status_details屬性會以相關資訊更新。

正在重新整理oauth2-client_credentials密碼

如果已將oauth2-client_credentials密碼指派給環境且其狀態為succeeded (已成功交換認證),則會在refresh_at上自動執行新的交換。

如果交換成功,meta物件中的refresh_status屬性會設為succeeded,而expires_atrefresh_atactivated_at會相應地更新。

如果交換失敗,會再嘗試作業三次,最後一次嘗試的時間不超過存取權杖過期的兩小時。 如果所有嘗試都失敗,來自meta物件的refresh_status_details屬性會以相關詳細資料更新。

oauth2-google oauth2-google

type_of值為oauth2-google的密碼需要credentials下的下列屬性:

認證屬性
資料類型
說明
scopes
陣列

列出用於驗證的Google產品範圍。 支援下列範圍:

建立oauth2-google密碼之後,回應會包含meta.authorization_url屬性。 您必須複製此URL並貼到瀏覽器中,才能完成Google驗證流程。

重新授權oauth2-google密碼

oauth2-google密碼的授權URL會在密碼建立後一小時到期(如meta.authorization_url_expires_at所指示)。 在這之後,必須重新授權密碼才能更新驗證程式。

若要瞭解如何透過向Reactor API發出PATCH要求來重新授權oauth2-google密碼,請參閱密碼端點指南

環境關係

建立密碼時,您必須指定密碼將存在的環境。 秘密會立即部署到在其中建立它們的環境。

密碼只能與一個環境相關聯。 一旦秘密和環境之間的關係建立,就不能從環境中清除秘密,也不能將秘密與不同的環境相關聯。

NOTE
此規則的唯一例外是刪除相關環境時。 在這種情況下,關係會被清除,且密碼可以指派給不同的環境。

成功交換密碼的認證之後,為了將密碼與環境相關聯,交換成品(token的權杖字串、simple-http的Base64編碼字串或oauth2-client_credentials的存取權杖)會安全地儲存在環境上。

成功在環境中儲存Exchange成品後,密碼的activated_at屬性會設定為目前的UTC時間,現在可以使用資料元素加以參照。 如需參考密碼的詳細資訊,請參閱下一節

引用機密 referencing-secrets

為了參考機密,您必須在事件轉送屬性上建立"機密" (由核心擴充功能提供)型別的資料元素。 設定此資料元素時,系統會提示您指出每個環境要使用的密碼。 然後,您可以建立參考機密資料元素的規則,例如HTTP呼叫的標頭內。

機密資料元素

NOTE
若要將機密資料元素新增至程式庫,您必須至少有一個succeeded機密與正在建立程式庫的環境相關聯。 例如,如果程式庫的機密資料元素沒有為中繼機密區段設定succeeded機密,則嘗試在中繼環境中建置該程式庫會導致錯誤。

在執行階段,秘密資料元素會由儲存在環境中的對應秘密交換成品取代。

後續步驟

本指南說明在Reactor API中處理機密的基礎知識。 如需有關如何使用API呼叫管理密碼的詳細資訊,請參閱密碼端點指南

recommendation-more-help
12b4e4a9-5028-4d88-8ce6-64a580811743