NB-Public/keycloak-2fa-sms-authenticator
0
0
Fork 0
mirror of https://github.com/netzbegruenung/keycloak-2fa-sms-authenticator.git synced 2024-05-10 22:56:08 +02:00
Code Issues Projects Releases Wiki Activity

Improve documentation

Browse source 
- Add hints for solving problems during building the problem.
- Move SMS Authenticator documentation into submodule.
- Add README section about current github action release workflow.
This commit is contained in:
Giuliano Mele 2024-03-27 08:12:43 +01:00
parent 39d57035ad
commit 9456fb88aa
Signed by: MelGi
GPG key ID: E790C1211F6DEE5E
2 changed files with 38 additions and 25 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

38
README.md
View file

@ -5,42 +5,30 @@ This repository contains the source code for a collection of Keycloak MFA plugin
* Force MFA & Selection dialog (work in progress)
* Native App MFA integration (work in progress)
The different plugins are documented below.
The different plugins are documented in the submodules README or in docs folder.
# License
The code of this project is Apache 2.0 licensed. Parts of the original code are MIT licensed.
# Keycloak 2FA SMS Authenticator
Keycloak Authentication Provider implementation to get a 2nd-factor authentication with a OTP/code/token send via SMS with a configurable HTTPS API. It should be possible to interact with most SMS providers. Issues and pull requests to support more SMS providers are welcome.
This is a fork of a great demo implementation by [@dasniko](https://github.com/dasniko/keycloak-2fa-sms-authenticator), and also takes huge chunks of code from the original authenticator provider [documentation](https://www.keycloak.org/docs/latest/server_development/index.html#_auth_spi) and [example](https://github.com/keycloak/keycloak/tree/main/examples/providers/authenticator) from Keycloak itself.
## Building
# Building
1. Clone this repository
1. Install Apache Maven
1. Change into the cloned directory and run
```shell
mvn package
mvn clean install
```
A file `target/netzbegruenung.keycloak-2fa-sms-authenticator.jar` should be created.
## Installing
1. Go to https://github.com/netzbegruenung/keycloak-2fa-sms-authenticator/releases and download
the latest .jar file.
1. Copy the created jar file into the `providers` directory of your Keycloak:
```shell
cp netzbegruenung.keycloak-2fa-sms-authenticator.jar /path/to/keycloak/providers
```
1. Run the `build` command and restart Keycloak:
```shell
/path/to/keycloak/bin/kc.sh build [your-additional-flags]
systemctl restart keycloak.service
```
If building fails and the problem is caused or related to the dev module or tests, try to run `mvn clean install -DskipTests`.
## Usage
1. Add a new execution to the 2FA flow of your Browser flow, choose "SMS Authentication (2FA)".
1. Make sure that you name it "sms-2fa". This is currently a hack that will hopefully be fixed. Additional executions with other names can be added. But this first execution will be used for the confirmation SMS when setting up a new phone number.
1. Go into the config of the execution and configure the plugin so that it works with the API of your SMS proivder.
## Deployment
Deployment is done by github actions: `.github/workflows/release.yml`
To trigger the release workflow be sure to have proper access rights and follow the steps below.
https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/configuring-tag-protection-rules#about-tag-protection-rules
1. Update revision property in parent POM file `pom.xml`
1. `git tag -a v1.2.3 -m "Bump version 1.2.3"`
1. `git push --tags`
After building completes the new release is available on github containing the jar files for each module.

25
sms-authenticator/README.md Normal file
View file

@ -0,0 +1,25 @@
# Keycloak 2FA SMS Authenticator
Keycloak Authentication Provider implementation to get a 2nd-factor authentication with a OTP/code/token send via SMS with a configurable HTTPS API.
It should be possible to interact with most SMS providers. Issues and pull requests to support more SMS providers are welcome.
This is a fork of a great demo implementation by [@dasniko](https://github.com/dasniko/keycloak-2fa-sms-authenticator), and also takes huge chunks of code
from the original authenticator provider [documentation](https://www.keycloak.org/docs/latest/server_development/index.html#_auth_spi) and [example](https://github.com/keycloak/keycloak/tree/main/examples/providers/authenticator) from Keycloak itself.
# Installing
1. Go to https://github.com/netzbegruenung/keycloak-mfa-plugins/releases and download
the latest .jar file.
1. Copy the created jar file into the `providers` directory of your Keycloak:
```shell
cp netzbegruenung.keycloak-2fa-sms-authenticator.jar /path/to/keycloak/providers
```
1. Run the `build` command and restart Keycloak:
```shell
/path/to/keycloak/bin/kc.sh build [your-additional-flags]
systemctl restart keycloak.service
```
# Usage
1. Add a new execution to the 2FA flow of your Browser flow, choose "SMS Authentication (2FA)".
1. Make sure that you name it "sms-2fa". This is currently a hack that will hopefully be fixed. Additional executions with other names can be added. But this first execution will be used for the confirmation SMS when setting up a new phone number.
1. Go into the config of the execution and configure the plugin so that it works with the API of your SMS proivder.