Updates after run 7 (#13)

Adding various minor updates after the inagural ws on codespaces. * Update contributing, signed commits * Update agenda, add info on 10 min breaks * Upd readme admin * http secure channel * Add extra step in ex-1 for shell and secret validation * Clarify ex-04 loc purpose * Recommend default setting for app in ex-06 * Clarify pre-requisites * Add info using the material after the course * Mark optional sections * Set form_post=query, update port fwd info for GH CS --------- Co-authored-by: Stein A Sivertsen <[email protected]>
equinor · Jan 22, 2024 · 9d1950b · 9d1950b
1 parent 65ff204
commit 9d1950b
Show file tree

Hide file tree

Showing 30 changed files with 107 additions and 77 deletions.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -9,7 +9,7 @@ To get started contributing, you should engage using a [fork and pull request fl
 1. Fork the repository on GitHub.
 2. Clone your forked repository to your local machine.
 3. Create a new branch for your changes.
-4. Make your changes and commit them to your branch.
+4. Make your changes and commit them to your branch (_use signed commits_)
 5. Push your changes to your forked repository on GitHub.
 6. Open a pull request to merge your changes into the main repository.
 

diff --git a/Support/workshop_preparations.md b/Support/workshop_preparations.md
@@ -1,18 +1,20 @@
 # Workshop Preparations &  Pre-Requisites
 
-Prior to joining the workshop the preconditions below should be met. This means that roles need to be active and the software on your local development environment should be tested and verified working.
-
-## We assume that participant:
-
-- You need a laptop with access to the internet
-- You need an updated and modern browser (like Firefox, Chrome, Edge)
-- *Some basic knowledge of the Linux command line and bash are always useful*
-- *The ability to read code in Javascript, Python and .Net will not hurt*
+Prior to joining the workshop the preconditions below must be met. This means that roles needs to be active and the software on your local development environment should be tested and verified working.
 
 ## Important pre-requisites
 
+
 - ⚡️ You need the [Application Developer with normal key (AAD) (MICROSOFT ENTRA ID)
 ](https://docs.omnia.equinor.com/governance/iam/App-General-Info/) role (Apply using Access@IT)
 - ⚡️ You need access to the [Equinor](https://github.com/equinor) organization on [github.com](https://github.com)</br>Verify access by opening the SSO end-point [https://github.com/orgs/equinor/sso](https://github.com/orgs/equinor/sso)
+- A computer with access to the internet
+- An updated and modern browser (like Firefox, Chrome, Edge)
+
+
+## Beneficials ....
 
+- Some basic knowledge of the Linux command line and bash are always useful
+- The ability to read code in Javascript, Python and .Net will not hurt
+- Teams have reported that sitting in the same physical room and joining the workshop together was very helpful and fun.
 
diff --git a/admin/readme.md b/admin/readme.md
@@ -9,7 +9,7 @@ Tasks to do before/after workshop. Current set-up is assuming a virtual workshop
 * 3-5 weeks prior
   * Coordinate with instructors/assistants
   * Reserve slots in calendar
-  * If needed, reserve physical meeting rooms
+  * (If needed, reserve physical meeting rooms)
   * ⚡️ Create a sign-up document, open the sign-up document for **write** for everyone with and Eqn Account 
   * Add reminders in instructors calendars on relevant check-points (2 week, 1 week, 1 week after etc...)
 * 2-3 weeks prior
@@ -28,17 +28,18 @@ Tasks to do before/after workshop. Current set-up is assuming a virtual workshop
   * Update the registration sheet sign-up permission to read-only for none course admins.
 * Execute WS
   * Collect feedback as part of last day
-* 1 week after
+  * 10 minutes breaks is a _must_ for the intense virtual workshop.
+* Within 1 week after
   * Evaluate, update, repeat
   * ⚡️ Remove permission from sign-up document. Should only be available to the AppSec team after the WS for statistics
   * Review and summarize info gathered in workshop retrospective
   * Do a workshop retrospective amongst instructors
   * Decide on changes, create issues/tasks on board for updates
   * Delete groups output of exercises from course Slack channel?
-* 2 weeks after
-  * ⚡️ Run scripts to identify EQ AAD Objects and Course Repos
+* Within 2 weeks after
+  * ⚡️ Run scripts to identify EQ AAD Objects 
   * Send reminder about cleaning up
-  * ⚡️ Remind about #appsec
+  * ⚡️ Remind about joining #appsec
 
 ### Invitation proposal ⚡️
 

diff --git a/docs/content/ex-10.md b/docs/content/ex-10.md
@@ -10,11 +10,11 @@ ADD Applications, Token Validation
 
 Open the file ex-10/readme.md for the exercise. ([official repo](https://github.com/equinor/appsec-fundamentals-authn-authz-cs/blob/main/ex-10/readme.md))
 
-👷‍♀️👷‍♂️👇
+(🥸)👷‍♀️👷‍♂️👇
 
 ---
 
-## Group Work
+## Group Work (🥸)
 
 <div style="font-size: 0.84em">
 

diff --git a/docs/content/ex-2.md b/docs/content/ex-2.md
@@ -8,9 +8,9 @@
 
 Open the file `ex-02/readme.md` for the exercise. ([official repo](https://github.com/equinor/appsec-fundamentals-authn-authz-cs/blob/main/ex-02/readme.md))
 
-👷‍♀️👷‍♂️👇
+(🥸)👷‍♀️👷‍♂️👇
 ---
-## Group Work
+## Group Work (🥸)
 
 * We split into a few small groups
 * We time box discussion to 10 minutes

diff --git a/docs/content/ex-8.md b/docs/content/ex-8.md
@@ -1,4 +1,4 @@
-## Exercise 8
+## Exercise 8 (🥸)
 
 ## The Implicit grant
 

diff --git a/docs/content/intro.md b/docs/content/intro.md
@@ -13,7 +13,7 @@ workshop (the CS version)
 
 * Give an introduction to the basics of modern web/api A&A
 * Explore RFC (specs) and Equinor Azure Implementation (⚡️)
-* Explore code & test automation for selected A&A scenarios
+* Explore code & tests for selected A&A scenarios
 * Insights into threats and security best current practices (BCP)
 
 Throughout the workshop we will discuss security issues, good practices and share experiences between the participants. This last part may be the most important one.
@@ -39,9 +39,13 @@ Throughout the workshop we will discuss security issues, good practices and shar
 * The basics of Authentication and Authorization (part 2)
 * Exploring Scope, Frameworks and Sessions
 * Exploring **Common** authorization scenarios in Equinor
-* Exploring Refresh tokens, Implicit grant and PKCE for Native, Mobile, SPA
+* Exploring Refresh tokens, Implicit grant (🥸) and PKCE for Native, Mobile, SPA
 * Exploring Protecting Web API's and API chaining
 
+Some exercises, and parts of exercises, are marked as optional (🥸). We will include these parts if time permits. The same goes for group work.
+
+<hr>
+The workshop's pace can be perceived as quite high. It will be beneficial for your learning to spend some time with the material and the exercises at your own pace after the course.
 </div>
 
 ---
@@ -53,8 +57,8 @@ Throughout the workshop we will discuss security issues, good practices and shar
 * Course channel on Slack [#appsec-fundamentals-authn-authz](https://equinor.slack.com/archives/C051G3JV7NE)
 * Typical schedule is
   * 09:00 - 15:45
-  * Break for lunch sometime around 11:00, approx 30 minutes.
-  * 5-10 minutes break every hour - don't be afraid to do gentle reminders on breaks :)
+  * Break for lunch sometime around 11:30, approx 30 minutes.
+  * 10 minutes break every hour </br>- don't be afraid to give gentle reminders on breaks 😊
 * Keeping the camera on increases the experience for everyone
 
 </div>

diff --git a/docs/content/wrap-up.md b/docs/content/wrap-up.md
@@ -7,6 +7,17 @@
 * Microsoft Entra ID App Registrations
 * Remove unused Github CodeSpaces
 
+---
+
+### Enhance the A&A learning
+
+
+It will be beneficial for your learning to spend some time with the material and the exercises at your own pace after the course.
+
+When you learn new stuff - feedback the learning to the #appsec community. 
+
+The workshop is open source - we welcome pull requests (PR's)
+
 ---
 <!-- .slide: data-background-image="content/images/slack-logo-thumb.png" data-background-size="30%" data-background-position="right 2% top 2%"-->
 ## The #AppSec Community

diff --git a/ex-01/doc/registering_app_object_in_azure_ad.md b/ex-01/doc/registering_app_object_in_azure_ad.md
@@ -16,27 +16,16 @@ Steps:
 * Register your personal application with the following properties:
   * Name: "(your initial)-appsec-course-client" (example: "johnd-appsec-course-client")
   * Type: Single tenant
-* Augment app object to be compliant ⚡️
+* Augment app objects to be compliant ⚡️
   * Add an additional owner to AppReg and to the Enterprise App (select course instructor) (Owners)
   * Update the "service management reference" to refer to the "AppSec-Training" - 119775 (Branding & Properties) 
-* Register a client secret for your application (In 'Certificates and Secrets')
-  * Expire: 7 days
-  * Execute the following command to persist the client secret.
-
-    ```shell
-    aa-save-client-secret.sh
-    ```
-  * When asked for by the script, paste the value of the client secret
-  * Select "Reload to Apply" when the message on "Your Codespace Secrets have changed" pops-up.
-
 * Register a redirect uri for your `Web` application (In 'Authentication', Platform Configuration)
   * Use the following command from a terminal window in CodeSpaces to get your redirect uri
 
     ```shell
     echo 'https://'$CODESPACE_NAME'-3000.'$GITHUB_CODESPACES_PORT_FORWARDING_DOMAIN'/'callback
     ```
 
-
   * Please note that the redirect uri will be different for each Codespace.
 * Explore the various attributes for your new app object
   * Overview, EndPoints
@@ -50,8 +39,41 @@ Steps:
 
 ## --Now You--
 
-* Do the steps
-
-When you are done:
+* Do the steps, register the app object
 
 * Post a message to the [appsec-fundamentals-authn-authz](https://equinor.slack.com/archives/C051G3JV7NE) Slack channel and include the "OAuth 2.0 Authorization endpoint (v2)" for your application ⚡️
+
+
+## Registering the client secret
+
+The client need to authenticate itself with the Authorization Server (MS Entra ID). For this it uses a client secret.
+
+Steps:
+
+* Verify that you are using Zsh as shell in your CS terminal window
+  * Look for the `>zsh` in the upper right corner area of you CS terminal
+  * Running `echo $0` should emit `/usr/bin/zsh`
+* Register a client secret for your application (In 'Certificates and Secrets')
+  * Expire: 7 days
+  * Copy the secret value (not the secret id)
+* Execute the following command to persist the client secret as a "Github Codespaces User Secret"</br>Typing "aa-" and then pressing "tab" should help, we have file completion in the terminal.
+
+    ```shell
+    aa-save-client-secret.sh
+    ```
+
+  * When asked for by the script, paste the value of the client secret
+  * Select "Reload to Apply" when the message on "Your Codespace Secrets have changed" pops-up.
+* Verify that the client secret is available in the CS environment
+  * Examine the Github Codespaces Config for you Github profile at [https://github.com/settings/codespaces](https://github.com/settings/codespaces)
+  * You should find the "APPSEC_AA_CLIENT_SECRET" and it should be connected to 1 repo
+  * Execute the following script to output the value secret into your terminal
+
+    ```shell
+    echo $APPSEC_AA_CLIENT_SECRET
+    ```
+  * (If the GH CS user secret is not available, run the "aa-save-client-secret.sh" script again)
+
+## --Now You--
+
+* Do the steps
diff --git a/ex-02/doc/running_the_app.md b/ex-02/doc/running_the_app.md
@@ -10,8 +10,7 @@ When using Github Codespaces we are running out applications in a virtual enviro
 - You can configure Port Forwarding as part of the `/.devcontainer/devcontainer.json`
 - You can configure Port Forwarding using the github CLI (`gh`)
 - Ports have visibility "Private", "Private to Organization" and "Public". The two first ones expects an authenticated session with Github. The "Public" is public to the world - not authentication control is added by Codespaces.
-- For our application we need to make the port forwarding public (The cookies/session information needed to drive the Github authentication is not able to follow the request to login.microsoft.com and will hence break the Github auth regime)
-- We will configure the port forwarding in the next steps
+- For our application using "Private" will work for all out-of-the-box exercises
 
 ## Starting the application
 
@@ -22,21 +21,20 @@ Steps:
   ```shell
   npm start
   ```
-* Open the application using the Popup indicating that the app i running on port 3000 and offering a "Open in Browser" button
-* Select the "get Inbox" button, notice that the request fails
-* Locate the "Ports" section of the Codespace
-* Change the visibility of port 3000 to "public" (right click port -> port visibility)
-* Go back to the "application tab" and select the "get Inbox" button and observe that the content of your inbox is shown.
+* Open the application using the Popup indicating that the app i running on port 3000 and offering a "Open in Browser" button. No need to make the port public
+* Open the browser and test the application
 * Stop the application
 * Observe that the "automatic port forwarding" is removing the forward for port 3000
 * Set the NODE_ENV to "development"
+
   ```shell
   export NODE_ENV=development
   ```
+
 * Start the back-end (`npm start`)
 * Observe that the "automatic port forwarding" is adding the forward for port 3000
 * Use the application again and observer the logging
-* Observe that the port forwarding is public so it remembered your decision
+* Observe that the port forwarding is Private so it remembered your decision
 
 ## --Now You--
 
@@ -53,7 +51,6 @@ Steps:
     npm run dev
     ````
   * prompt
-  * response_mode
   * scope
 * Explore what consent you have given to apps on Microsoft Entra ID on [myapps.microsoft.com](https://myapps.microsoft.com/)
  * Test revoking for your app (if available in the list, if not can you find how to add it to the list? :) )
@@ -62,7 +59,7 @@ Steps:
 
 * It is bad practice to extract information from tokens that are not intended for you
   * Example: Extracting "given_name" at the client from the Access Token
-* The "public port forward" represents a security risk
+* Port forwarding with "public" represents a security risk
 
 ## Prologue
 
@@ -71,5 +68,5 @@ URL parameters from 1st leg, "getting authorization code"
 * **response_type** is part of oauth2 spec [rfc6749](https://datatracker.ietf.org/doc/html/rfc6749)
 * **response_mode** is part of OIDC [core](https://openid.net/specs/openid-connect-core-1_0.html)
   * Specifies the method for sending back the token to the client
-  * One of the reasons why our code supports both GET and POST requests to the redirect_uri endpoint
-* The Microsoft Identity Platform seems to expect a few optional parameters (from RFC) to be mandatory and adds new ones (like response_mode for oAuth2 code grant)
+  * Not part of rfc6749 (oAuth2)
+  * The Microsoft Identity Platform add this as a optional/recommended parameters for oAuth2 as well. Default value is "query"
diff --git a/ex-02/lib/auth-utils.js b/ex-02/lib/auth-utils.js
@@ -77,9 +77,8 @@ function buildAuthorizeUrl(state, scope, responseMode) {
         state: state,
         scope: scope,
         response_mode: responseMode,
+
         prompt: 'select_account',
-        // response_mode: 'form_post',
-        // response_mode: 'query',
     });
 
     logger.debug('Returning URL : ' + redirectUrl);

diff --git a/ex-02/src/app.js b/ex-02/src/app.js
@@ -48,9 +48,7 @@ function build(opts = {}) {
 
     app.get('/showinbox', async function (request, reply) {
         state = createNewState();
-        const response_mode = 'form_post';
-        // const response_mode = 'query';
-
+        const response_mode = 'query';  //recommended, default from the MS Identity platform
         const scope = 'user.read mail.read';
 
         return reply.redirect(

diff --git a/ex-04/doc/lines_of_code.md b/ex-04/doc/lines_of_code.md
@@ -1,6 +1,6 @@
-# Lines of Code - Dependency Scanning
+# Lines of Code - Dependency Scanning (🥸)
 
-In this section we will explore the impact using frameworks has on the amount of code in our projects.
+In this section we will explore some of the impact using open source frameworks and modules has on our project.
 
 ## --Code Analysis--
 

diff --git a/ex-04/lib/app-config.js b/ex-04/lib/app-config.js
@@ -22,7 +22,7 @@ const msalConfig = {
     request: {
         authCodeUrlParameters: {
             scopes: ['user.read mail.read'],
-            responseMode: 'form_post',
+            responseMode: 'query',
             redirectUri: process.env.REDIRECT_URI
             // prompt: 'none',
         },

diff --git a/ex-04/lib/auth-utils.js b/ex-04/lib/auth-utils.js
@@ -105,7 +105,6 @@ async function readInbox(accessToken) {
         });
 
         return newMails;
-
     } catch (error) {
         logger.error('Request for emails failed: ' + error);
         return newMails;

diff --git a/ex-04/readme.md b/ex-04/readme.md
@@ -11,7 +11,7 @@ Our app will list the context of your inbox. A web page is presented, when **sho
 * [Exploring the code](doc/exploring_the_code.md)
 * [Running the application](doc/running_the_application.md)
 * [Security considerations](doc/security_considerations.md)
-* [Lines of code - dependency scanning](doc/lines_of_code.md)
+* [Lines of code - dependency scanning](doc/lines_of_code.md) (🥸)
 
 ---
 

diff --git a/ex-05/doc/running_the_application.md b/ex-05/doc/running_the_application.md
@@ -38,7 +38,7 @@ Steps:
 
 ## --Discuss security issues and good practices--
 
-* Good practice: Cookies holding session information should be marked as "secure" (available using http only)
+* Good practice: Cookies holding session information should be marked as "secure" (available using HTTPS only)
 * Good practice: Move the session store out of the in-memory store. The cookie signing key should be part of app config params.
 * Good practice: Move the token cache out of the in-memory store.
 * Good practice: Follow security advices and recommendations for frameworks

diff --git a/ex-05/lib/app-config.js b/ex-05/lib/app-config.js
@@ -24,7 +24,6 @@ const msalConfig = {
             scopes: ['user.read mail.read'],
             responseMode: 'query',
             redirectUri: process.env.REDIRECT_URI
-            // responseMode: 'form_post',
             // prompt: 'none',
         },
         tokenRequest: {

diff --git a/ex-06/doc/scenario_1.md b/ex-06/doc/scenario_1.md
@@ -49,8 +49,9 @@ Steps:
   * "Sign-in" should be enabled, "Assignment required" should be disabled.
     * Test => Able to sign in.
 
-## --Security considerations--
+## --Security considerations and recommendations--
 
 * Valid account means all accounts in the Microsoft Entra ID tenant, not only "employees". It could be externals, guests accounts or similar.
+* Default configuration for enterprise app registrations should be **"Enabled for users to sign-in=Yes" and "Assignment Required=Yes"**
 * Be aware of security considerations for multi tenant applications ([MS Guidance](https://msrc.microsoft.com/blog/2023/03/guidance-on-potential-misconfiguration-of-authorization-of-multi-tenant-applications-that-use-azure-ad/))
 
diff --git a/ex-06/doc/scenario_2.md b/ex-06/doc/scenario_2.md
@@ -42,7 +42,7 @@ Steps:
 * Login to your application and figure out how to observe the changes (Hint: "id token")
 * When done - post how many AD groups you are member of into the course Slack channel.
 
-### --Further experiments--
+### --Further experiments-- (🥸)
 
 * Do the following experiments (remember to save in AAD and to restart the client back-end between changes. Changes can take "some time" to be reflected)
   * Experiment-1

diff --git a/ex-08/readme.md b/ex-08/readme.md
@@ -1,4 +1,4 @@
-# EX-8 - Implicit grant
+# EX-8 - Implicit grant (🥸)
 
 In this section we will briefly discuss the OAuth2 Implicit Grant. It may be important to understand from a legacy perspective.