API Gateway – 認証・認可詳説 Subhead goes here on one line Name 日本オラクル株式会社 May, 2022

API Gatewayを活用したWeb APIに対する認証・認可処理 • API Gatewayの機能を活用することで、各アプリケーションに実装していた認証・認可処理をオフロード • バックエンド実行基盤は、よりビジネスロジックに集中できる • API Gatewayで一元管理することで、認証強度や鍵のライフサイクル管理を統一できる Copyright © 2022, Oracle and/or its affiliates 2 User Functions Functions Functions ビジネスロジック + 認証・認可処理 ビジネスロジック + 認証・認可処理 ビジネスロジック + 認証・認可処理 API Gateway User Functions Functions Functions ビジネスロジック ビジネスロジック ビジネスロジック API Gateway 認証・認可処理を API Gatewayにオフロード

API Gatewayで行われる認証・認可処理の基本的な動き 1. エンドユーザーが認証・認可のために必要な情報（ID/Password, JWT, etc.）含めてリクエストを送信 2. API Gatewayにて、認証やJWTの検証処理が行われる。方法は以下の2通り。 • Oracle Functionsで実装したロジック（Authorizer Functions）を用いて、認証を行う • 設定値に基づき、JWT(JSON Web Token)の検証を行う 3. 認証結果、検証済みのJWTに含まれるscopeを用いて、各パス単位に認可処理を行う • スキップ（認可処理を実行しない）も可能 Copyright © 2022, Oracle and/or its affiliates 3 User Functions Functions Functions API Gateway 1. 資格情報、JWT 2. 資格情報を用いて認証や JWTの検証処理を行う 3. 各パス単位にscopeを 用いた認可処理 list:greet create:greet update:greet delete:greet list:greet list:greet create:greet create:greet create:greet

Authorizer Function • HTTPリクエスト（ヘッダー or クエリーパラメーター） に含まれる情報を認証処理を行うOracle Functions(Authorizer Functions)へ渡し、検証す る事で認証処理を行う • （オプション）返却された認証結果に含まれるscope を用いて認可処理を行う JWT Validator • HTTPリクエスト（ヘッダー or クエリーパラメーター） に含まれるJWTをAPI Gatewayで検証する • （オプション）検証済みのJWTに含まれているscope を用いて、認可処理を行う 提供されている認証・認可のための機能 Copyright © 2022, Oracle and/or its affiliates 4 Functions Functions Functions API Gateway Functions Functions Functions API Gateway Functions Identity Provider JWKs Endpoint Public Key 認証依頼 認証結果 （オプション）認証結果に含まれる scopeを用いて認可処理 JWTの検証 - 署名の検証 - Issuerの検証 - Audienceの検証 - 有効期限の検証 - etc. （オプション）検証済みJWTのPayloadに 含まれるscopeを用いて認可処理 Identity Domains/IDCS Auth0 Okta Keycloak etc.

Copyright © 2022, Oracle and/or its affiliates 5 Authorizer Functions

Authorizer Functionsを用いた処理のシーケンス Copyright © 2022, Oracle and/or its affiliates 6 Enduser API Gateway Oracle Functions Backend 資格情報を送信 -H “xxx: ” or https://xxx?yyy= API Gatewayから既定の形式で 認証処理のリクエスト 認証処理 API Gatewayへ既定の形式で 認証結果のレスポンス 認証処理失敗: HTTP 401 検証成功: バックエンドへリクエスト 認可処理失敗: HTTP 404 認可処理

Authorizer Functionsを用いた処理のシーケンス Copyright © 2022, Oracle and/or its affiliates 7 Enduser API Gateway Oracle Functions Backend 資格情報を送信 -H “xxx: ” or https://xxx?yyy= API Gatewayから既定の形式で 認証処理のリクエスト 認証処理 API Gatewayへ既定の形式で 認証結果のレスポンス 認証処理失敗: HTTP 401 I/Fが定められている 検証成功: バックエンドへリクエスト 認可処理失敗: HTTP 404 認可処理

Authorizer FunctionsのI/F Copyright © 2022, Oracle and/or its affiliates 8 User Functions API Gateway -H “xxx: ” or https://xxx?yyy= API Gatewayからの入力形式 { “type”: “TOKEN”, “token”: “” } 認証スキームも含められるため、 Functions側でハンドリングする 認証処理に失敗した場合: { “active”: false, “expiresAt”: “”, “context”: {“”: “”,…}, “wwwAuthenticate”: “” } 認証処理に成功した場合: { “active”: true, “principal”: ””, “scope”: [“”], “clientId”: “”, “expiresAt”: “”, “context”: {“”: “”,…} }

* active: true • 認証処理が正常に終了したことを示す * principal: • ユーザ名、アプリケーション名 * scope: [] • コール元が実行を許可されている操作 • 認可処理で使用される clientId: • ホスト名、クライアントIP、etc. * expiresAt: • 認証結果の有効期限(ISO-8601) • 認証結果のキャッシュ期間の決定に使用される context: {: , …} • APIデプロイメントで使用する任意のデータ（key-value形式） • ${request.auth[]}の形式で使用 *: 返却必須項目 例 Oracle FunctionsがAPI Gatewayに返却する結果（正常系） Copyright © 2022, Oracle and/or its affiliates 9 { "active": true, "principal": "https://example.com/users/jdoe", "scope": [ "list:hello", "read:hello", "create:hello", "update:hello", "delete:hello", "someScope" ], "clientId": "host123", "expiresAt": "2019-05-30T10:15:30+01:00", "context": { "email": "[email protected]" } }

* active: false • 認証処理が失敗したことを示す * expiresAt: • 認証結果の有効期限(ISO-8601) • 認証結果のキャッシュ期間の決定に使用される context: {: , …} • APIデプロイメントで使用する任意のデータ（key-value形式） • ${request.auth[]}の形式で使用 * wwwAuthenticate: • 検証が失敗した場合に、クライアントに返却される wwwAuthenticateヘッダの値。リソースへのアクセス権を取得す る方法（認証タイプ等）を返却する。 *: 返却必須項目 例 Oracle FunctionsがAPI Gatewayに返却する結果（異常系） Copyright © 2022, Oracle and/or its affiliates 10 { "active": false, "wwwAuthenticate": "Bearer realm=¥"example.com¥"“ "expiresAt": "2019-05-30T10:15:30+01:00", "context": { "email": "[email protected]" } }

scopeを用いた認可処理 Copyright © 2022, Oracle and/or its affiliates 11 Functions Functions Functions API Gateway list: hello create: hello update: hello delete: hello someScope someScope dummyScope Authorizer Functionsから返却された認証結果 各ルーティングパス毎の許可されるscopeの設定 設定されたscopeの内容を 少なくとも一つ含む事を確認

認可タイプ 概要 任意 設定したスコープが少なくとも一つ含まれている場合、認証済みのエンドユーザーに対してアクセス権 を付与する 匿名 認証済みでないエンドユーザーに対してもアクセス権を付与する（※認証ポリシーで匿名アクセスの 有効化オプションが必要） 認証のみ 認可処理を実行しない（認証済みエンドユーザーであればアクセス権を付与する） 認可ポリシー Copyright © 2022, Oracle and/or its affiliates 12

public AuthorizerResponse handleRequest(AuthorizerRequest authorizerRequest) { // request validation if (!TYPE.equals(authorizerRequest.getType()) || authorizerRequest.getType() == null) { var response = new AuthorizerResponse(); response.setActive(false); response.setWwwAuthenticate("Basic realm=¥"foo¥""); return response; } if ("".equals(authorizerRequest.getToken()) || authorizerRequest.getToken() == null || !authorizerRequest.getToken().startsWith(TOKEN_PREFIX)) { var response = new AuthorizerResponse(); response.setActive(false); response.setWwwAuthenticate("Basic realm=¥"foo¥""); return response; } // token validation var adminCredential = new String(Base64.getUrlEncoder().encode(String.format("%s:%s", ADMIN_USER, ADMIN_PASSWORD) .getBytes(StandardCharsets.UTF_8))); var inputToken = authorizerRequest.getToken().substring(TOKEN_PREFIX.length()); if (!adminCredential.equals(inputToken)) { var response = new AuthorizerResponse(); response.setActive(false); response.setWwwAuthenticate("Basic realm=¥"foo¥""); return response; } var response = createResponse(inputToken); return response; } Authorizer Functionsの実装例 Copyright © 2022, Oracle and/or its affiliates 13 独自の認証ロジックを実装することで、様々な方式 に対応することができる。

参考: 設定の解説 Copyright © 2022, Oracle and/or its affiliates 14 カスタムを選択する 作成済みの認証処理を行う Oracle Functionsを選択する ヘッダー or クエリーパラメーター パラメータ名を指定する 匿名ユーザー（未認証なエンドユーザー）が APIデプロイメント内のパスにアクセス可能かどうかを示す

Copyright © 2022, Oracle and/or its affiliates 15 JWT Validator

JSON Web Token • jot(ジョット) と発音することが RFC 7519 で推奨されている • スペースに制約のある環境を想定したコンパクトなクレームの表現方法 • JSONをURL-safeな形でコンパクトにエンコードしたもの • コンパクトにするという目的で省略形が使われることが多い (e.g. audience → aud) • JOSE(JavaScript Object Signing and Encryption)と呼ばれる仕様群の一つ • JWS (JSON Web Signature) - RFC 7515 • JWE (JSON Web Encryption) - RFC 7516 • JWK (JSON Web Key) - RFC 7517 • JWA (JSON Web Algorithms) - RFC 7518 • JWT (JSON Web Token) - RFC 7519 JSON Web Token Copyright © 2022, Oracle and/or its affiliates 16

JWT Validator Copyright © 2022, Oracle and/or its affiliates 17 Enduser API Gateway Identity Provider Backend JWTを送信 -H “xxx: eyJ…” or https://xxx?yyy=eyJ... 公開鍵の要求* 公開鍵の返却* 検証失敗: HTTP 401 検証成功: バックエンドへリクエスト 認可処理失敗: HTTP 404 JWTの検証処理 JWKs Endpoint 認可処理 - 署名の検証 - Issuerの検証 - Audienceの検証 - 有効期限の検証 - etc. *: 実行時に動的に公開鍵を取得しない方法も可能

署名とPayloadに含まれるクレームの検証が実行される JWT Validator – JWTの検証処理 Copyright © 2022, Oracle and/or its affiliates 18 { "user_tz": "Asia/Tokyo", "sub": "[email protected]", "iss": "https://identity.oraclecloud.com/", "client_id": "tokenGenerator", "sub_type": "user", "client_tenantname": "idcs-oracle", "region_name": "us-phoenix-idcs-1", "user_lang": "en", "exp": 1651052900, "iat": 1651049300, "user_displayname": "Hoge Hoge", "aud": [ "https://example.com/", "https://console:9245" ], "scope": "list:hello create:hello update:hello delete:hello someScope" ... 省略 ... } JWTのPayload例（※一部抜粋） 発行時刻(iat)と有効期限(exp)を 元にJWTの有効期限の確認

検証済みのJWTのPayloadに含まれるクレーム(scope)とAPI Gatewayに設定済みのスコープを元に認可処理を行う JWT Validator – 認可処理 Copyright © 2022, Oracle and/or its affiliates 19 { ... 省略 ... "scope": "list:hello create:hello update:hello delete:hello someScope" ... 省略 ... } JWTのPayload例（※一部抜粋） 少なくとも一つ 含まれることを検証

参考: 設定の解説(1/3) Copyright © 2022, Oracle and/or its affiliates 20 JWTを選択する ヘッダー or クエリーパラメーター パラメータ名を指定する 匿名ユーザー（未認証なエンドユーザー）が APIデプロイメント内のパスにアクセス可能かどうかを示す

参考: 設定の解説(2/3) Copyright © 2022, Oracle and/or its affiliates 21 JWTの発行者(Issuer/iss)を指定する（各IdP固有の値） JWTの発行先(audience/aud)を指定する • リモートJWKS: APIの実行時にIdPから公開されているJWKs Endpointを実行し、公開鍵を取得する • 静的キー: 事前発行済みの公開鍵を設定する

参考: 設定の解説(3/3) Copyright © 2022, Oracle and/or its affiliates 22 IdPとAPI Gatewayの間のシステム・クロックに差分が予想される場合に、指定する 指定した値は、JWTの有効期限の算出に考慮される iss/aud以外で、JWT検証に含めたいクレームが存在する場合にその内容を指定する

Identity Provider iss aud JWKs Endpoint IDCS https://identity.oraclecl oud.com/ 顧客固有 https:///admin/v1/Signing Cert/jwk OKTA https://.com 顧客固有 https://.com/oauth2//v1/keys Auth0 https://.auth0.com/ 顧客固有 https://.auth0.com/.well -known/jwks.json 参考: iss, aud, JWKs Endpointの一例 Copyright © 2022, Oracle and/or its affiliates 23

Copyright © 2022, Oracle and/or its affiliates 24 Thank you

No content