Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/kilmajster/keycloak-username-password-attribute-authenticator
Default Keycloak login form with additional validation of configurable user attribute!
https://github.com/kilmajster/keycloak-username-password-attribute-authenticator
docker docker-image helm init-container keycloak keycloak-authenticator keycloak-extension keycloak-spi kubernetes selenide
Last synced: about 2 months ago
JSON representation
Default Keycloak login form with additional validation of configurable user attribute!
- Host: GitHub
- URL: https://github.com/kilmajster/keycloak-username-password-attribute-authenticator
- Owner: kilmajster
- License: mit
- Created: 2021-05-25T18:38:07.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2024-10-14T20:56:16.000Z (2 months ago)
- Last Synced: 2024-10-16T08:09:52.365Z (2 months ago)
- Topics: docker, docker-image, helm, init-container, keycloak, keycloak-authenticator, keycloak-extension, keycloak-spi, kubernetes, selenide
- Language: Java
- Homepage:
- Size: 948 KB
- Stars: 18
- Watchers: 3
- Forks: 6
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Keycloak username password attribute authenticator
[](https://github.com/kilmajster/keycloak-username-password-attribute-authenticator/actions/workflows/maven.yml)
#### Supported Keycloak versions
| 
| [`keycloak-username-password-attribute-authenticator:0.3.0`](https://github.com/kilmajster/keycloak-username-password-attribute-authenticator/tree/0.3.0) |
|-------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------|
| 
| [`keycloak-username-password-attribute-authenticator:1.0.1`](https://github.com/kilmajster/keycloak-username-password-attribute-authenticator/tree/main) |
## Description
Keycloak default login form with additional user attribute validation. Example:
## Usage
To use this authenticator, it should be bundled together with Keycloak, here's how do that:
### Deploying jar
Build your Keycloak image like below:
```Dockerfile
FROM quay.io/keycloak/keycloak:24.0.1
RUN curl -s -L -o /opt/keycloak/providers/keycloak-username-password-attribute-authenticator-1.0.1.jar https://github.com/kilmajster/keycloak-username-password-attribute-authenticator/releases/download/1.0.1/keycloak-username-password-attribute-authenticator-1.0.1.jar
RUN /opt/keycloak/bin/kc.sh build
ENTRYPOINT ["/opt/keycloak/bin/kc.sh", "start"]
```
## Authentication configuration
Following steps shows how to create authentication flow that uses authenticator with user attribute validation.
1. In Keycloak admin console, go to _Authentication_ section, select authentication type of _Browser_ and click
_Duplicate_ action.
2. Set name for new authentication flow eg. `Browser with user attribute` and click _Ok_.
3. In newly created authentication flow remove _Username Password Form_ execution.
4. On _Browser With User Attribute Forms_ level, click _Actions_ > _Add execution_ and select provider of type
_Username Password Attribute Form_, set _Requirement_ to `required`, then save.
5. Then move _Username Password Attribute Form_ on a previous position of _Username Password Form_,
so in the end authentication flow should look like following:
6. On _Username Password Attribute Form_ level, click _Actions_ > _Settings_.
### Minimal configuration
- ##### `User attribute`
Attribute used to validate login form.
### Advanced configuration
- ##### `Generate label` (default true)
If enabled, label for login form will be generated based on attribute name, so attribute with name:
- `favorite_number` will be labeled as _Favorite number_
- `REALLY_custom.user-Attribute` will be translated to _Really custom user attribute_, etc.
By default, set to `true`. If `User attribute form label`
is configured, label is taken form configuration and generation is skipped.
- ##### `User attribute form label`
Message which will be displayed as user attribute input label. If value is a valid message key, then proper translation will be used.
- ##### `Invalid user attribute error message`
Message which will be displayed as user attribute validation error. If value is a valid message key, then proper translation will be used.
## Theme configuration
Theme configuration is handled in clients section, in following example Keycloak default `account-console` client will be used.
### Using bundled default Keycloak theme
In Keycloak admin panel, go to _Clients_ and select client you want to authenticate with user attribute form. As _Login Theme_ set `base-with-attribute`
Then in advance section > _Authentication Flow Overrides_ for _Browser Flow_, choose authentication that contain previously configured login form,
so for example `Browser with user attribute`.
### Extending own theme
If you have your own theme, then in `.your-theme/login/login.ftl` add following below `
` responsible for a password stuff or anywhere you want.
How it was done with _Keycloak base_ theme, you can check [here](/src/main/resources/theme/base-with-attribute/login/login.ftl).
```html
<#if usernameHidden?? && messagesPerField.existsError('username','password')>
${kcSanitize(messagesPerField.getFirstError('username','password'))?no_esc}
#if>
<#if user_attribute_label??>${msg(user_attribute_label)}<#else>${msg("defaultUserAttributeLabel")}#if>
<#if usernameHidden?? && messagesPerField.existsError('username','password', 'user_attribute')>
${kcSanitize(messagesPerField.getFirstError('username','password'))?no_esc}
#if>
<#if realm.rememberMe && !usernameHidden??>
```
### Testing & development
#### Build the project
```shell
$ mvn package
```
#### Run Keycloak with authenticator in docker compose
After building a project, do following to start Keycloak with bundled authenticator jar and dummy configuration ([`dev-realm.json`](dev-realm.json)).
```shell
$ docker compose up
```
Open browser and go to http://localhost:8080/realms/dev-realm/account
use _Username or email_ = `test`, _Password_ = `test` and _Favorite number_ = `46` to login.