Update matrix-auth-plugin docs for v3.2+ syntax (#2718)

Co-authored-by: Junaid-Ashraf-56 <[email protected]>
Co-authored-by: Tim Jacomb <[email protected]>

Author: 3 people

demos/global-matrix-auth/README.md

@@ -1,21 +1,80 @@
-# Configure Matrix Authorization Strategy
+# matrix-auth-plugin
 
-Basic configuration of the [Matrix Authorization Strategy plugin](https://plugins.jenkins.io/matrix-auth)
+Configuration of the [Matrix Authorization Strategy plugin](https://plugins.jenkins.io/matrix-auth)
 
-## sample configuration
+There are a couple of built-in authorizations to consider.
+
+- **anonymous** - anyone who has not logged in.
+- **authenticated** - anyone who has logged in.
+
+## sample-configuration (global matrix)
 
 ```yaml
 jenkins:
-  securityRealm:
-    local:
-      allowsSignup: false
-      users:
-        - id: test
-          password: test
-
   authorizationStrategy:
     globalMatrix:
-      permissions:
-        - "Overall/Read:anonymous"
-        - "Overall/Administer:authenticated"
+      entries:
+        - user:
+            name: "admin"
+            permissions:
+              - "Overall/Administer"
+        - user:
+            name: "anonymous"
+            permissions:
+              - "Overall/Read"
+              - "Job/Read"
+        - group:
+            name: "authenticated"
+            permissions:
+              - "Overall/Read"
+              - "Job/Build"
+              - "Job/Create"
 ```
+
+
+## sample-configuration (project based matrix)
+
+```yaml
+jenkins:
+  authorizationStrategy:
+    projectMatrix:
+      entries:
+        - group:
+            name: "authenticated"
+            permissions:
+              - "View/Delete"
+              - "View/Read"
+              - "View/Configure"
+              - "View/Create"
+              - "Job/Read"
+              - "Job/Build"
+              - "Job/Configure"
+              - "Job/Create"
+              - "Job/Delete"
+              - "Job/Discover"
+              - "Job/Move"
+              - "Job/Workspace"
+              - "Job/Cancel"
+              - "Run/Delete"
+              - "Run/Replay"
+              - "Run/Update"
+              - "SCM/Tag"
+              - "Overall/Administer"
+        - user:
+            name: "anonymous"
+            permissions:
+              - "Overall/Read"
+```
+
+Some permissions depends on actual plugin-usage.  
+For Example: `Release/*:authenticated` is only available if you _use_ the Release plugin in one of your jobs.
+
+## GitHub Authorization
+
+https://plugins.jenkins.io/github-oauth/
+
+You can configure authorization based on GitHub users, organizations, or teams.
+
+- **username** - specific GitHub username.
+- **organization** - every user that belongs to a specific GitHub organization.
+- **organization*team** - specific GitHub team of a GitHub organization.

demos/matrix-auth/README.md

@@ -14,7 +14,7 @@
     <!-- no need to be deployed during release, this is a test-only module -->
     <maven.deploy.skip>true</maven.deploy.skip>
     <jenkins.baseline>2.516</jenkins.baseline>
-    <jenkins.version>${jenkins.baseline}.1</jenkins.version>
+    <jenkins.version>${jenkins.baseline}.3</jenkins.version>
   </properties>
 
   <dependencyManagement>

integrations/pom.xml

@@ -0,0 +1,60 @@
+package io.jenkins.plugins.casc;
+
+import static org.junit.Assert.assertEquals;
+
+import hudson.model.Job;
+import hudson.security.GlobalMatrixAuthorizationStrategy;
+import hudson.security.ProjectMatrixAuthorizationStrategy;
+import io.jenkins.plugins.casc.misc.ConfiguredWithReadme;
+import io.jenkins.plugins.casc.misc.JenkinsConfiguredWithReadmeRule;
+import java.util.Set;
+import jenkins.model.Jenkins;
+import org.jenkinsci.plugins.matrixauth.PermissionEntry;
+import org.junit.Rule;
+import org.junit.Test;
+import org.junit.jupiter.api.Assertions;
+
+/**
+ * @author Mads Nielsen
+ * @since 1.0
+ */
+public class MatrixAuthorizationTest {
+
+    @Rule
+    public JenkinsConfiguredWithReadmeRule j = new JenkinsConfiguredWithReadmeRule();
+
+    @Test
+    @ConfiguredWithReadme("matrix-auth/README.md#0")
+    public void checkGlobalCorrectlyConfiguredPermissions() {
+        assertEquals(
+                "The configured instance must use the Global Matrix Authentication Strategy",
+                GlobalMatrixAuthorizationStrategy.class,
+                Jenkins.get().getAuthorizationStrategy().getClass());
+        GlobalMatrixAuthorizationStrategy gms =
+                (GlobalMatrixAuthorizationStrategy) Jenkins.get().getAuthorizationStrategy();
+
+        Set<PermissionEntry> adminPermission = gms.getGrantedPermissionEntries().get(Job.BUILD);
+        assertEquals("authenticated", adminPermission.iterator().next().getSid());
+
+        Set<PermissionEntry> readPermission = gms.getGrantedPermissionEntries().get(Job.READ);
+        assertEquals("anonymous", readPermission.iterator().next().getSid());
+    }
+
+    @Test
+    @ConfiguredWithReadme("matrix-auth/README.md#1")
+    public void checkProjectCorrectlyConfiguredPermissions() {
+        Assertions.assertEquals(
+                ProjectMatrixAuthorizationStrategy.class,
+                Jenkins.get().getAuthorizationStrategy().getClass(),
+                "The configured instance must use the Global Matrix Authentication Strategy");
+        ProjectMatrixAuthorizationStrategy gms =
+                (ProjectMatrixAuthorizationStrategy) Jenkins.get().getAuthorizationStrategy();
+
+        Set<PermissionEntry> adminPermission = gms.getGrantedPermissionEntries().get(Jenkins.ADMINISTER);
+        Assertions.assertEquals(
+                "authenticated", adminPermission.iterator().next().getSid());
+
+        Set<PermissionEntry> readPermission = gms.getGrantedPermissionEntries().get(Jenkins.READ);
+        Assertions.assertEquals("anonymous", readPermission.iterator().next().getSid());
+    }
+}