Merge pull request #3 from PhilanthropyDataCommons/2-initial-keycloak…

…-sms-authenticator

Afford a twilio SMS Authenticator for keycloak

.github/workflows/build.yml

@@ -0,0 +1,24 @@
+name: Build
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+
+jobs:
+  target_node:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository code.
+        uses: actions/checkout@v3
+      - name: Get Zulu OpenJDK (current LTS version).
+        uses: actions/setup-java@v3
+        with:
+          distribution: 'zulu'
+          java-version: '17'
+      - name: Build a shaded fat jar.
+        working-directory: twilio-keycloak-provider
+        run: ./gradlew shadowJar

.github/workflows/test.yml

@@ -0,0 +1,24 @@
+name: Test
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+
+jobs:
+  target_node:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository code.
+        uses: actions/checkout@v3
+      - name: Get Zulu OpenJDK (current LTS version)
+        uses: actions/setup-java@v3
+        with:
+          distribution: 'zulu'
+          java-version: '17'
+      - name: Run tests and code coverage report.
+        working-directory: twilio-keycloak-provider
+        run: ./gradlew test jacocoReport

README.md

@@ -1,2 +1,5 @@
 # Authentication and Authorization services for Philanthropy Data Commons
 PDC related extensions that were made for the keycloak auth service
+
+See each subdirectory for the license associated with its respective extension.
+

twilio-keycloak-provider/.gitattributes

@@ -0,0 +1,9 @@
+#
+# https://help.github.com/articles/dealing-with-line-endings/
+#
+# Linux start script should use lf
+/gradlew        text eol=lf
+
+# These are Windows script files and should use crlf
+*.bat           text eol=crlf
+

twilio-keycloak-provider/.gitignore

@@ -0,0 +1,5 @@
+# Ignore Gradle project-specific cache directory
+.gradle
+
+# Ignore Gradle build output directory
+build

twilio-keycloak-provider/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2020 Niko Köbler
+Copyright (c) 2023 Open Tech Strategies
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

twilio-keycloak-provider/README.md

@@ -0,0 +1,80 @@
+# Twilio Keycloak SMS Authentication Provider
+
+A keycloak Authentication SPI implementation providing SMS verification.
+
+Based on https://github.com/dasniko/keycloak-2fa-sms-authenticator at 4205a6c.
+
+## How to build and run tests
+
+Start in the `lib` directory
+
+- `cd twilio-keycloak-provider/lib`
+
+### Build with dependencies included in a fat jar (recommended)
+
+- `../gradlew shadowJar`
+
+The resulting jar should be in `build/libs`. This (fat) jar is what should be included in keycloak's `/providers` directory. See below for details and how to verify that it is OK to include.
+
+### Build plain jar without dependencies included (not recommended for deployment but may be useful for debugging)
+
+- `../gradlew jar`
+
+The resulting jar should be in `build/libs`. This jar could be included in keycloak's `/providers` directory but also requires twilio and its dependencies to be included on the keycloak classpath by other means. It is assumed in this document that you will use the fat jar.
+
+### Run tests
+
+- `../gradlew test`
+
+## How to include the software in keycloak
+
+Before including the fat jar in keycloak, verify that the shadow/relocation process results are as expected. There should only be software under one package (directory): `org.philanthropydatacommons`.
+
+In other words, verify exactly three directories in the root of the jar:
+1. `META-INF`
+2. `org`
+3. `theme-resources`
+
+Furthermore, verify:
+1. inside the `org` directory, there is exactly one directory, `philanthropydatacommons`, and
+2. inside that `philanthropydatacommons` directory, there are exactly two directories, `auth` and `shadow`.
+
+If there are more or fewer directories than expected above, this means any of the following problems (or more) occurred:
+* Twilio's transitive dependencies changed (e.g. a newer version of twilio's jar had different dependencies), and/or
+* the shadow plugin changed behavior (e.g. a newer version of the shadow plugin differs), and/or
+* new code was included under an unexpected package/directory structure.
+
+To see a change in dependencies, use gradle to list dependencies, e.g. `../gradlew dependencies` or `../gradlew dependencyInsight --dependency problemDepName`. Use `git` to go back and find what version of the software worked OK and did not violate the above rules. Change the `shadowJar` task in the build script (`build.gradle.kts`) accordingly, with a view for what jars are (or are not) present in keycloak's classpath.
+
+To see what jars are in the keycloak distribution, within a shell on the keycloak machine or container:
+`find /path/to/keycloak/lib/lib/main /path/to/keycloak/providers -name "*.jar"`
+
+Example command inside a bitnami keycloak container:
+`find /opt/bitnami/keycloak/lib/lib/main /opt/bitnami/keycloak/providers -name "*.jar"`
+
+If all appears to be OK, copy the fat jar to keycloak's `/providers` directory or make it visible there by some other means (e.g. docker volume mount).
+
+## How to use the software in keycloak
+
+In the keycloak administration interface for a realm:
+
+1. Create a copy of the browser flow,
+2. add the `SMS Authentication` step to the newly created flow,
+3. enable this new flow as the browser flow (effectively disabling the old browser flow),
+4. configure properties of the new flow (add a name), and
+5. enable dasniko's "required action" in the realm (requires a jar of [dasniko's requiredaction](https://github.com/dasniko/keycloak-extensions-demo/tree/main/requiredaction) at or near commit 0ae273c in `/providers` as well).
+
+Most details can be found at [dasniko's blog post](https://www.n-k.de/2020/12/keycloak-2fa-sms-authentication.html).
+
+## How to configure Twilio
+
+Use the following environment variables to configure Twilio:
+
+- `TWILIO_PHONE_NUMBER`: the "from" phone number set up in Twilio.
+- `TWILIO_ACCOUNT_SID`: the SID or username for Twilio API access.
+- `TWILIO_AUTH_TOKEN`: the token or secret for Twilio API access.
+
+
+## License
+
+Expat (also called MIT) license, see LICENSE file.

twilio-keycloak-provider/gradle/wrapper/gradle-wrapper.properties

@@ -0,0 +1,6 @@
+distributionBase=GRADLE_USER_HOME
+distributionPath=wrapper/dists
+distributionUrl=https\://services.gradle.org/distributions/gradle-8.0.1-bin.zip
+networkTimeout=10000
+zipStoreBase=GRADLE_USER_HOME
+zipStorePath=wrapper/dists