附註：

此教學課程需要存取 Oracle Cloud。若要註冊免費帳戶，請參閱 Oracle Cloud Infrastructure Free Tier 入門。
它使用 Oracle Cloud Infrastructure 證明資料、租用戶及區間的範例值。完成實驗室時，請將這些值取代為您雲端環境特定的值。

使用 OCI IAM 網域所發出的 JWT 權杖存取 ORDS 中受保護的資源

簡介

Oracle Cloud Infrastructure Identity and Access Management (OCI IAM) 使用識別網域來提供識別和存取管理功能，例如 OCI 的認證、單一登入 (SSO) 和識別生命週期管理，以及 Oracle 和非 Oracle 應用程式 (無論是 SaaS、雲端代管還是內部部署)。

Oracle REST Data Services (ORDS) 可橋接 HTTPS 和您的 Oracle Database。ORDS 是一個中間層 Java 應用程式，提供 Database Management REST API、SQL Developer Web、PL/SQL 閘道、Simple Oracle Document Access (SODA) for REST，以及能夠發佈 RESTful Web 服務以與 Oracle Database 中的資料和預存程序互動。

ORDS 版本 23.3 導入 JSON Web 權杖 (JWT) 支援。這些 Bearer 權杖可讓 ORDS 開發人員將認證和授權委派給任何符合 OAuth2 規範的身分識別提供者 (IdP) 以發出 JWT 存取權杖，讓 ORDS 可以驗證以提供 ORDS 保護資源的存取權。

在本教學課程中，我們將示範如何使用 OCI IAM 網域所發出的 JWT 權杖存取 ORDS 中受保護的資源。在本示範中，我們將使用 OCI 中的 Oracle Autonomous Database，隨附預先設定且完全受管理的 ORDS 應用程式。

下圖顯示解決方案架構的高階表示法。

架構圖

目標

使用 OCI IAM 網域所發出的 JWT 權杖存取 ORDS 中受保護的資源。

必要條件

OCI 中的使用者必須具備管理 Oracle Autonomous Databases 和 OCI IAM 網域的必要原則。如需有關所有服務原則參照的詳細資訊，請參閱原則參照。
必須有可用的 Oracle Autonomous Database。如需詳細資訊，請參閱佈建 Autonomous Database 執行處理。
ORDS 接受使用 JWT 的認證和授權之前：
- 必須已經設定符合 OAuth2 規範的 IdP (例如，具備識別網域的 OCI IAM Auth0)，才能為可存取 ORDS 資源的使用者發出 JWT。
- 如果您想在授權原則中使用自訂宣告，必須設定 IdP，才能將自訂宣告新增至發出的 JWT。
若要使用發行版本 IdP 提供的對應公開驗證金鑰來驗證 JWT：
- 簽署演算法必須是 RS256、RS384 或 RS512。
- 公用驗證金鑰至少必須為 2048 位元且不得超過 4096 位元。
- 公用驗證金鑰必須以 JSON Web 金鑰 (JWK) 格式指定，而且可由 ORDS 存取且無須認證。
JWK URI 需求：
- JWK URI 必須可以從 ORDS 存取。
- 金鑰參數必須存在於 JWKS 中，才能驗證 JWT 簽章。
- 依照預設，JWKS 的大小上限為 10,000 個位元組。

注意：由其發出的 OCI IAM 網域和 JWT 權杖符合上述所有需求。

作業 1：設定資料庫綱要的 ORDS、定義 API 端點以及設定存取控制

登入 OCI 主控台，瀏覽至 Oracle Database 並按一下 Autonomous Database 。
按一下佈建的 Autonomous Database 執行處理、資料庫動作，然後按一下 SQL 。
請執行下列查詢，確定您有支援 JWT 的 ORDS 版本 23.3 或更新版本。
```
SELECT * FROM ORDS_METADATA.ORDS_VERSION;
```

執行下列查詢以建立使用者 (ordstest)，並指派必要的權限。

CREATE USER ordstest IDENTIFIED BY "<Password>";
GRANT CONNECT, RESOURCE TO ordstest;
ALTER USER ordstest DEFAULT ROLE CONNECT, RESOURCE;

執行下列查詢，為綱要啟用 ORDS 以允許使用 REST API 功能。

BEGIN
 ORDS_ADMIN.ENABLE_SCHEMA(
     p_enabled => TRUE,
     p_schema => 'ordstest',
     p_url_mapping_type => 'BASE_PATH',
     p_url_mapping_pattern => 'ordstest',
     p_auto_rest_auth=> FALSE
 );
commit;
END;
/

執行下列查詢，在 ordstest 綱要中建立名為 emp 的表格，並插入範例資料。

CREATE TABLE ordstest.emp (
EMPNO NUMBER(4,0),
ENAME VARCHAR2(10 BYTE),
JOB VARCHAR2(9 BYTE),
MGR NUMBER(4,0),
HIREDATE DATE,
SAL NUMBER(7,2),
COMM NUMBER(7,2),
DEPTNO NUMBER(2,0),
CONSTRAINT PK_EMP PRIMARY KEY (EMPNO)
);

Insert into ordstest.EMP (EMPNO,ENAME,JOB,MGR,HIREDATE,SAL,COMM,DEPTNO) values (7369,'SMITH','CLERK',7902,to_date('17-DEC-80','DD-MON-RR'),800,null,20);
Insert into ordstest.EMP (EMPNO,ENAME,JOB,MGR,HIREDATE,SAL,COMM,DEPTNO) values (7499,'ALLEN','SALESMAN',7698,to_date('20-FEB-81','DD-MON-RR'),1600,300,30);
Insert into ordstest.EMP (EMPNO,ENAME,JOB,MGR,HIREDATE,SAL,COMM,DEPTNO) values (7521,'WARD','SALESMAN',7698,to_date('22-FEB-81','DD-MON-RR'),1250,500,30);
Insert into ordstest.EMP (EMPNO,ENAME,JOB,MGR,HIREDATE,SAL,COMM,DEPTNO) values (7566,'JONES','MANAGER',7839,to_date('02-APR-81','DD-MON-RR'),2975,null,20);
Insert into ordstest.EMP (EMPNO,ENAME,JOB,MGR,HIREDATE,SAL,COMM,DEPTNO) values (7654,'MARTIN','SALESMAN',7698,to_date('28-SEP-81','DD-MON-RR'),1250,1400,30);

執行下列查詢以定義將包含 API 端點的 ORDS 模組 (demo)。

BEGIN
  ORDS_ADMIN.DEFINE_MODULE(
     p_schema => 'ordstest',
     p_module_name => 'demo',
     p_base_path => '/demo/',
     p_items_per_page=> 1000,
     p_status => 'PUBLISHED',
     p_comments=> ''
 );
COMMIT;
END;
/

執行下列查詢以定義對應至特定 REST 資源的範本 emp。

BEGIN
 ORDS_ADMIN.DEFINE_TEMPLATE(
     p_schema => 'ordstest',
     p_module_name => 'demo',
     p_pattern => 'emp',
     p_priority => 0,
     p_etag_type => 'HASH',
     p_comments => ''
 );
COMMIT;
END;
/

執行下列查詢以建立 emp 的 GET 要求處理程式，該處理程式會執行從表格 emp 傳回資料的簡單 SQL 查詢。
```
BEGIN
 ORDS_ADMIN.DEFINE_HANDLER(
     p_schema => 'ordstest',
     p_module_name => 'demo',
     p_pattern => 'emp',
     p_method => 'GET',
     p_source_type => ords.source_type_collection_feed,
     p_source => 'select * from emp',
     p_items_per_page => 25,
     p_comments => ''
 );
COMMIT;
END;
/
```
將 /ordstest/demo/emp 附加至 Oracle 自治式資料庫的 ORDS 公用存取 URL (位於工具組態底下)，即可檢視 emp 表格而不進行任何認證。本自學課程使用 Postman 。

執行下列查詢以定義保護 demo 模組的權限 (privilegetest)。

DECLARE
L_PRIV_ROLES owa.vc_arr;
L_PRIV_PATTERNS owa.vc_arr;
L_PRIV_MODULES owa.vc_arr;
BEGIN
L_PRIV_MODULES( 1 ) := 'demo';
ORDS_ADMIN.DEFINE_PRIVILEGE(
  P_Schema=> 'ordstest',
  P_PRIVILEGE_NAME => 'privilegetest',
  P_ROLES => L_PRIV_ROLES,
  P_PATTERNS =>  L_PRIV_PATTERNS,
  P_MODULES => L_PRIV_MODULES,
  P_LABEL => 'privilegetest',
  P_DESCRIPTION => 'Demonstrate controlling access with priviliges',
  P_COMMENTS=> ''
  );
COMMIT;
END;
/

由於 demo 模組受到 privilegetest 權限的保護，因此未經適當授權便無法存取。若要啟用存取，您必須為 ordstest 綱要建立 JWT 設定檔。這可讓 ORDS 驗證 JWT Bearer 權杖並授予受保護資源 (例如示範模組) 的存取權。

作業 2：建立 ORDS JWT 設定檔

您可以使用 OAUTH.CREATE_JWT_PROFILE 程序，在啟用 REST 的綱要內建立 JWT 設定檔。不過，每個綱要只能定義一個 JWT 設定檔。若要更新現有的 JWT 設定檔，必須先將其刪除，再建立新的 JWT 設定檔。

BEGIN
  OAUTH_ADMIN.DELETE_JWT_PROFILE(p_schema=>'ordstest');
  OAUTH_ADMIN.CREATE_JWT_PROFILE(
  p_schema => 'ordstest',
  p_issuer => 'https://idcs-123456789abcdefghijklmnopqrstuvw.identity.oraclecloud.com',
  p_audience => 'ords/ordstest/',
  p_jwk_url =>'https://idcs-123456789abcdefghijklmnopqrstuvw.identity.oraclecloud.com:443/admin/v1/SigningCert/jwk'
 );
COMMIT;
END;
/

此 JWT 設定檔指定發照者、受眾及 JWK URL。

p_issuer 必須是非空值的值，且必須符合 JWT Bearer 權杖中的 iss 宣告。
p_audience 必須是非空值的值，且必須與 JWT Bearer 權杖中的 aud 宣告相符。
p_jwk_url 必須是以 https:// 為開頭的非空值，並且識別授權伺服器以 JSON Web 金鑰 (JWK) 格式提供的公開驗證金鑰。

若要取得 OCI IAM 網域的 Issuer 和 JWK URI，請傳送 GET 要求至 OCI IAM 網域 URL (附加 /.well-known/openid-configuration)，如下圖所示。

IAM 網域描述資料

若要驗證 JWT 設定檔組態，請以 ordstest 使用者身分登入並執行下列 SQL 查詢。

SELECT * FROM ORDS_METADATA.USER_ORDS_JWT_PROFILE;

此查詢會擷取 JWT 設定檔詳細資訊，確保已正確設定發照者、受眾及 JWK URL。

ORDS JWT 設定檔

設定 JWT 設定檔之後，一般使用者可以提供 OAuth 2.0 相容 IdP 所發出的 JWT 權杖 (例如 JWT 設定檔中指定的 OCI IAM 網域)，以存取 ORDS 受保護的資源。順利驗證 JWT Bearer 權杖時，ORDS 會接受下列項目：

JWT 主體宣告為提出要求的已認證使用者。
JWT 範圍會宣告為啟用 REST 的綱要 ORDS 權限，使用者已代表其使用權限同意應用程式。

作業 3：啟用無認證之 OCI IAM 網域簽署憑證的 ORDS 存取

移至 OCI 主控台，瀏覽至識別與安全、識別，然後按一下網域。
按一下您要處理之識別網域的名稱。您可能必須變更區間才能找到您要的網域。按一下設定值和網域設定值。
在存取簽署憑證區段中，選取設定從屬端存取，然後按一下儲存變更。這可讓 ORDS 存取識別網域的簽署認證，不需要認證。

作業 4：設定資源伺服器和從屬端、JWT 範圍以及 ORDS 權限

您必須設定 IdP，才能發出符合必要 ORDS 權限之範圍的 JWT。如果 ORDS 中的資源受到權限保護，則必須將該權限名稱定義為範圍。此範圍允許應用程式代表使用者要求存取權。發出的 JWT 必須接著包含範圍作為求償。由於我們將使用 OCI IAM OAuth2 服務強制執行授權，因此需要設定部分資源伺服器和從屬端。

作業 4.1：建立具有所需對象與範圍的資源伺服器類型機密應用程式

移至您使用的識別網域，然後按一下整合的應用程式。
依序選取新增應用程式、機密應用程式，然後按一下啟動工作流程。
輸入應用程式的名稱 (例如，ORDS-SERVER)，然後按一下下一步。
在資源伺服器組態段落中，選取立即將此應用程式設定為資源伺服器。
使用符合 JWT 設定檔的主要對象和符合 ORDS 權限的範圍來設定資源伺服器。
按下一步並完成。
在應用程式總覽頁面中，選取啟用並確認要啟用應用程式。機密應用程式已啟用。

作業 4.2：建立指定所需範圍的從屬端類型機密應用程式

移至您使用的識別網域，然後按一下整合的應用程式。
依序選取新增應用程式、機密應用程式，然後按一下啟動工作流程。
輸入應用程式的名稱 (例如，ORDS-CLIENT)，然後按一下下一步。
在用戶端組態區段中，選取立即將此應用程式設定為用戶端。
在授權區段中，選取用戶端憑證。

注意：在此教學課程中，我們將使用從屬端證明資料作為授權類型。您可以根據您的需求選取不同的授權類型，例如使用者導向從屬端的授權代碼流程。
在用戶端類型中，選取機密。
在權杖發放原則區段中，選取特定作為授權的資源。
按一下新增資源，然後在資源下，選取新增範圍。為在 Task 4.1 中建立的資源伺服器選取所需的範圍。例如，privilegetest。
按下一步並完成。
在應用程式概觀頁面中，選取啟用並確認您要啟用應用程式。機密應用程式已啟用。
複製此從屬端應用程式的從屬端 ID 和從屬端密碼。驗證需要這些憑證。