use the bare jar from the ear instead

Reviewed-on: #84

.forgejo/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,28 @@
+---
+name: Bug Report
+about: Report a problem with this project
+title: ''
+labels: ''
+assignees: ''
+
+---
+
+### Expected Behaviour
+
+Please provide a description of the expected behaviour.
+
+### Actual Behavior
+
+Please provide a description of the actual behaviour.
+
+### Steps To Reproduce
+
+Please provide the steps to reproduce the issue.
+
+### Environment
+
+Please provide relevant details of your environment:
+
+* keycloak version
+* java version
+* platform (O/S, etc.)

.forgejo/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,24 @@
+---
+name: Feature Request
+about: Suggest an idea for this project
+title: ''
+labels: ''
+assignees: ''
+
+---
+
+### Desired Behaviour
+
+Please provide a description of the desired behaviour.
+
+### Actual Behavior
+
+Please provide a description of the actual behaviour.
+
+### Environment
+
+Please provide relevant details of your environment:
+
+* keycloak version
+* java version
+* platform (O/S, etc.)

.forgejo/dependabot.yml

@@ -0,0 +1,6 @@
+version: 2
+updates:
+  - package-ecosystem: "maven"
+    directory: "/" # Location of package manifests
+    schedule:
+      interval: "daily"

.forgejo/pull_request_template.md

@@ -0,0 +1,7 @@
+### Description
+
+Please provide a description that details the content of the pull request.
+
+Please also indicate whether any issues are fixed.
+
+Fixes # (issue)

.forgejo/workflows/analyze.yml

@@ -0,0 +1,32 @@
+# name: analyze
+#
+# on:
+#   push:
+#     branches: [ main ]
+#   pull_request:
+#     branches: [ main ]
+#   schedule:
+#     - cron: '24 21 * * 6'
+#
+# jobs:
+#   analyze:
+#     runs-on: ubuntu-latest
+#     strategy:
+#       fail-fast: false
+#       matrix:
+#         language: [ 'java' ]
+#     permissions:
+#       actions: read
+#       contents: read
+#       security-events: write
+#     steps:
+#     - name: checkout repository
+#       uses: actions/checkout@v2
+#     - name: initialize CodeQL
+#       uses: github/codeql-action/init@v1
+#       with:
+#         languages: ${{ matrix.language }}
+#     - name: autobuild
+#       uses: github/codeql-action/autobuild@v1
+#     - name: perform CodeQL analysis
+#       uses: github/codeql-action/analyze@v1

.forgejo/workflows/build.yml

@@ -0,0 +1,25 @@
+name: build
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  build:
+    runs-on: docker
+    steps:
+    - name: checkout repository
+      uses: https://gitea.com/actions/checkout@v2
+    - name: set up java
+      uses: https://gitea.com/actions/setup-java@v4
+      with:
+        java-version: '21'
+        distribution: 'temurin'
+    - name: Set up Maven
+      uses: https://github.com/stCarolas/setup-maven@v5
+      with:
+        maven-version: 3.9.9
+    - name: build with maven
+      run: mvn --batch-mode --file pom.xml package

.forgejo/workflows/publish.yml

@@ -0,0 +1,33 @@
+name: publish
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  build:
+    runs-on: docker
+    steps:
+    - name: checkout repository
+      uses: actions/checkout@v4
+    - name: set up java
+      uses: https://gitea.com/actions/setup-java@v4
+      with:
+        java-version: '21'
+        distribution: 'temurin'
+    - name: Set up Maven
+      uses: https://github.com/stCarolas/setup-maven@v5
+      with:
+        maven-version: 3.9.9
+    - name: build with maven
+      run: mvn --batch-mode --file pom.xml -Drevision=${GITHUB_REF_NAME/v/} -Dkeycloak.version=21.0.0 package
+    - name: copy jars
+      run: |-
+        mkdir -p release/jars
+        cp -v bundle/target/keycloak-regex-mapper-*/com.github.lucafilipozzi-keycloak-regex-mapper-*.jar release/jars
+    - name: upload to release
+      uses: actions/forgejo-release@v2.6.0
+      with:
+        direction: upload
+        release-dir: 'release/jars'

.github/ISSUE_TEMPLATE/bug_report.md

@@ -1,38 +1,28 @@
 ---
-name: Bug report
+name: Bug Report
-about: Create a report to help us improve
+about: Report a problem with this project
 title: ''
 labels: ''
 assignees: ''
 
 ---
 
-**Describe the bug**
+### Expected Behaviour
-A clear and concise description of what the bug is.
 
-**To Reproduce**
+Please provide a description of the expected behaviour.
-Steps to reproduce the behavior:
-1. Go to '...'
-2. Click on '....'
-3. Scroll down to '....'
-4. See error
 
-**Expected behavior**
+### Actual Behavior
-A clear and concise description of what you expected to happen.
 
-**Screenshots**
+Please provide a description of the actual behaviour.
-If applicable, add screenshots to help explain your problem.
 
-**Desktop (please complete the following information):**
+### Steps To Reproduce
- - OS: [e.g. iOS]
- - Browser [e.g. chrome, safari]
- - Version [e.g. 22]
 
-**Smartphone (please complete the following information):**
+Please provide the steps to reproduce the issue.
- - Device: [e.g. iPhone6]
- - OS: [e.g. iOS8.1]
- - Browser [e.g. stock browser, safari]
- - Version [e.g. 22]
 
-**Additional context**
+### Environment
-Add any other context about the problem here.
+
+Please provide relevant details of your environment:
+
+* keycloak version
+* java version
+* platform (O/S, etc.)

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,24 @@
+---
+name: Feature Request
+about: Suggest an idea for this project
+title: ''
+labels: ''
+assignees: ''
+
+---
+
+### Desired Behaviour
+
+Please provide a description of the desired behaviour.
+
+### Actual Behavior
+
+Please provide a description of the actual behaviour.
+
+### Environment
+
+Please provide relevant details of your environment:
+
+* keycloak version
+* java version
+* platform (O/S, etc.)

.github/pull_request_template.md

@@ -0,0 +1,7 @@
+### Description
+
+Please provide a description that details the content of the pull request.
+
+Please also indicate whether any issues are fixed.
+
+Fixes # (issue)

.github/workflows/publish.yml

@@ -16,7 +16,9 @@ jobs:
         java-version: '11'
     - name: build with maven
       run: mvn --batch-mode --file pom.xml package
-    - name: publish to github packages
+    - name: upload to release
-      run: mvn --batch-mode --file pom.xml deploy
+      uses: skx/github-action-publish-binaries@master
       env:
-        GITHUB_TOKEN: ${{ github.token }}⏎
+        GITHUB_TOKEN: ${{ github.token }}
+      with:
+        args: 'bundle/target/*.ear'

.gitignore

@@ -9,3 +9,6 @@
 
 # java
 target/
+
+# summon
+secrets.yml

README.md

@@ -10,13 +10,13 @@
 [![alerts][alerts-img]][alerts-url]
 [![code quality][code-quality-img]][code-quality-url]
 
+[![lines of code][lines-of-code-img]][lines-of-code-url]
 [![maintainability][maintainability-img]][maintainability-url]
 [![technical debt][technical-debt-img]][technical-debt-url]
-[![vulnerabilities][vulnerabilities-img]][vulnerabilities-url]
 
 # keycloak-regex-mapper
 
-This project provides a [keycloak][keycloak] broker mapper that maps a
+This project provides a [Keycloak][keycloak] broker mapper that maps a
 multivalued OIDC claim (e.g.: groups) or SAML attribute (e.g.: groupMembership)
 into one or more realm and/or client role assignments based on regular
 expressions.
@@ -29,7 +29,150 @@ Copy `keycloak-regex-mapper-«version».ear` to `${KEYCLOAK_HOME}/deployments`.
 
 ### configuration
 
-TODO
+The _Advanced Claim to Role_ (OIDC) and _Advanced Attribute to Role_ (SAML) mappers included with
+Keycloak provide a mechanism to map specific claim/attribute values to a specific target realm or
+client. This can be tedious to configure if there are many target roles that should be mapped.
+
+The purpose of the _Regex Realm and Client Role Importer_ mappers (one for OIDC, one for SAML)
+included in this project is to provide a mechanism to map many entries in an OIDC claim
+( e.g., `groups`) or SAML attribute (e.g.: `groupMembership`) to target roles using a single
+configured mapper.
+
+The mechanism relies on two principles:
+
+* that the claim / attribute provider uses clientId and realmName values when naming things... in
+  other words, the mapping exists on the claim/attribute provider
+* assigning an attribute to each realm and claim role to be managed by the mapper
+
+#### OIDC Example
+
+Suppose that the claim provider has a group structure as follows:
+
+```
+/IdentityBrokers
+  /idb1                         # this is the realm
+    /Roles                      # these are the realm roles
+      SupportAnalyst            # A
+        member=alice
+        member=bob
+    /ServiceProviders           # these are the clients
+      /sp1                      # B
+        /Roles                  # these are the client roles for sp1
+          Impersonator          # C
+            member=alice
+      /sp2                      # D
+        /Roles                  # these are the client roles for sp2
+          OtherRole             # E
+            member=bob
+```
+
+Then, when Alice logs in to / through idb1, the `groups` claim would contain:
+
+```
+IdentityBroker/idb1/Roles/SupportAnalysts
+IdentityBroker/idb1/ServiceProviders/sp1/Roles/Impersonator
+```
+
+Whereas Bob's would contain:
+
+```
+IdentityBroker/idb1/Roles/SupportAnalysts
+IdentityBroker/idb1/ServiceProviders/sp2/Roles/OtherRole
+```
+
+At the identity broker, realm and client roles would be configured as follows:
+
+```
+Roles                           # these are the realm roles
+  SupportAnalyst                # matches A above
+Clients
+  sp1                           # matches B above
+    Roles                       # these are the client roles for sp1
+      Impersonator              # matches C above
+        attribute:
+          key="automatically mapped"
+          value="true"
+  sp2                           # matches D above
+    Roles                       # these are the client roles for sp2
+      OtherRole                 # matches E above
+        attribute:
+          key="automatically mapped"
+          value="true"
+```
+
+And the _Regex Realm and Client Role Importer_ mapper would be configured as follows:
+
+| configuration key               | value                                                                    |
+| ------------------------------- | ------------------------------------------------------------------------ |
+| type                            | `Regex Realm and Client Role Importer`                                   |
+| name                            | `groups to realm and client roles`                                       |
+| sync mode override              | `force`                                                                  |
+| OIDC claim name                 | `groups`                                                                 |
+| client roles attribute name     | `automatically mapped`                                                   |
+| client roles regular expression | `/IdentityBrokers/idb1/ServiceProviders/(?<client>.*)/Roles/(?<role>.*)` |
+| realm roles attribute name      | `automatically mapped`                                                   |
+| realm roles regular expression  | `/IdentityBrokers/idb1/Roles/(?<role>.*)`                                |
+
+The purpose of the the `client roles attribute name` and the `realm roles attribute name` is to flag
+for the mapper which client and realm roles to assign / un-assign. Otherwise, every role not
+matching the regular expressions would be un-assigned, including those that might have been locally
+assigned by an administrator.
+
+Take note of the named groupings (e.g.: `(?<client>.*)` in the regular expressions:
+
+* the `client roles regular expression` needs two: `client` and `role`.
+* The `realm roles regular expression` only needs one: `role`.
+
+#### SAML example
+
+Suppose the attribute provider draws group membership from an LDAP server structured as follows:
+
+```
+dc=example,dc=com
+  ou=IdentityBrokers
+    ou=idb1
+      ou=Roles                  # realm roles
+        cn=SystemAnalyst
+          member=alice
+          member=bob
+      ou=ServiceProviders
+        ou=sp1
+          ou=Roles              # client roles for sp1
+            cn=Impersonator
+              member=alice
+        ou=sp2
+          ou=Roles              # client roles for sp2
+            cn=OtherRole
+              member=bob
+```
+
+For Alice, groupMembership would contain:
+
+```
+                          cn=SystemAnalyst,ou=Roles,ou=idb1,ou=IdentityBrokers,dc=example,dc=com
+cn=Impersonator,ou=Roles,ou=sp1,ou=ServiceProviders,ou=idb1,ou=IdentityBrokers,dc=example,dc=com
+```
+
+For Bob, groupMembership would contain:
+
+```
+                          cn=SystemAnalyst,ou=Roles,ou=idb1,ou=IdentityBrokers,dc=example,dc=com
+   cn=OtherRole,ou=Roles,ou=sp2,ou=ServiceProviders,ou=idb1,ou=IdentityBrokers,dc=example,dc=com
+```
+
+Assuming the same realm and client role configuration as above (in the OIDC example), then the _Regex
+Realm and Client Role Importer_ mapper would be configured as follows:
+
+| configuration key               | value                                                                                                       |
+| ------------------------------- | ----------------------------------------------------------------------------------------------------------- |
+| type                            | `Regex Realm and Client Role Importer`                                                                      |
+| name                            | `groups to realm and client roles`                                                                          |
+| sync mode override              | `force`                                                                                                     |
+| SAML attribute name             | `groupMembership`                                                                                           |
+| client roles attribute name     | `automatically mapped`                                                                                      |
+| client roles regular expression | `cn=(^<role>.*),ou=Roles,ou=(^<client>.*),ou=ServiceProviders,ou=idb1,ou=IdentityBrokers,dc=example,dc=com` |
+| realm roles attribute name      | `automatically mapped`                                                                                      |
+| realm roles regular expression  | `cn=(^<role>.*),ou=Roles,ou=idb1,ou=IdentityBrokers,dc=example,dc=com`                                      |
 
 ## development
 
@@ -39,8 +182,8 @@ This project follows the module/bundle approach to packaging keycloak extensions
 
 * `module` builds the jar that contains the keycloak extensions
 
-* `bundle` builds the ear that contains the jar from `module` and the jars for
+* `bundle` builds the ear that contains the jar from `module` and any jars that are
-  any not-provided dependencies
+  not designated as `provided` dependencies
 
 ### coding conventions
 
@@ -55,7 +198,6 @@ This project uses:
 ---
 Copyright 2021 Luca Filipozzi. Some rights reserved. See [LICENSE][license-url].
 
-
 [keycloak]: https://keycloak.org/
 
 [style-guide]: https://google.github.io/styleguide/javaguide.html
@@ -83,9 +225,9 @@ Copyright 2021 Luca Filipozzi. Some rights reserved. See [LICENSE][license-url].
 [code-quality-img]: https://badgen.net/lgtm/grade/g/LucaFilipozzi/keycloak-regex-mapper/java?icon=lgtm
 [code-quality-url]: https://lgtm.com/projects/g/LucaFilipozzi/keycloak-regex-mapper/context:java
 
+[lines-of-code-img]: https://badgen.net/codeclimate/loc/LucaFilipozzi/keycloak-regex-mapper?icon=codeclimate
+[lines-of-code-url]: https://codeclimate.com/github/LucaFilipozzi/keycloak-regex-mapper
 [maintainability-img]: https://badgen.net/codeclimate/maintainability/LucaFilipozzi/keycloak-regex-mapper?icon=codeclimate
 [maintainability-url]: https://codeclimate.com/github/LucaFilipozzi/keycloak-regex-mapper/maintainability
 [technical-debt-img]: https://badgen.net/codeclimate/tech-debt/LucaFilipozzi/keycloak-regex-mapper?icon=codeclimate
 [technical-debt-url]: https://codeclimate.com/github/LucaFilipozzi/keycloak-regex-mapper/maintainability
-[vulnerabilities-img]: https://badgen.net/snyk/LucaFilipozzi/keycloak-regex-mapper/main/pom.xml
-[vulnerabilities-url]: https://snyk.io/test/github/lucafilipozzi/keycloak-regex-mapper?targetFile=pom.xml

SECURITY.md

@@ -1,6 +1,6 @@
 # Security Policy
 
-This project is provided on a 'time-avaialble' basis.
+This project is provided on a 'time-available' basis.
 
 If you have a security concern to report, please open an issue or a pull request.
 

pom.xml

@@ -42,21 +42,13 @@
     <url>https://github.com/${github.account}/${project.artifactId}</url>
   </scm>
 
-  <distributionManagement>
-    <repository>
-      <id>github</id>
-      <name>Github Packages</name>
-      <url>https://maven.pkg.github.com/${github.account}/${project.artifactId}</url>
-    </repository>
-  </distributionManagement>
-
   <properties>
     <maven.compiler.source>1.8</maven.compiler.source>
     <maven.compiler.target>1.8</maven.compiler.target>
     <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
     <github.account>lucafilipozzi</github.account>
-    <revision>1.0.6</revision>
+    <revision>develop</revision>
-    <keycloak.version>15.0.2</keycloak.version>
+    <keycloak.version>26.0.7</keycloak.version>
   </properties>
 
   <!-- IMPORTANT: don't forget to update jboss-deployment-structure.xml -->
@@ -151,7 +143,7 @@
         <plugin>
           <groupId>org.apache.maven.plugins</groupId>
           <artifactId>maven-enforcer-plugin</artifactId>
-          <version>3.0.0-M3</version>
+          <version>3.5.0</version>
           <configuration>
             <rules>
               <!-- org.apache.maven.plugins:maven-enforcer-plugin -->
@@ -159,7 +151,7 @@
                 <version>1.8</version>
               </requireJavaVersion>
               <requireMavenVersion>
-                <version>3.6.0</version>
+                <version>3.9.0</version>
               </requireMavenVersion>
               <requirePluginVersions>
                 <banLatest>true</banLatest>
@@ -193,14 +185,14 @@
             <dependency>
               <groupId>org.codehaus.mojo</groupId>
               <artifactId>extra-enforcer-rules</artifactId>
-              <version>1.3</version>
+              <version>1.6.1</version>
             </dependency>
           </dependencies>
         </plugin>
         <plugin>
           <groupId>org.codehaus.mojo</groupId>
           <artifactId>buildnumber-maven-plugin</artifactId>
-          <version>1.4</version>
+          <version>3.0.0</version>
         </plugin>
 
         <!-- compile -->
@@ -241,7 +233,7 @@
             <dependency>
               <groupId>org.codehaus.plexus</groupId>
               <artifactId>plexus-archiver</artifactId>
-              <version>4.2.5</version>
+              <version>4.6.1</version>
             </dependency>
           </dependencies>
         </plugin>
@@ -260,7 +252,7 @@
             <dependency>
               <groupId>com.puppycrawl.tools</groupId>
               <artifactId>checkstyle</artifactId>
-              <version>8.45.1</version>
+              <version>10.6.0</version>
             </dependency>
           </dependencies>
           <configuration>
@@ -282,7 +274,7 @@
         <plugin>
           <groupId>org.owasp</groupId>
           <artifactId>dependency-check-maven</artifactId>
-          <version>6.2.2</version>
+          <version>8.0.1</version>
           <configuration>
             <skipProvidedScope>true</skipProvidedScope>
           </configuration>