Azure APIM 中的訂用帳戶
適用於：所有 API 管理 層
在 Azure API 管理中，「訂用帳戶」是 API 取用者用來存取透過 API 管理執行個體發佈之 API 的最常見方式。 本文提供下列概念的概觀。
注意
APIM 訂用帳戶專門用於使用訂用帳戶金鑰，透過 APIM 呼叫 API。 這與 Azure 訂用帳戶不同。
什麼是訂用帳戶？
藉由透過 API 管理發佈 API，您可以輕鬆地使用訂用帳戶金鑰來保護 API 存取。 需要取用已發佈 API 的開發人員在呼叫那些 API 時，必須在 HTTP 要求中包括有效的訂用帳戶金鑰。 若無有效的訂用帳戶金鑰，呼叫將會：
- 立即遭到 API 管理閘道拒絕。
- 不會轉送到後端服務。
若要存取 API，開發人員需要訂用帳戶與訂用帳戶金鑰。 「訂用帳戶」是一對訂用帳戶金鑰的具名容器。
此外，
- 開發人員可以在無需 API 發行者核准的情況下取得訂用帳戶。
- API 發行者可以直接為 API 取用者建立訂用帳戶。
管理訂用帳戶金鑰
定期重新產生金鑰是常見的安全性預防措施。 就像大部分需要訂用帳戶金鑰的 Azure 服務，API 管理也會產生成對金鑰。 每個使用服務的應用程式都可從「金鑰 A」切換至「金鑰 B」，並在造成最少中斷的情況下重新產生金鑰 A，反之亦然。
叫用 Azure APIM 訂用帳戶 - 建立或更新 Azure REST API，即可設定特定金鑰，而不是重新產生金鑰。 具體而言，必須在 HTTP 要求本文中設定 properties.primaryKey 和/或 properties.secondaryKey。
注意
- 「API 管理」不提供內建功能來管理訂用帳戶金鑰的生命週期，例如，設定到期日或自動輪替金鑰。 您可以使用 Azure PowerShell 或 Azure SDK 等工具來開發工作流程，以將這些流程自動化。
- 為了強制執行對 API 的限時存取，API 發行者可能會搭配訂用帳戶金鑰使用原則，或使用提供內建到期的機制，例如權杖型驗證。
訂用帳戶的範圍
訂用帳戶可以與各種範圍相關聯：產品、所有 API 或個別 API。
產品的訂用帳戶
傳統上，API 管理中的訂用帳戶會與單一產品範圍相關聯。 開發人員：
- 可在開發人員入口網站上找到產品清單。
- 針對想要使用的產品提交訂用帳戶要求。
- 使用那些訂用帳戶 (已自動核准或由 API 發行者核准) 中的金鑰來存取產品中的所有 API。
目前，開發人員入口網站只會在 [使用者設定檔] 區段下方顯示產品範圍訂用帳戶。
適用於所有 API 或個別 API 的訂用帳戶
您也可以建立金鑰來為下列各項授與存取權：
- 單一 API，或
- API 管理執行個體內的所有 API。
在這些情況下，您不需先建立產品並為其新增 API。
所有存取訂用帳戶
每個 APIM 執行個體均隨附一個內建的所有存取訂用帳戶，可授與所有 API 的存取權。 此服務範圍的訂用帳戶讓服務擁有者能以直覺方式，在測試主控台內進行 API 測試和偵錯。
警告
所有存取訂閱可供存取 API 管理執行個體中所有的 API，此訂閱僅應由授權使用者使用。 請勿將此訂閱用於常式 API 存取，也不要將所有存取訂閱金鑰在內嵌在用戶端應用程式中。
注意
如果您使用 API 範圍的訂用帳戶、所有 API 訂用帳戶或內建的所有存取訂用帳戶，則在產品範圍中設定的原則都不會套用至來自該訂用帳戶的要求。
獨立訂用帳戶
APIM 也允許「獨立」訂用帳戶，其不會與開發人員帳戶相關聯。 此功能在有數個開發人員或小組共用一個訂用帳戶的類似案例中相當實用。
在未指派擁有者的情況下建立訂用帳戶，會使其成為獨立訂用帳戶。 若要為開發人員和小組的其他成員授與對獨立訂用帳戶金鑰的存取權，請採用下列其中一種方式：
- 手動共用訂用帳戶金鑰。
- 使用自訂系統，讓訂用帳戶金鑰可供您的小組使用。
在 Azure 入口網站中建立及管理訂用帳戶
API 發行者可以直接在 Azure 入口網站中，建立訂閱。
在入口網站中建立時，訂用帳戶會處於使用中狀態，這表示訂閱者可以使用有效的訂用帳戶金鑰來呼叫相關聯的 API。 您可以視需要變更訂用帳戶的狀態。 例如，您可以暫止、取消或刪除任何訂用帳戶 (包括內建的所有存取訂用帳戶)，以防止 API 存取。
使用訂用帳戶金鑰
訂閱者可以透過下列兩種方式之一來使用 APIM 訂用帳戶金鑰：
將 Ocp-Apim-Subscription-Key HTTP 標頭新增至要求，以傳遞有效訂用帳戶金鑰的值。
在 URL 中包含 subscription-key 查詢參數和有效值。 只有當標頭不存在時，才會檢查查詢參數。
提示
Ocp-Apim-Subscription-Key 是訂用帳戶金鑰標頭的預設名稱，而 subscription-key 是查詢參數的預設名稱。 您可以視需要在每個 API 的設定中修改這些名稱。 例如，在入口網站中，於 API 的 [設定] 索引標籤上更新這些名稱。
注意
包含在要求標頭或查詢參數中時，訂用帳戶金鑰預設會傳遞至後端，而且可能會在後端監視記錄或其他系統中公開。 如果這被視為敏感性資料，則您可在 [inbound] 區段結尾設定原則，以移除訂用帳戶金鑰標頭 (set-header) 或查詢參數 (set-query-parameter)。
啟用或停用 API 或產品存取的訂用帳戶需求
根據預設，當您建立 API 時，API 存取需要訂用帳戶金鑰。 同樣地，當您建立產品時，預設需要有訂用帳戶金鑰，才能存取任何新增至產品的 API。 在某些情況下，API 發行者可能想要在不需使用訂用帳戶的情況下，公開發佈產品或特定 API。 雖然發行者可以選擇對特定 API 啟用不安全 (匿名) 的存取，但還是建議您設定另一個機制來保護用戶端存取。
警告
設定不需要訂用帳戶的產品或 API 時，請格外小心。 此設定可能過於寬鬆，而且可能會讓 API 更容易遭受特定的 API 安全性威脅。
注意
開啟的產品已 停用 [需要訂 用帳戶] 設定，這表示使用者不需要訂閱。 基於這個理由，開啟的產品不會顯示在 開發人員入口網站的 [產品 ] 頁面上。
您可以在建立 API 或產品時，或在日後，停用訂用帳戶需求。
使用入口網站停用訂用帳戶需求：
- 停用產品需求：在產品的 [設定] 頁面上，停用 [需要訂用帳戶]
- 停用 API 需求：在 API 的 [設定] 頁面上，停用 [需要訂用帳戶]。
停用訂用帳戶需求之後，即可在沒有訂用帳戶金鑰的情況下存取選取的一或多個 API。
API 管理如何處理具有或不具訂用帳戶金鑰的要求
具有訂用帳戶金鑰的 API 要求
當 API 管理收到來自沒有訂用帳戶金鑰之用戶端的 API 要求時，會根據下列規則處理要求:
檢查其是否為與作用中訂用帳戶相關聯的有效金鑰，無論是:
- 範圍設定為 API 的訂用帳戶
- 範圍設定為指派給 API 之產品的訂用帳戶
- 範圍設定為所有 API 的訂用帳戶
- 服務範圍訂用帳戶 (內建的所有存取訂用帳戶)
如果提供適當範圍內作用中訂用帳戶的有效金鑰，則允許存取。 原則會根據該範圍的原則定義設定來套用。
否則，會拒絕存取 (401 拒絕存取錯誤)。
具有訂用帳戶金鑰的 API 要求
當 API 管理收到來自沒有訂用帳戶金鑰之用戶端的 API 要求時，會根據下列規則處理要求：
- 先檢查包括該 API 但不需訂用帳戶的產品 (「開放」產品) 是否存在。 如果開放產品存在，在為該產品設定的 API、原則及存取規則的內容中處理要求。 API 最多可以與一個開放產品相關聯。
- 如果找不到包括該 API 的開放產品，檢查該 API 是否需要訂用帳戶。 如果不需要訂用帳戶，在該 API 和作業的內容中處理要求。
- 如果找不到已設定的產品或 API，則會拒絕存取 (401 拒絕存取錯誤)。
摘要表
下表摘要說明閘道在不同案例中，如何在有無訂用帳戶金鑰的情況下處理 API 要求。 請注意可能啟用非預期匿名 API 存取的設定。
| 指派給 API 的所有產品都需要訂用帳戶 | API 需要訂用帳戶 | 使用訂用帳戶金鑰進行 API 呼叫 | 不使用訂用帳戶金鑰進行 API 呼叫 | 典型案例 |
|---|---|---|---|---|
| ✔️ | ✔️ | 允許存取： • 產品範圍的金鑰 • API 範圍的金鑰 • 所有 API 範圍的金鑰 • 服務範圍的金鑰 拒絕存取： • 未將範圍限定於適用產品或 API 的其他金鑰 |
拒絕存取 | 使用產品範圍或 API 範圍訂用帳戶保護的 API 存取 |
| ✔️ | ❌ | 允許存取： • 產品範圍的金鑰 • API 範圍的金鑰 • 所有 API 範圍的金鑰 • 服務範圍的金鑰 拒絕存取： • 未將範圍限定於適用產品或 API 的其他金鑰 |
允許存取 (API 內容) | • 使用產品範圍訂用帳戶保護的 API 存取 •匿名存取 API。 如果不適合匿名存取，請設定 API 層級原則來強制執行驗證和授權。 |
| ❌1 | ✔️ | 允許存取： • 產品範圍的金鑰 • API 範圍的金鑰 • 所有 API 範圍的金鑰 • 服務範圍的金鑰 拒絕存取： • 未將範圍限定於適用產品或 API 的其他金鑰 |
允許存取 (開啟產品內容) | • 使用 API 範圍訂用帳戶保護的 API 存取 •匿名存取 API。 如果不適合匿名存取，請設定產品原則來強制執行驗證和授權 |
| ❌1 | ❌ | 允許存取： • 產品範圍的金鑰 • API 範圍的金鑰 • 所有 API 範圍的金鑰 • 服務範圍的金鑰 拒絕存取： • 未將範圍限定於適用產品或 API 的其他金鑰 |
允許存取 (開啟產品內容) | 匿名存取 API。 如果不適合匿名存取，請設定產品原則來強制執行驗證和授權 |
1 存在與 API 相關聯的開放式產品。
考量
- 不論產品是否已發佈，產品內容中的 API 存取都相同。 取消發佈產品會從開發人員入口網站中將之隱藏，但不會使新的或現有的訂用帳戶金鑰失效。
- 即使產品或 API 不需要訂用帳戶，仍可使用使用中訂用帳戶的有效金鑰來存取產品或 API。
- API 存取「內容」表示在特定範圍 (例如 API 或產品) 上套用的原則和存取控制。
下一步
取得 APIM 的詳細資訊：