JanssenProject · mo-auto · Oct 28, 2022 · Oct 28, 2022
diff --git a/docs/admin/install/vm-install/rhel.md b/docs/admin/install/vm-install/rhel.md
@@ -46,7 +46,7 @@ interactive mode.
 
 After the successful completion of setup process, [verify the system health](../install-faq.md#after-installation-how-do-i-verify-that-the-janssen-server-is-up-and-running).
 
-### Red Hat / Centos Un-installation
+## Red Hat / Centos Un-installation
 
 Removing Janssen is a two step process:
 

diff --git a/docs/admin/install/vm-install/suse.md b/docs/admin/install/vm-install/suse.md
@@ -12,7 +12,6 @@ tags:
 
 Before you install, check the [VM system requirements](vm-requirements.md).
 
-
 ## Supported versions
 - SUSE Linux Enterprise Server (SLES) 15
 - openSUSE Leap 15.4
@@ -48,7 +47,7 @@ interactive mode.
 
 After the successful completion of setup process, [verify the system health](../install-faq.md#after-installation-how-do-i-verify-that-the-janssen-server-is-up-and-running).
 
-## Uninstall
+## Un-installation
 
 Uninstall process involves two steps
 

diff --git a/docs/admin/install/vm-install/ubuntu.md b/docs/admin/install/vm-install/ubuntu.md
@@ -10,7 +10,6 @@ tags:
 
 Before you install, check the [VM system requirements](vm-requirements.md).
 
-
 ## Supported Versions
 - Ubuntu 20.04
 
@@ -50,7 +49,7 @@ interactive mode.
 
 After the successful completion of setup process, [verify the system health](../install-faq.md#after-installation-how-do-i-verify-that-the-janssen-server-is-up-and-running).
 
-# Ubuntu Janssen Un-Installation
+## Ubuntu Janssen Un-Installation
 
 Removing Janssen is a two step process:
 

diff --git a/docs/admin/planning/application-portal.md b/docs/admin/planning/application-portal.md
@@ -4,5 +4,12 @@ tags:
   - planning
 ---
 
-This is a placeholder
+An application portal ("portal") is a website which displays all the
+protected applications available for an end user to access. The Janssen Project
+does not provide a portal. But you can build your own.
 
+Each application that you want in your portal should be configured as an
+OpenID Connect RP. Build a simple website (any CMS will do) that is also
+an RP. The OP can provide the roles of the user, or another claim, which will
+enable your portal to determine which websites to display. Iterate and
+display the websites (or icons) with the respective URLs.
diff --git a/docs/admin/planning/benchmarking.md b/docs/admin/planning/benchmarking.md
@@ -2,7 +2,53 @@
 tags:
   - administration
   - planning
+  - benchmarking
 ---
 
-This is a placeholder
+Want confidence that your Janssen platform will perform with the latency and
+concurrency you need in production? If so, then you MUST benchmark properly.
+It's critical that your test data and transactions mock what you need to prove
+in production. For cloud native deployments, benchmarking is also essential
+to test auto-scaling and failover. Ideally, you'll test the same hardware
+and network.
 
+Remember that OAuth has different flows, which have a different number of steps,
+and different requirements for compute and persistence. For example, the
+OAuth Client Credential Grant is very short: there is one token request, and
+one token response. The OpenID Code Flow has many more steps: it has a
+request/response to the authorization, token, Userinfo and logout endpoints.
+It's really important to test the exact flow you intend to use in production.
+
+Benchmarking also has the benefit of testing the index configuration in your
+database. Every database trades disk space for performance by using indexes.
+If you miss an index, performance sometimes comes to a grinding halt. Your
+service may even crash. Having confidence that all potential index scenario's
+get executed in your benchmarking is essential.
+
+Auth Server publishes [JUnit](https://junit.org) tests and some tools for
+generating test data. Because each page rendered by Auth Server has a state,
+you cannot use a static load generation page tool. Don't forget to gather data
+on compute, storage, and memory. Also watch the resources consumed by the each
+web service and system service (e.g. database). You can't find the bottleneck
+without this data. System libraries and hardware choices may also impact your
+results.
+
+Benchmarking is an iterative process. Inevitably, things never go exactly how
+you guessed they would. And you make changes to your environment and run the
+benchmarking tests again--*ad naseum*. Leave enough time for benchmarking. How
+ever much time you think it will take, triple your estimate.
+
+Make sure you look at both short tests and long running tests. A slow memory
+leak may only present after many hours of high load. Also, run some crazy tests,
+just so you know what happens. Some organizations benchmark for ten times
+normal volume. But when an incident happens, they see 1,000 times normal volume.
+Think outside-the-box.  
+
+It's tricky load testing some newer two-factor authentication services,
+especially if they rely on new features of the browser. Hopefully the tools to
+benchmark these will evolve.
+
+Janssen Auth Server supports a number of deployment models--both VM and cloud
+native. While cloud native architecture enables true horizontal scalability,
+it comes at a cost. Benchmarking can help you understand if that cost is
+justified.
diff --git a/docs/admin/planning/certificates-keys.md b/docs/admin/planning/certificates-keys.md
@@ -28,10 +28,10 @@ JSON documents. There are six IETF RFCs that provide considerable detail:
 | ------------- |:-------------:|
 | DPOP     | RS256, RS384, RS512, ES256, ES384, ES512, PS256, PS384, PS512 |
 | Authorization  | HS256, HS384, HS512, RS256, RS384, RS512, ES256, ES384, ES512, ES512, PS256, PS384, PS512      |
-| Request Object  | [ none, HS256, HS384, HS512, RS256, RS384, RS512, ES256, ES384, ES512, PS256, PS384, PS512      |
+| Request Object  | HS256, HS384, HS512, RS256, RS384, RS512, ES256, ES384, ES512, PS256, PS384, PS512      |
 | Userinfo  | HS256, HS384, HS512, RS256, RS384, RS512, ES256, ES384, ES512, PS256, PS384, PS512       |
 | Token Endpoint Auth | HS256, HS384, HS512, RS256, RS384, RS512, ES256, ES384, ES512, PS256, PS384, PS512   |
-| ID Token  | none, HS256, HS384, HS512, RS256, RS384, RS512, ES256, ES384, ES512, PS256, PS384, PS512 |
+| ID Token  | HS256, HS384, HS512, RS256, RS384, RS512, ES256, ES384, ES512, PS256, PS384, PS512 |
 
 ### Auth Server Supported Encryption
 

diff --git a/docs/admin/planning/discovery.md b/docs/admin/planning/discovery.md
@@ -4,5 +4,30 @@ tags:
   - planning
 ---
 
-This is a placeholder
+In a federated identity topology, you can authenticate a person by redirecting
+their browser to the correct IDP. But what happens when there is more then
+one IDP? Before the person authenticates, how do you know to which IDP to send
+them? This challenge is called "discovery", "where are you from", or "WAYF".
 
+There are a few ways to handle discovery. Here are a few:
+
+1. Display a list of logos and enable the end user to pick the IDP. If you
+ever clicked on a social login button, you've experienced this approach.
+
+2. Use a different URL for each IDP, like `https://customer1.saas.com` or
+`https://saas.com/customer2`. Based on which URL the person hits, you know
+where to send them.
+
+3. Prompt the person to enter something identifying, like their email address.
+You can use this to look up their home IDP.
+
+4. Use contextual information, like network address, geolocation, or browser
+data.
+
+Once you've figured out the person behind the browser, it may make sense to
+write a cookie so next time, you don't have to bother them.
+
+While it's possible to implement a discovery workflow using an Agama script
+or an Auth Server person authentication interception script, you also write
+a simple web application, and then redirect to the authorization endpoint
+with a hint as an extra parameter and a specific `acr_values`.