API

最近因為有需求，需要了解一下 Azure APIM 的用法，初步整理一下，從 Kong 的角度來理解新東西。 設定 API 從 Kong 的觀念來理解 Azure APIM 對應之概念 Kong Azure 差異 Service API (或 Backend) 在 Kong 中我們使用 Service 來定義上游 URL；Azure 中則在 API 層定義，或使用 Backend 實體來管理共用的上游設定。 Route Operation Kong 的 Route 負責路徑匹配；Azure 則在 API 層的 Operation 定義具體 HTTP method 與路徑。 Plugin Policy Kong 使用內建 Plugin，直接套用，或使用 lua 寫自訂 plugin；Azure 則使用 XML 定義 Policy。 Consumer Subscription Kong 透過 Consumer 身分來控制 API 存取權；Azure 透過 Subscription (訂閱帳戶) 來控制。每一個「訂用帳戶」都會產生一組 Subscription Key (Primary & Secondary Key)，呼叫 API 時，於 Header 設置 Ocp-Apim-Subscription-Key 來呼叫。 Product 在 Azure APIM 中，API 必須被包在一個 Product 中才能被「訂閱」與呼叫(除非該 API 是 open 的，所有人皆可呼叫)。 ...

前言 本篇算是整理下目前自己對 API 的理解，算是雜談性質，就記錄一下吧。 什麼是 API (Application Program Interface) ? 從文義解釋開始 從文義解釋來看，API 的基本定義是：軟體之間溝通的介面，允許不同系統有規範地交換資料。API 規範了如何向服務提出請求、需要的資料格式，以及回傳結果的形式。 然而文義解釋總是過於抽象，我們還是舉例來說明會比較清楚。在介紹何謂 API 時，最常聽到，會用餐廳點餐來比喻，我這裡也不免俗地用這個方式來說明。 餐廳的例子 Image Source Credit: Celeste Layne - Medium.com 你是餐廳的顧客，菜單代表「服務可以提供那些資料、功能」。當你向服務生點餐（發送請求），服務生將你的請求帶給廚房（資源所在，也就是後端系統）。廚房根據菜單和你的選擇（麵要加大不要辣）的選擇製作食物（處理請求）。最後，服務生把餐點（回應）端給你。 在這個比喻中，服務生就像 API，客戶端（顧客）不直接與後端（資料、邏輯、資源）打交道，而是透過 API 這個介面來溝通下單和取得結果，省去彼此理解內部細節的麻煩。 但是，工具的目的是為了解決問題，重要的不是工具本身，而是背後要解決的那個問題。因此我們要進一步思考的是，如果沒有 API，會如何？ 軟體之間就必須「直接訪問」彼此的資料或功能，彼此須了解對方的內部細節，如同點菜時顧客沒有按照制式的菜單點餐，廚房根本不知道怎麼出菜，最後本人必須進廚房了解每一道手續，如此一來餐廳根本無法運作。但若真的讓顧客直接進餐廳，如此，就會缺乏安全隔離，外部程式可以隨意取得資料，使系統變得脆弱，就像顧客可能將病原體帶入廚房，污染食材。同時，維護上若有需要調整，將會修改困難，比方說內部實作細節更改，取用者要如何取得資料，必須重新理解取用過程。 舉例來說，如果沒有 API，你開發一個 App，需要取得 google 地圖的資料、處理金流等功能時，你得直接接觸這些系統的底層，理解提供服務者的內部結構才能夠拿到你想要的東西。 訂購人的困境 OK，現在每一家餐廳都有自己的菜單與訂購單，解決了廚房的溝通問題。這解決了單一廚房點餐的問題，基本上只要看得懂上面菜單的文字，就可以知道這張單要出甚麼內容。我們有了 API 了！ 但若場景變成：要對多個餐廳要同時下單，你是訂便當股長，就會遇到要對應不同便當店，要看懂每家的菜單格式，還要想辦法看懂各位同事自由格式的信件內容，也就是你要適應不同格式，結果就是增加了溝通成本。 例如上圖，每間餐廳的菜單風格迥異。 開發人員的困境 回到開發場景。來做個系統吧，資訊人員一定會幫我們解決這個問題，降低便當股長的離職率。但資訊人員遇到了問題，那就是他要去串接的每個店家，他的訂購單格式都不一樣，此時面對了一些抉擇： 鍛鍊資訊人員，所有店家都客製作下去，但這可能會提高資訊人員離職率。 訓練資訊人員的溝通能力，配合專案經理，以及外部合作商，談訂一個共同的規格。 很遺憾的，上面那兩個選項，偉大的老闆選了項目 1，為了不影響其他合作商，所以決定讓自己的工程師處理。 如果每個合作對象（例如不同餐廳）都用自己的格式來傳遞資料，資訊人員（工程師）就必須針對每一種格式，開發不同的「解析」方法。舉例來說： 有的店家用 Word 檔案下訂單，有的用 Excel，有的用 PDF，有的直接寄圖片，有的用網頁表單。工程師就要寫很多不同的程式，來讀取和理解這些不同的檔案格式。 如果店家改變了檔案格式（例如 Word 從 2003 版換成 2007 版），工程師的程式就可能失效，要重新修改。 有的 Excel 檔案可能被植入病毒，還要擔心安全問題。 如果是圖片，還要用影像辨識技術來「看懂」圖片內容，萬一圖片字體換了，辨識又會出錯。 ...

前言 當你的 API 以 OpenID Connect 協定實作 authentication(認證)時，就會使用到 Kong OIDC(OpenID Connect) plugin。本篇要關注的是，當利用 OpenID Connect 協定，讓 Kong 在認證階段自動與 IdP（例如 ADFS）整合，獲取並驗證 JWT Token，保證只有合法使用者能夠存取上游服務的這個過程。 驗證流程 當 Kong 收到來自 consumer 的請求後，會進行以下流程： Issuer Discovery Kong 透過 OIDC plugin 中的 issuer 參數，從 .well-known/openid-configuration URL，自動抓取 IdP 的 Metadata。Metadata 包含 jwks_uri（JSON Web Key Set）endpoint，用於後續公鑰獲取。 若在 plugin 的 extra_jwks_uris 有設定放置公鑰的 URL，Kong 會先依序對每個 extra_jwks_uris URL 嘗試下載 JWKS。若所有 extra_jwks_uris 都無法成功（連線失敗或無對應公鑰），再從 .well-known/openid-configuration 中的 jwks_uri 嘗試；若未設定 extra_jwks_uris，則會直接使用 .well-known Metadata 提供的 jwks_uri。 Token 取得: Kong 會對 ADFS 發起請求並獲取並 JWT Token。 ...

概述 本文紀錄如何在已運行一個 API 服務的 IIS 伺服器上，部署第二個（例如測試用）API。 方法：在同一個網站下建立子應用程式 (Sub-application) 這是在現有網站下新增 API 最直接的方法，因為此方法不需要更改 DNS 或防火牆規則（否則你要設定新的 domain name，或是在既有 domain 下使用一個未使用的 port），僅透過 URL 路徑來區分不同的 API。例如： 正式 API 呼叫路徑：http://yourdomain.com/endpoint 測試 API 呼叫路徑：http://yourdomain.com/test-api/endpoint 原理說明：應用程式集區 (Application Pool) 的隔離機制 「應用程式集區」是 IIS 中實現服務隔離的關鍵。它是一個獨立的容器，由 IIS 工作者處理序 (w3wp.exe) 管理。為新的測試 API 建立一個「全新的、獨立的」應用程式集區主要有以下三個好處： 隔離性 (Isolation)：最重要的優點。如果測試 API 因錯誤而崩潰，只會影響其自身的集區，正式運行的 API 服務將完全不受影響，確保了主服務的穩定性。 安全性 (Security)：可以為不同的集區設定不同的執行身分 (Identity)，從而對檔案系統、資料庫等資源進行權限隔離。 獨立設定 (Configuration)：每個集區可以有獨立的設定，如 .NET 版本、記憶體上限、CPU 使用率限制等，讓正式與測試環境的配置完全分開。 IIS 設定步驟 開啟 IIS 管理器，在左側窗格中找到您現有的網站。 在網站上按右鍵，選擇「新增應用程式」。 在「新增應用程式」視窗中，填寫以下資訊： 別名 (Alias)：設定 URL 路徑，例如 test-api。這將成為新 API 的存取路徑的一部分。 實體路徑 (Physical path)：指向您測試 API 發布檔案所在的資料夾。 應用程式集區 (Application Pool)： 點擊「選取…」。 在彈出視窗中，點擊「新增…」來建立一個新集區。 為新集區命名（例如 TestApiAppPool）。 (.NET Core 的設定於後面詳述) 確認選取了這個剛剛建立的新集區。 點擊「確定」完成設定。 部署 .NET Core API 的特別注意事項 部署 .NET Core / .NET 5+ 的應用程式時，其運作模式與傳統 ASP.NET Framework 不同，設定上有一處關鍵差異。 ...

小弟最近要接手管理 APIM 了，會把踩的點記錄下來。 在管理 Kong API Gateway 的過程中，發現在啟用 IP Restriction Plugin 並設置白名單後，該 consumer 仍然驗證失敗。經確認此情況與 IP 置換有關。 該 consumer request 路徑為： Client → Load Balancer → Kong API Gateway → Backend Service 在這樣的架構中，Kong 接收到的 IP 並不是實際的 Client IP，而是來自 Load Balancer 的內部 IP。 經確認： Kong 接收到的 client_ip 顯示為內部網段 IP（例如：以 .254 結尾）。 這些 IP 實際上是 Load Balancer 的 IP。 導致 IP Restriction Plugin 誤判來源 IP，合法用戶被錯誤拒絕。 Nginx 真實 IP 辨識機制 Kong 是建構在 Nginx 之上，利用 Nginx 的 ngx_http_realip_module 模組來從 HTTP Header 中擷取真正的 Client IP，並改寫 $remote_addr。 ...