diff --git a/README.md b/README.md index 00a13b1..abe5d19 100644 --- a/README.md +++ b/README.md @@ -1,73 +1,133 @@ -

- Nest Logo -

+# Keycloak User Manager -[circleci-image]: https://img.shields.io/circleci/build/github/nestjs/nest/master?token=abc123def456 -[circleci-url]: https://circleci.com/gh/nestjs/nest - -

A progressive Node.js framework for building efficient and scalable server-side applications.

-

-NPM Version -Package License -NPM Downloads -CircleCI -Coverage -Discord -Backers on Open Collective -Sponsors on Open Collective - - Support us - -

- +The `keycloak-user-manager` package provides an easy way to manage users with Keycloak in a NestJS application. It offers pre-built endpoints for common user management tasks while allowing customization for your own endpoints if needed. + +## Features + +- Easy integration with Keycloak +- Pre-built user management endpoints +- Configurable module for different Keycloak instances +- Extendable service for custom user management logic ## Description -[Nest](https://github.com/nestjs/nest) framework TypeScript starter repository. +Module/Boilerplate for simplified user-management w/ [Keycloak](https://www.keycloak.org/) in NestJS applications ## Installation +To install the package, use npm or yarn: + ```bash -$ npm install +npm install keycloak-user-manager +# or +yarn add keycloak-user-manager ``` -## Running the app +## Configuration -```bash -# development -$ npm run start +To configure the module, you need to provide the Keycloak connection details in your `app.module.ts` file: -# watch mode -$ npm run start:dev +```typescript +# app.module.ts +import { Module } from '@nestjs/common'; +import { KeycloakUserManagerModule } from 'keycloak-user-manager'; -# production mode -$ npm run start:prod -``` +@Module({ + imports: [ + KeycloakUserManagerModule.forRoot({ + baseUrl: 'http://localhost:8080', + realm: 'med5-realm', + clientId: 'med5-clientId', + clientSecret: 'med5-clientSecret', -## Test + }), + ], +}) +@Global() +export class AppModule {} +``` +

+Do not forget to provide your own Keycloak options. +

-```bash -# unit tests -$ npm run test +## Usage +### Pre-built Endpoints + +Once the module is configured, you can use the following endpoints to manage users: + +- `GET /users`: Returns a list of all users in the Keycloak realm. +- `GET /users/:id`: Returns the user with the specified ID. +- `POST /users`: Creates a new user in the Keycloak realm. +- `PUT /users/:id`: Updates the user with the specified ID. +- `DELETE /users/:id`: Deletes the user with the specified ID. +- `PUT /users/reset-password`: Resets the password of a user. + +You should respect the following shape of the user object: +```typescript +{ + username: string; + email: string; + firstName: string; + lastName: string; +} +// for resetting the password, the body should be: +{ + id: string; + password: string; +} +``` +

The email is optional, but if provided, it will be used to create the user in Keycloak. (It can be used as a login identifier).

+
+

+The username is required, and it will be used by Keycloak to identify the user so it should be unique. +

-# e2e tests -$ npm run test:e2e -# test coverage -$ npm run test:cov +### Custom Endpoints + +If you need to create your own endpoints, you can use the `KeycloakUserManagerService` provided by the module. Following is an example of how to use it: + +```typescript +import { Controller, Post } from '@nestjs/common'; +import { KeycloakUserManagerService } from 'keycloak-user-manager'; +import { AddUserDto, UpdateUserDto } from 'src/dto/custom-users.dto'; + +@Controller('custom-users') +export class UserService { + constructor(private readonly keycloakUserManagerService: KeycloakUserManagerService) {} + + @Post() + async addUser(@Body() addUserDto: AddUserDto){ + return await this.keycloakUserManagerService.createUser(addUserDto); + } + + @Put(':id') + async modifyUser(@Param('id') id: string, @Body() updateUserDto: UpdateUserDto){ + return await this.keycloakUserManagerService.updateUser(id, updateUserDto); + } + + @Get(':id') + async getOneUser(@Param('id') id: string){ + return await this.keycloakUserManagerService.findUserById(id); + } + + @Get() + async getAllUsers(){ + return await this.keycloakUserManagerService.findManyUsers(); + } + @Delete(':id') + async removeUser(@Param('id') id: string){ + return await this.keycloakUserManagerService.deleteUser(id); + } + +} ``` -## Support +## Contributing -Nest is an MIT-licensed open source project. It can grow thanks to the sponsors and support by the amazing backers. If you'd like to join them, please [read more here](https://docs.nestjs.com/support). +Contributions are welcome! Feel free to do contribute by opening issues and/or pull requests. ## Stay in touch -- Author - [Kamil Myśliwiec](https://kamilmysliwiec.com) -- Website - [https://nestjs.com](https://nestjs.com/) -- Twitter - [@nestframework](https://twitter.com/nestframework) - -## License - -Nest is [MIT licensed](LICENSE). +- Author - [Mohamed Lamine Badji] (https://flowcv.me/muhammad-al-amine) +- Twitter - [@Med5Lemzi](https://x.com/Med5Lemzi) diff --git a/package.json b/package.json index 9b40d44..7fc94ff 100644 --- a/package.json +++ b/package.json @@ -2,7 +2,7 @@ "name": "nest-keycloak-user-manager", "version": "0.0.1", "description": "", - "author": "", + "author": "Mohamed Lamine Badji ", "private": false, "license": "UNLICENSED", "repository": {