Add HOWTO on groups configuration

README.md

@@ -25,6 +25,7 @@ A Jenkins plugin which lets you login to Jenkins using your own, self-hosted or
   - [Contributing](#contributing)
 - [Documentation](docs/)
   - [Configuration](docs/configuration/README.md)
+  - [How to ...](docs/howto/README.md)
   - [FAQ](docs/FAQ.md)
 </details>
 
@@ -59,7 +60,7 @@ OpenID Connect Authentication plugin is installed as other plugins:
 
 In either case, choosing the plugin as Security Realm means that other
 authentication methods (Jenkins Database, LDAP, ...) will no
-longer be available and any missconfiguration or service availability
+longer be available and any misconfiguration or service availability
 issue will lock out the users. An *escape hatch* can be activated at
 configuration time to define a admin credential which can be used to
 recover access to Jenkins.
@@ -75,7 +76,7 @@ documentation.
 
 In a nutshell, the configuration is done in three steps:
 1. **Register Jenkins** as an OIDC client in your provide. You will need these details:
-    - Login Redirec URI: `${JENKINS_ROOT_URL}/securityRealm/finishLogin`
+    - Login Redirect URI: `${JENKINS_ROOT_URL}/securityRealm/finishLogin`
     - Logout Redirect URI: `${JENKINS_ROOT_URL}/OicLogout`
     - scope: openid profile email
     - Grant Type: `authorization_code`
@@ -85,7 +86,8 @@ In a nutshell, the configuration is done in three steps:
    Normally, providers expose .well-known/openid-configuration which has all the details client need to know.
 
 Detailed instructions for [Generic OpenID Connect](docs/configuration/README.md)
-configuration are provided in the documentation. 
+configuration are provided in the documentation. Some [HOWTO](docs/howto/README.md)
+are provided for the various aspects of the configuration.
 
 See the following screenshot utilizing the google well known endpoint
 for a minimal configuration example: 
@@ -162,7 +164,7 @@ panel of the plugin's repository. They also available in the
 
 Contributions are welcome, we are looking for:
 
-- developpers to implement the features, improve the code and whatever
+- developers to implement the features, improve the code and whatever
   hackers do for a living
 - anybody wanting to help sorting the issues, improve,
   [translate](https://jenkins.crowdin.com/u/projects/25)

docs/FAQ.md

@@ -21,7 +21,7 @@ Logs contains warnings about crumb and CSRF issues:
 
 *Workaround*
 
-This was solved by installin the [Strict Crumb Issuer](https://plugins.jenkins.io/strict-crumb-issuer/) plugin.
+This was solved by installing the [Strict Crumb Issuer](https://plugins.jenkins.io/strict-crumb-issuer/) plugin.
 Relevant JCasC configuration is the following:
 
 ```jenkins:

docs/howto/GROUPS_FROM_IDP.md

@@ -0,0 +1,87 @@
+# Groups from Identity Provider (IDP)
+
+When a user logs in using OpenID Connect, the plugin can be configured to extract group
+information from the openid token and/or the userinfo endpoint of the provider.
+
+General steps are:
+
+  1. Create groups in IDP and associate them to users - configure plugin to extract groups
+  2. Create group with same name in Jenkins and associate rights
+  3. When user connects, it gets the rights of group configured in step 2
+
+There is a special group named `Authenticated Users` which applies rights to user that were able
+to authenticate but without any specific group.
+
+## Groups from IDP
+
+The actual creation of groups and how it is associated to user is outside the scope of this HOWTO.
+Please refer to the documentation of your provider.
+
+Throughout the configuration of the plugin, you can check which groups (*authorities*) were assigned to you
+by visiting the whoami url of your jenkins `https://<root url>/whoAmI/` (case is important).
+
+> **Who Am I?**
+> Name: `<username>`
+> IsAuthenticated?:	true
+> Authorities:	
+> - "Jenkins user"
+> - "Jenkins admin"
+
+If you do not see anything of your groups, it means that the plugin was not able to
+collect the information: either the configuration is wrong or the information is not provided.
+
+### Inspect IdToken or UserInfo
+
+The plugin doesn't currently propose a way to inspect raw information from provider.
+
+Either you provider or a tool should be able to present the data in json
+format.
+
+Sample:
+
+```json
+{
+  "exp": 1713262211,
+  ... standard information ...
+  "sub": "<user>",
+  "realm_access": {
+    "roles": [
+      "foo users",
+      "bar users"
+    ]
+  },
+  "name": "<full name>",
+  "preferred_username": "<login name>",
+  "email": "<mail address>"
+}
+```
+
+### Configure group field
+
+The `Group` field of the plugin's configuration can be expressed as a [JMES Path](https://jmespath.org/).
+JMES is a way to express how to collect fields from a JSON document.
+
+The online tool provided on the website can used for debugging the field configuration:
+
+- paste the data in the big box (it should be a valid json)
+- adapt the line at the top with the expression
+- inspect the output at the bottom: correct output should be a list of strings containing your groups' name
+
+Example: `realm_access.roles` with the data of the precedent section
+
+## Create Jenkins groups
+
+OpenID Connect doesn't provide a API for collecting groups name. The groups
+must be created manually in the "Security" section of configuration.
+
+The actual configuration depends on the "Authorization" strategy.
+The follwoing instructions apply to Matrix-based and Project-based security.
+
+For each group you want to associate with rights:
+
+- create a group by clicking on the `Add Group ...` button
+- the name of the group in the popup windows should be the same as the provider's (with case and spaces)
+- tick the columns on the lines of the new group
+
+Finally, save the configuration.
+

docs/howto/README.md

@@ -0,0 +1,6 @@
+# HOW TO ...
+
+The following Linux HOWTOs are currently available:
+
+- [Associate group(s) to user](GROUPS_FROM_IDP.md): grant rights to user based on providers' groups
+