
Micro-service for identity and access management, facilitating user, organization, and role management with Keycloak integration. Offers SDKs and clients for seamless application communication.
IM is a microservice for Identity and Access Management built with Kotlin and Spring Cloud Function, leveraging a Keycloak instance. It enables the creation and management of Spaces, Users, Organizations, and Privileges, which can then be used to authenticate via Keycloak.
IM simplifies identity and access management with the following features:
IM interacts with Keycloak using Keycloak's Admin Client and exposes endpoints to communicate with other applications.
Define the necessary parameters in your application.yml file:
connect:
fs:
url: http://fs:8090A sample docker-compose configuration for the IM Gateway:
services:
im-gateway:
image: ${DOCKER_REPOSITORY}im-gateway:${VERSION_IM}
environment:
- server_port=8004
- f2_tenant_issuer-base-uri=${KC_URL_PUBLIC}
- connect_im_keycloak_url=${KC_URL_PUBLIC}
- connect_im_keycloak_realm=${KC_ROOT_REALM}
- connect_im_keycloak_clientId=${KC_IM_CLIENT_ID}
- connect_im_keycloak_clientSecret=${KC_IM_CLIENT_SECRET}
ports:
- "8004:8004"Features act as access control filters, defining the specific contexts in which permissions can be applied. They ensure permissions are valid only in allowed contexts.
| Permission Name | Description | Required Features |
|---|---|---|
| im_user_read | Ability to view any user data | feat_im_all, feat_im_own |
| im_user_write | Ability to modify any user data | feat_im_all, feat_im_own |
| im_user_role_write | Ability to modify the roles of a user | feat_im_all, feat_im_own |
| im_user_self | Ability to view and modify one's own account (profile, email, password, MFA) | feat_im_all, feat_im_own |
| im_organization_read | Ability to view any organization data | feat_im_all |
| im_organization_write | Ability to modify any organization data | feat_im_all |
| im_organization_read_own | Ability to view own organization data and its members | feat_im_all, feat_im_own |
| im_organization_write_own | Ability to modify own organization data | feat_im_all, feat_im_own |
| im_organization_apikey_read | Ability to read any organization API keys | feat_im_all |
| im_organization_status_write | Ability to write organization status | feat_im_all |
| im_role_read | Ability to view any role data | feat_im_all, feat_im_own |
| im_role_write | Ability to modify any role data | feat_im_all |
| im_apikey_read | Ability to view API keys | feat_im_all, feat_im_own |
| im_apikey_write | Ability to modify API keys | feat_im_all, feat_im_own |
| im_space_read | Ability to view space data | feat_im_all |
| im_space_write | Ability to modify space data | feat_im_all |
| im_mfa_force_otp | Ability to force MFA otp on a user | feat_im_all |
Every rule of IM requires a permission, acting on oneself included. Reading one's own account
needs im_user_self (or im_user_read); modifying it, within the organization rule, needs
im_user_self (or im_user_write); configuring its MFA needs im_user_self. Reading one's own
organization, its members or the organization and user refs needs im_organization_read_own
(or im_organization_read / im_user_read).
Both are granted to every user by default, as composites of the realm's default role
(default-roles-<realm>). Keycloak gives that role to every user it creates, through the
admin API or self-registration, and to every client's service account (API keys included);
IM keeps it when it reassigns a user's roles. Putting them on a user or admin role is
therefore unnecessary, and would be lost each time IM rewrites that user's roles.
Like every permission carrying features, they reach a token only when the client's scope
holds feat_im_all or feat_im_own (see UserRealmRoleFeatureMapper): a full-scope client
gets them, a client without full scope — a third-party application acting for the user —
does not, and its token can neither read nor modify its own user or organization. A user
whose roles hold neither feature gets neither permission, as for every other feat_im_own
permission.
New realms: im-script (im.script.space.jsonCreate) creates the permissions and adds
them to the default role.
Existing realms: re-run im-script with the realm's space-create.json as
im.script.space.jsonCreate. The realm is kept as is; the script creates the IM permissions
that are missing and adds those two to the default role if it does not hold them yet.
Without that re-run, users of the realm lose access to their own account and organization
through IM. If im-script cannot be run, do the same with kcadm.sh:
REALM=my-realm
kcadm.sh config credentials --server "$KC_URL" --realm master --user "$KC_ROOT_USER" --password "$KC_ROOT_PASS"
DEFAULT_ROLE=$(kcadm.sh get "realms/$REALM" --fields 'defaultRole(name)' | sed -n 's/^ *"name" : "\(.*\)",*$/\1/p')
kcadm.sh create roles -r "$REALM" -s name=im_user_self \
-s "description=Ability to view and modify one's own account (profile, email, password, MFA)" \
-s 'attributes={"type":["PERMISSION"],"features":["[\"feat_im_all\"]","[\"feat_im_own\"]"]}'
kcadm.sh create roles -r "$REALM" -s name=im_organization_read_own \
-s "description=Ability to view own organization data and its members" \
-s 'attributes={"type":["PERMISSION"],"features":["[\"feat_im_all\"]","[\"feat_im_own\"]"]}'
kcadm.sh add-roles -r "$REALM" --rname "$DEFAULT_ROLE" \
--rolename im_user_self --rolename im_organization_read_ownIM publishes, under the group io.komune.im, the Kotlin Multiplatform modules a client needs: the
domains and the clients. Use the root coordinate; Gradle resolves its -jvm or -js variant.
| Kind | Coordinates |
|---|---|
| Clients (JVM only) |
im-apikey-client, im-organization-client, im-privilege-client, im-space-client, im-user-client
|
| Domains |
im-apikey-domain, im-organization-domain, im-privilege-domain, im-space-domain, im-user-domain
|
| Shared domains |
im-commons-domain, im-commons-auth, im-mfa-core-domain, im-organization-core-domain, im-privilege-core-domain, im-user-core-domain
|
| Keycloak plugin SDK (JVM) |
im-keycloak-plugin-client, im-keycloak-plugin-domain: verify and read the webhooks of IM's Keycloak plugin |
implementation("io.komune.im:im-user-domain:${Versions.im}")
implementation("io.komune.im:im-user-client:${Versions.im}")The server side is not published since 0.28.0: it is IM's own and ships in the im-gateway,
im-script and im-keycloak images. These coordinates have no 0.28.0 and later:
api-config, im-apikey-api, im-apikey-lib, im-client-core-api, im-client-core-domain,
im-commons-api, im-commons-core, im-keycloak, im-mfa-core-api, im-organization-api, im-organization-core-api,
im-organization-lib, im-privilege-api, im-privilege-core-api, im-privilege-lib, im-redis,
im-space-api, im-space-lib, im-user-api, im-user-core-api, im-user-lib.
The clients are JVM modules since 0.28.0: im-<x>-client-jvm and im-<x>-client-js have no 0.28.0
and later, and im-<x>-client is the JVM artifact itself. A JavaScript caller uses f2's
httpF2JsClient with the domain packages.
The clients provided use Ktor and should be singletons:
@Configuration
class ImConfig(
private val tokenProvider: TokenProvider
) {
@Value("\${im.url}")
lateinit var imUrl: String
@Bean
fun userClient() = UserClient(
url = imUrl,
generateBearerToken = tokenProvider::getToken
)
}i2-keycloak:keycloak-plugin
./gradlew i2-keycloak:keycloak-plugin:shadowJar
i2-keycloak/docker/
(steps 2 and 3 can be done automatically with make package-keycloak)
PUT /admin/realms/{realm}/im-welcome-email/users/{id} sends welcome.ftl with the subject welcomeSubject, manage-users required. IM calls it for a creation handing over the password, and for a password reset on an account without credentials. The link lasts connect.im.user.welcomeLinkLifespanSeconds (7 days by default).
To use it, an email theme adds html/welcome.ftl, text/welcome.ftl and the welcomeSubject message. A theme without them keeps Keycloak's executeActions mail with the realm's lifespan. Re-read the endpoint against Keycloak's UserResource.executeActionsEmail at every Keycloak upgrade.
client ("xxx-web" + "account") hardcoded claim: event-http-wehbook = url to send the events to
if local and keycloak is within docker container, use ip address instead of localhost
It is possible to filter the events to send from the keycloak GUI by going to Events > Login Events Settings > Save Events ON > Saved Types
Endpoint example:
@Configuration
class KeycloakEventEndpoint(
private val applicationContext: ApplicationContext
) {
@PermitAll
@Bean
fun keycloakEvent(): F2Consumer<KeycloakHttpEvent> = f2Consumer { event ->
println(event.type)
applicationContext.publishEvent(event)
}
}IM is a microservice for Identity and Access Management built with Kotlin and Spring Cloud Function, leveraging a Keycloak instance. It enables the creation and management of Spaces, Users, Organizations, and Privileges, which can then be used to authenticate via Keycloak.
IM simplifies identity and access management with the following features:
IM interacts with Keycloak using Keycloak's Admin Client and exposes endpoints to communicate with other applications.
Define the necessary parameters in your application.yml file:
connect:
fs:
url: http://fs:8090A sample docker-compose configuration for the IM Gateway:
services:
im-gateway:
image: ${DOCKER_REPOSITORY}im-gateway:${VERSION_IM}
environment:
- server_port=8004
- f2_tenant_issuer-base-uri=${KC_URL_PUBLIC}
- connect_im_keycloak_url=${KC_URL_PUBLIC}
- connect_im_keycloak_realm=${KC_ROOT_REALM}
- connect_im_keycloak_clientId=${KC_IM_CLIENT_ID}
- connect_im_keycloak_clientSecret=${KC_IM_CLIENT_SECRET}
ports:
- "8004:8004"Features act as access control filters, defining the specific contexts in which permissions can be applied. They ensure permissions are valid only in allowed contexts.
| Permission Name | Description | Required Features |
|---|---|---|
| im_user_read | Ability to view any user data | feat_im_all, feat_im_own |
| im_user_write | Ability to modify any user data | feat_im_all, feat_im_own |
| im_user_role_write | Ability to modify the roles of a user | feat_im_all, feat_im_own |
| im_user_self | Ability to view and modify one's own account (profile, email, password, MFA) | feat_im_all, feat_im_own |
| im_organization_read | Ability to view any organization data | feat_im_all |
| im_organization_write | Ability to modify any organization data | feat_im_all |
| im_organization_read_own | Ability to view own organization data and its members | feat_im_all, feat_im_own |
| im_organization_write_own | Ability to modify own organization data | feat_im_all, feat_im_own |
| im_organization_apikey_read | Ability to read any organization API keys | feat_im_all |
| im_organization_status_write | Ability to write organization status | feat_im_all |
| im_role_read | Ability to view any role data | feat_im_all, feat_im_own |
| im_role_write | Ability to modify any role data | feat_im_all |
| im_apikey_read | Ability to view API keys | feat_im_all, feat_im_own |
| im_apikey_write | Ability to modify API keys | feat_im_all, feat_im_own |
| im_space_read | Ability to view space data | feat_im_all |
| im_space_write | Ability to modify space data | feat_im_all |
| im_mfa_force_otp | Ability to force MFA otp on a user | feat_im_all |
Every rule of IM requires a permission, acting on oneself included. Reading one's own account
needs im_user_self (or im_user_read); modifying it, within the organization rule, needs
im_user_self (or im_user_write); configuring its MFA needs im_user_self. Reading one's own
organization, its members or the organization and user refs needs im_organization_read_own
(or im_organization_read / im_user_read).
Both are granted to every user by default, as composites of the realm's default role
(default-roles-<realm>). Keycloak gives that role to every user it creates, through the
admin API or self-registration, and to every client's service account (API keys included);
IM keeps it when it reassigns a user's roles. Putting them on a user or admin role is
therefore unnecessary, and would be lost each time IM rewrites that user's roles.
Like every permission carrying features, they reach a token only when the client's scope
holds feat_im_all or feat_im_own (see UserRealmRoleFeatureMapper): a full-scope client
gets them, a client without full scope — a third-party application acting for the user —
does not, and its token can neither read nor modify its own user or organization. A user
whose roles hold neither feature gets neither permission, as for every other feat_im_own
permission.
New realms: im-script (im.script.space.jsonCreate) creates the permissions and adds
them to the default role.
Existing realms: re-run im-script with the realm's space-create.json as
im.script.space.jsonCreate. The realm is kept as is; the script creates the IM permissions
that are missing and adds those two to the default role if it does not hold them yet.
Without that re-run, users of the realm lose access to their own account and organization
through IM. If im-script cannot be run, do the same with kcadm.sh:
REALM=my-realm
kcadm.sh config credentials --server "$KC_URL" --realm master --user "$KC_ROOT_USER" --password "$KC_ROOT_PASS"
DEFAULT_ROLE=$(kcadm.sh get "realms/$REALM" --fields 'defaultRole(name)' | sed -n 's/^ *"name" : "\(.*\)",*$/\1/p')
kcadm.sh create roles -r "$REALM" -s name=im_user_self \
-s "description=Ability to view and modify one's own account (profile, email, password, MFA)" \
-s 'attributes={"type":["PERMISSION"],"features":["[\"feat_im_all\"]","[\"feat_im_own\"]"]}'
kcadm.sh create roles -r "$REALM" -s name=im_organization_read_own \
-s "description=Ability to view own organization data and its members" \
-s 'attributes={"type":["PERMISSION"],"features":["[\"feat_im_all\"]","[\"feat_im_own\"]"]}'
kcadm.sh add-roles -r "$REALM" --rname "$DEFAULT_ROLE" \
--rolename im_user_self --rolename im_organization_read_ownIM publishes, under the group io.komune.im, the Kotlin Multiplatform modules a client needs: the
domains and the clients. Use the root coordinate; Gradle resolves its -jvm or -js variant.
| Kind | Coordinates |
|---|---|
| Clients (JVM only) |
im-apikey-client, im-organization-client, im-privilege-client, im-space-client, im-user-client
|
| Domains |
im-apikey-domain, im-organization-domain, im-privilege-domain, im-space-domain, im-user-domain
|
| Shared domains |
im-commons-domain, im-commons-auth, im-mfa-core-domain, im-organization-core-domain, im-privilege-core-domain, im-user-core-domain
|
| Keycloak plugin SDK (JVM) |
im-keycloak-plugin-client, im-keycloak-plugin-domain: verify and read the webhooks of IM's Keycloak plugin |
implementation("io.komune.im:im-user-domain:${Versions.im}")
implementation("io.komune.im:im-user-client:${Versions.im}")The server side is not published since 0.28.0: it is IM's own and ships in the im-gateway,
im-script and im-keycloak images. These coordinates have no 0.28.0 and later:
api-config, im-apikey-api, im-apikey-lib, im-client-core-api, im-client-core-domain,
im-commons-api, im-commons-core, im-keycloak, im-mfa-core-api, im-organization-api, im-organization-core-api,
im-organization-lib, im-privilege-api, im-privilege-core-api, im-privilege-lib, im-redis,
im-space-api, im-space-lib, im-user-api, im-user-core-api, im-user-lib.
The clients are JVM modules since 0.28.0: im-<x>-client-jvm and im-<x>-client-js have no 0.28.0
and later, and im-<x>-client is the JVM artifact itself. A JavaScript caller uses f2's
httpF2JsClient with the domain packages.
The clients provided use Ktor and should be singletons:
@Configuration
class ImConfig(
private val tokenProvider: TokenProvider
) {
@Value("\${im.url}")
lateinit var imUrl: String
@Bean
fun userClient() = UserClient(
url = imUrl,
generateBearerToken = tokenProvider::getToken
)
}i2-keycloak:keycloak-plugin
./gradlew i2-keycloak:keycloak-plugin:shadowJar
i2-keycloak/docker/
(steps 2 and 3 can be done automatically with make package-keycloak)
PUT /admin/realms/{realm}/im-welcome-email/users/{id} sends welcome.ftl with the subject welcomeSubject, manage-users required. IM calls it for a creation handing over the password, and for a password reset on an account without credentials. The link lasts connect.im.user.welcomeLinkLifespanSeconds (7 days by default).
To use it, an email theme adds html/welcome.ftl, text/welcome.ftl and the welcomeSubject message. A theme without them keeps Keycloak's executeActions mail with the realm's lifespan. Re-read the endpoint against Keycloak's UserResource.executeActionsEmail at every Keycloak upgrade.
client ("xxx-web" + "account") hardcoded claim: event-http-wehbook = url to send the events to
if local and keycloak is within docker container, use ip address instead of localhost
It is possible to filter the events to send from the keycloak GUI by going to Events > Login Events Settings > Save Events ON > Saved Types
Endpoint example:
@Configuration
class KeycloakEventEndpoint(
private val applicationContext: ApplicationContext
) {
@PermitAll
@Bean
fun keycloakEvent(): F2Consumer<KeycloakHttpEvent> = f2Consumer { event ->
println(event.type)
applicationContext.publishEvent(event)
}
}