WMS ID 4602

build-ords-apis-in-adb/3-secure-endpoints/secure-endpoints.md

@@ -14,67 +14,71 @@ Estimated Lab Time: 10 minutes
 
 ### Prerequisites
 
-- The following lab requires an [Oracle Cloud account](https://www.oracle.com/cloud/free/). You may use your own cloud account, a cloud account that you obtained through a trial, or a training account whose details were given to you by an Oracle instructor.
+<if type="tenancy">
+- The following lab requires an [Oracle Cloud account](https://www.oracle.com/cloud/free/). You may use your own cloud account, a cloud account obtained through a trial, or a training account whose details were given to you by an Oracle instructor.
+</if>
 - This lab uses the command line application cURL for testing APIs; some familiarity is suggested.
 - This lab assumes you have completed all previous Labs. 
 
-## Task 1: Create a Role for an OAuth2.0 client
+## Task 1: Create a Role
 
 1. From the REST Workshop, select **Roles** from the **Security** dropdown menu.
 
-    ![Roles from the security menu](./images-new/1-roles-from-security-menu.png " ")
+    ![Roles from the security menu](./images/1-roles-from-security-menu.png " ")
 
 2. Next, click the **+ Create Role** button.
 
-    ![click create role button](./images-new/2-create-role-button.png " ")
+    ![click create role button](./images/2-create-role-button.png " ")
 
 3. In the Role Definition modal, enter in a **Role Name**, such as: `my.test.role`, then click **Create**.
 
-    ![The role definition modal](./images-new/3-role-definition-modal.png " ")
+    ![The role definition modal](./images/3-role-definition-modal.png " ")
 
-## Task 2: Create a Privilege for an OAuth2.0 client
+## Task 2: Create a Privilege
 
-1. Next, you'll create a Privilege for the OAuth2.0 client. Select **Privileges** from the **Security** dropdown menu. 
+1. Next, you'll create a Privilege. Select **Privileges** from the **Security** dropdown menu. 
 
-    ![Selecting privileges from security menu](./images-new/4-select-privileges-option.png " ")
+    ![Selecting privileges from security menu](./images/4-select-privileges-option.png " ")
 
 2. Click the **+ Create Privilege** button, and enter in values for this privilege. 
 
-   ![Create privilege button](./images-new/5-create-privilege-button.png " ")
+    ![Create privilege button](./images/5-create-privilege-button.png " ")
 
-   To better follow along, choose values similar to the examples: 
+    To better follow along, choose values similar to the examples: 
 
     **Privilege Definition**
     - **Label:** `my.test.priv`
     - **Name:** `my.test.priv`
     - **Description:** `my.test.priv` (You can alter this as needed)
     - **Comments:** optional 
 
-     ![create-priv-priv-definition](./images-new/6-create-priv-priv-definition.png " ")
+     ![create-priv-priv-definition](./images/6-create-priv-priv-definition.png " ")
 
     **Roles**
-    - **Roles:** `my.test.role` (or your unique role, if it differs)
+    - **Roles:** `my.test.role` (the role you created in Task 1)
 
-       ![create-priv-roles](./images-new/7-create-priv-roles.png " ")
+       ![create-priv-roles](./images/7-create-priv-roles.png " ")
 
     **Protected Modules**
     - **Selected Modules**: `records.module`
 
-      ![create-priv-selected-modules](./images-new/8-create-priv-protected-modules.png " ")
+      ![create-priv-selected-modules](./images/8-create-priv-protected-modules.png " ")
 
     > **TIP:** Move a Module into the Selected Modules column by dragging, or using the arrow buttons.
 
-3. Once complete, click the **Create** button.
+3. Once complete, click the **Create** button. 
+
+4. Your `records.module` is now protected by the `my.test.priv`. The `my.test.priv` *enumerates* any roles you've attached to it.
 
 ## Task 3: Create an ORDS OAuth Client
 
 1. Select **OAuth Clients** from the **Security Tab**.
 
-    ![selecting OAuth Clients](./images-new/9-oauth-clients-menu.png " ")
+    ![selecting OAuth Clients](./images/9-oauth-clients-menu.png " ")
 
 2. Then, click the **+ Create OAuth Client** button.
 
-    ![Click the Create OAuth Client button](./images-new/10-create-oauth-client-button.png " ")
+    ![Click the Create OAuth Client button](./images/10-create-oauth-client-button.png " ")
 
 3. In the Create OAuth Client slider, enter in the following values and click the **Create** button when complete:
 
@@ -85,56 +89,66 @@ Estimated Lab Time: 10 minutes
     - **Support email:** your choice (mandatory field)
     - **Support URI:** https://www.my-company.com/support (can be fictitious)
 
-     ![Description Field](./images-new/11-create-oauth-client-definition.png " ")
+     ![Description Field](./images/11-create-oauth-client-definition.png " ")
 
-    **Roles**
-    - **Roles:** `my.test.role` (or your unique role, if it differs)
+4. Previously you created a Privilege, which includes (enumerates) a Role. Here, you can optionally assign the OAuth Client either the `my.test.role` role, the `my.test.priv` privilege, or both (although in this case, a bit redundant).
 
-       ![choose-roles-tB](./images-new/12-create-oauth-client-roles.png " ")
+      Selecting *only* the Role is acceptable, since the Privilege you created includes this Role. Since your `records.module` is protected by the same Privilege, this is a valid approach. 
 
-    **Privileges**
-    - **Roles:** `my.test.role` (or your unique role, if it differs)
+      **Roles**
+      - **Roles:** `my.test.role` (or your unique role, if it differs)
 
-       ![choose-ouath-privs](./images-new/13-create-oauth-client-privs.png " ")
+         ![choose-roles-tB](./images/12-create-oauth-client-roles.png " ")
 
-## Task 4: Testing the OAuth2.0 client
+    Alternatively, you can simply assign the Privilege directly. And since that Privilege enumerates the Role, this is valid as well. 
+
+      **Privileges**
+      - **Roles:** `my.test.role` (or your unique role, if it differs)
 
-1. After clicking **Create**, a Client Secret modal will appear. Copy the Secrect Client value to your clipboard or a text editor. 
+         ![choose-ouath-privs](./images/13-create-oauth-client-privs.png " ")
 
-     > **NOTE:** If you click OK prior to copying, you can also Rotate in a new Client Secret value.
+5. Choose an approach, and click the **Create** button when complete. 
+
+## Task 4: Testing the OAuth2.0 client
 
-     ![Copy my client secret](./images-new/14-my-oauth-client-secret.png " ")
+1. After clicking **Create**, a Client Secret modal will appear. Copy the Secret Client value to your clipboard or a text editor. 
 
-     ![Rotate in new secret](./images-new/15-mistake-rotate-secret.png " ")
+    ![Copy my client secret](./images/14-my-oauth-client-secret.png " ")
 
-2. You will also next need to copy your Client ID.
+    > **NOTE:** If you click OK prior to copying, you can also Rotate in a new Client Secret value.
 
-    ![Client ID value](./images-new/16-copy-client-id-value.png " ")
+    > ![Rotate in new secret](./images/15-mistake-rotate-secret.png " ")
 
-3. You will first request an Access token from the ORDS OAuth2.0 `/token` endpoint. The Token endpoint is located at the following URL, where `server.com` is the location of your database server (this example assumes your schema is also `ords101`):
+2. You will first request an Access token from the ORDS OAuth2.0 `/token` endpoint. The Token endpoint is located at the following URL, where `server.com` is the location of your database server:
 
-    ```http
-    <copy>https://[MY ADB's OCI]-[My ADB Name].adb.[My-Region].oraclecloudapps.com/ords/ords101/oauth/token</copy>
+    ```html
+    <copy>https://[MY ADB's OCI]-[My ADB Name].adb.[My-Region].oraclecloudapps.com/ords/[Schema name]/oauth/token</copy>
     ```
 
-    Your cURL command for retrieving an Access Token should resemble the following (where the `--user` value is your `Client_ID`:`Client_Secret`):
+3. The simpliest way to retrive this endpoint, along with a fully-formed curl command, is by clicking the OAuth client's kebab menu, then selecting the Get Bearer Token menu option. Then, copy the command.
 
-    ```shell
+    ![select-get-bearer-token](./images/16-select-get-bearer-token.png " ")
+
+    ![copy-oauth-token-command](./images/16-1-copy-oauth-token-command.png " ")
+
+    > Your cURL command for retrieving an Access Token should resemble the following (where the `--user` value is your `Client_ID`:`Client_Secret`):
+
+    > ```shell
     <copy>curl \
     --user AbcDef3456XYz..:a45AbcdeF8675309abcd.. \
     --data 'grant_type=client_credentials' \
     'https://abcdefgh12345-ords101db.adb.us-ashburn-1.oraclecloudapps.com/ords/ords101/oauth/token'</copy>
     ```
 
-    ![Obtaining-the-bearer-token-part-one](./images-new/17-obtaining-the-bearer-token-part-one.png " ")
+    > ![Obtaining-the-bearer-token-part-one](./images/17-obtaining-the-bearer-token-part-one.png " ")
 
 4. Execute your cURL command; you will recieve a valid Access Token. In this example, you can use the `GET` endpoint that you created in **Lab 2, Task 3: Building an ORDS GET API** as your target endpoint.
 
-    ![Obtaining-the-bearer-token-part-two](./images-new/18-obtaining-the-bearer-token-part-two.png " ")
+    ![Obtaining-the-bearer-token-part-two](./images/18-obtaining-the-bearer-token-part-two.png " ")
 
 5. Before proceeding, attempt a GET request on your GET Handler, it will fail as you have not provided a valid Access Token (Unauthorized).
 
-    ![An unauthorized get request](./images-new/19-unauthorized-request.png " ")
+    ![An unauthorized get request](./images/19-unauthorized-request.png " ")
 
 6. Finally, with a valid Access Token, perform a GET request on your target endpoint, using the following cURL command as an example: 
 
@@ -144,7 +158,7 @@ Estimated Lab Time: 10 minutes
     'https://abcdefgh12345-ords101db.adb.us-ashburn-1.oraclecloudapps.com/ords/ords101/v1/dept_active/10/true'</copy>
     ```
 
-    ![An authorized get request](./images-new/20-authorized-request.png " ")
+    ![An authorized get request](./images/20-authorized-request.png " ")
 
 7. What you should see is the successful response from your `/ords101/v1/dept_active/` endpoint. Congratulations, you've just completed the ORDS 101 Workshop!
 
@@ -161,4 +175,4 @@ You may now [proceed to the next lab](#next).
 
 ### Last Updated By/Date
 
-- Chris Hoina, September 2025
+- Chris Hoina, September 2026

build-ords-apis-in-adb/4-workshop-scripts/combined_setup.sql

@@ -0,0 +1,168 @@
+-- ==========================================
+-- CREATE DEPARTMENT TABLE
+-- Source: create_department_table.sql
+-- ==========================================
+CREATE TABLE "DEPARTMENT" 
+   (	"DEPT_ID" NUMBER GENERATED BY DEFAULT AS IDENTITY MINVALUE 1 MAXVALUE 9999999999999999999999999999 INCREMENT BY 1 START WITH 1 CACHE 20 NOORDER  NOCYCLE  NOKEEP  NOSCALE , 
+	"DEPT_CODE" VARCHAR2(5 BYTE) COLLATE "USING_NLS_COMP", 
+	"ESTABLISHED" DATE, 
+	"DETAILS" JSON
+   )  DEFAULT COLLATION "USING_NLS_COMP" ;
+
+CREATE UNIQUE INDEX "DEPT_CODE_UK" ON "DEPARTMENT" ("DEPT_CODE") 
+  ;
+
+CREATE UNIQUE INDEX "DEPT_ID_PK" ON "DEPARTMENT" ("DEPT_ID") 
+  ;
+
+CREATE UNIQUE INDEX "DEPARTMENT_DEPT_CODE_UQ" ON "DEPARTMENT" (UPPER("DEPT_CODE")) 
+  ;
+
+ALTER TABLE "DEPARTMENT" MODIFY ("DEPT_ID" NOT NULL ENABLE);
+
+ALTER TABLE "DEPARTMENT" MODIFY ("DEPT_CODE" CONSTRAINT "DEPT_CODE_NN" NOT NULL ENABLE);
+
+ALTER TABLE "DEPARTMENT" ADD CONSTRAINT "DEPT_ID_PK" PRIMARY KEY ("DEPT_ID")
+  USING INDEX  ENABLE;
+
+
+-- ==========================================
+-- CREATE EMPLOYEE TABLE
+-- Source: create_employee_table.sql
+-- ==========================================
+CREATE TABLE "EMPLOYEE" 
+   (	"EMP_ID" NUMBER GENERATED BY DEFAULT AS IDENTITY MINVALUE 1 MAXVALUE 9999999999999999999999999999 INCREMENT BY 1 START WITH 1 CACHE 20 NOORDER  NOCYCLE  NOKEEP  NOSCALE , 
+	"EMP_NAME" VARCHAR2(100 BYTE) COLLATE "USING_NLS_COMP", 
+	"DEPT_ID" NUMBER, 
+	"COMMENTS" CLOB COLLATE "USING_NLS_COMP"
+   )  DEFAULT COLLATION "USING_NLS_COMP" ;
+
+CREATE UNIQUE INDEX "EMP_ID_PK" ON "EMPLOYEE" ("EMP_ID") 
+  ;
+
+CREATE INDEX "EMP_DEPARTMENT_IX" ON "EMPLOYEE" ("DEPT_ID") 
+  ;
+
+ALTER TABLE "EMPLOYEE" MODIFY ("EMP_ID" NOT NULL ENABLE);
+
+ALTER TABLE "EMPLOYEE" MODIFY ("EMP_NAME" CONSTRAINT "EMP_NAME_NN" NOT NULL ENABLE);
+
+ALTER TABLE "EMPLOYEE" MODIFY ("DEPT_ID" CONSTRAINT "EMP_DEPT_ID_NN" NOT NULL ENABLE);
+
+ALTER TABLE "EMPLOYEE" ADD CONSTRAINT "EMP_ID_PK" PRIMARY KEY ("EMP_ID")
+  USING INDEX  ENABLE;
+
+ALTER TABLE "EMPLOYEE" ADD CONSTRAINT "FK_EMPLOYEE_DEPT" FOREIGN KEY ("DEPT_ID")
+	  REFERENCES "DEPARTMENT" ("DEPT_ID") ENABLE;
+
+
+-- ==========================================
+-- CREATE PROJECT TABLE
+-- Source: create_project_table.sql
+-- ==========================================
+CREATE TABLE "PROJECT" 
+   (	"PROJ_ID" NUMBER GENERATED BY DEFAULT AS IDENTITY MINVALUE 1 MAXVALUE 9999999999999999999999999999 INCREMENT BY 1 START WITH 1 CACHE 20 NOORDER  NOCYCLE  NOKEEP  NOSCALE , 
+	"PROJ_NAME" VARCHAR2(100 BYTE) COLLATE "USING_NLS_COMP", 
+	"DEPT_ID" NUMBER, 
+	"IS_ACTIVE" BOOLEAN
+   )  DEFAULT COLLATION "USING_NLS_COMP" ;
+
+CREATE UNIQUE INDEX "PROJ_ID_PK" ON "PROJECT" ("PROJ_ID") 
+  ;
+
+CREATE INDEX "PROJ_DEPARTMENT_IX" ON "PROJECT" ("DEPT_ID") 
+  ;
+
+ALTER TABLE "PROJECT" MODIFY ("PROJ_ID" NOT NULL ENABLE);
+
+ALTER TABLE "PROJECT" MODIFY ("PROJ_NAME" CONSTRAINT "PROJ_NAME_NN" NOT NULL ENABLE);
+
+ALTER TABLE "PROJECT" MODIFY ("DEPT_ID" CONSTRAINT "PROJ_DEPT_ID_NN" NOT NULL ENABLE);
+
+ALTER TABLE "PROJECT" ADD CONSTRAINT "PROJ_ID_PK" PRIMARY KEY ("PROJ_ID")
+  USING INDEX  ENABLE;
+
+ALTER TABLE "PROJECT" ADD CONSTRAINT "FK_PROJECT_DEPT" FOREIGN KEY ("DEPT_ID")
+	  REFERENCES "DEPARTMENT" ("DEPT_ID") ENABLE;
+
+-- ==========================================
+-- INSERT DATA
+-- Source: insert_data.sql
+-- ==========================================
+INSERT INTO DEPARTMENT (DEPT_CODE, ESTABLISHED, DETAILS) VALUES
+    ('HR001', DATE '2001-04-13', JSON_OBJECT('location' VALUE 'Bldg 1', 'members' VALUE 25)),
+    ('FN002', DATE '2002-06-20', JSON_OBJECT('location' VALUE 'Bldg 2', 'members' VALUE 20)),
+    ('EN003', DATE '2000-11-01', JSON_OBJECT('location' VALUE 'Bldg 3', 'members' VALUE 40)),
+    ('SA004', DATE '2005-01-15', JSON_OBJECT('location' VALUE 'Bldg 4', 'members' VALUE 18)),
+    ('MK005', DATE '2003-12-07', JSON_OBJECT('location' VALUE 'Bldg 5', 'members' VALUE 15)),
+    ('LG006', DATE '2010-03-31', JSON_OBJECT('location' VALUE 'Bldg 6', 'members' VALUE 5)),
+    ('IT007', DATE '2001-09-23', JSON_OBJECT('location' VALUE 'Bldg 7', 'members' VALUE 30)),
+    ('SP008', DATE '2015-05-05', JSON_OBJECT('location' VALUE 'Bldg 8', 'members' VALUE 12)),
+    ('LG009', DATE '2012-07-14', JSON_OBJECT('location' VALUE 'Bldg 9', 'members' VALUE 10)),
+    ('OP010', DATE '2008-08-01', JSON_OBJECT('location' VALUE 'Bldg 10', 'members' VALUE 22));
+    COMMIT;
+
+INSERT INTO PROJECT (PROJ_NAME, DEPT_ID, IS_ACTIVE) VALUES
+    ('Onboarding', 1, TRUE),
+    ('Audit2024', 2, FALSE),
+    ('NewApp', 3, TRUE),
+    ('SalesCampaign', 4, TRUE),
+    ('SocialMediaPush', 5, FALSE),
+    ('Compliance', 6, TRUE),
+    ('UpgradeInfra', 7, TRUE),
+    ('HelpdeskRevamp', 8, TRUE),
+    ('FleetUpdate', 9, TRUE),
+    ('ProcessReorg', 10, FALSE);
+    COMMIT;
+
+INSERT INTO EMPLOYEE (EMP_NAME, DEPT_ID, COMMENTS) VALUES
+    ('Alice', 1,  'Strong analyst, quick learner.'),
+    ('Bob', 2,  'CPA certification in progress.'),
+    ('Carol', 3,  'Dev team lead for NewApp project.'),
+    ('David', 4,  'Consistent sales over target.'),
+    ('Eve', 5,  'Leads digital campaigns.'),
+    ('Frank', 6,  'Subject matter expert in compliance.'),
+    ('Grace', 7,  'Skilled in infrastructure upgrades.'),
+    ('Heidi', 8,  'Customer support supervisor.'),
+    ('Ivan', 9,  'Fleet manager - long tenure.'),
+    ('Judy', 10,  'Operations management veteran.');
+    COMMIT;
+
+
+-- ==========================================
+-- CREATE PROCEDURE
+-- Source: create_procedure.sql
+-- ==========================================
+CREATE OR REPLACE EDITIONABLE PROCEDURE "PR_ADD_AND_ASSIGN_EMPLOYEE" (
+      p_emp_name  IN VARCHAR2,
+      p_dept_code IN VARCHAR2,
+      p_comments  IN CLOB
+  ) AS
+      l_dept_id department.dept_id%TYPE;
+  BEGIN
+      SELECT dept_id
+        INTO l_dept_id
+        FROM department
+       WHERE UPPER(dept_code) = UPPER(p_dept_code);
+
+      INSERT INTO employee (
+          emp_name,
+          dept_id,
+          comments
+      )
+      VALUES (
+          p_emp_name,
+          l_dept_id,
+          p_comments
+      );
+
+  EXCEPTION
+      WHEN NO_DATA_FOUND THEN
+          raise_application_error(
+              -20001,
+              'Department code not found. Valid values: ' ||
+              'EN003, FN002, HR001, IT007, LG006, LG009, ' ||
+              'MK005, OP010, SA004, SP008'
+          );
+  END;
+/

build-ords-apis-in-adb/4-workshop-scripts/create_department_table.sql

@@ -0,0 +1,23 @@
+CREATE TABLE "DEMO_USER"."DEPARTMENT" 
+   (	"DEPT_ID" NUMBER GENERATED BY DEFAULT AS IDENTITY MINVALUE 1 MAXVALUE 9999999999999999999999999999 INCREMENT BY 1 START WITH 1 CACHE 20 NOORDER  NOCYCLE  NOKEEP  NOSCALE , 
+	"DEPT_CODE" VARCHAR2(5 BYTE) COLLATE "USING_NLS_COMP", 
+	"ESTABLISHED" DATE, 
+	"DETAILS" JSON
+   )  DEFAULT COLLATION "USING_NLS_COMP" ;
+
+CREATE UNIQUE INDEX "DEMO_USER"."DEPT_CODE_UK" ON "DEMO_USER"."DEPARTMENT" ("DEPT_CODE") 
+  ;
+
+CREATE UNIQUE INDEX "DEMO_USER"."DEPT_ID_PK" ON "DEMO_USER"."DEPARTMENT" ("DEPT_ID") 
+  ;
+
+CREATE UNIQUE INDEX "DEMO_USER"."DEPARTMENT_DEPT_CODE_UQ" ON "DEMO_USER"."DEPARTMENT" (UPPER("DEPT_CODE")) 
+  ;
+
+ALTER TABLE "DEMO_USER"."DEPARTMENT" MODIFY ("DEPT_ID" NOT NULL ENABLE);
+
+ALTER TABLE "DEMO_USER"."DEPARTMENT" MODIFY ("DEPT_CODE" CONSTRAINT "DEPT_CODE_NN" NOT NULL ENABLE);
+
+ALTER TABLE "DEMO_USER"."DEPARTMENT" ADD CONSTRAINT "DEPT_ID_PK" PRIMARY KEY ("DEPT_ID")
+  USING INDEX  ENABLE;
+