npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@amplication/plugin-auth-keycloak

v0.0.11

Published

Keycloak Authentication plugin for Amplication

Downloads

152,192

Readme

@amplication/plugin-auth-keycloak

NPM Downloads

This plugin helps in integrating Keycloak into your app generated by Amplication and provides the required configuration files.

Purpose

Provides a way to integrate Keycloak into your app generated by Amplication by adding the required dependencies and configuration files. Keycloak is an open source software product to allow single sign-on with Identity Management and Access Management aimed at modern applications and services.

Working with the plugin

It can be used by adding the plugin in the plugins page of the app settings. The plugin can be added by providing the settings as shown in general settings.

[!WARNING] Have to add the auth-core-plugin plugin before adding this plugin.

Results in configuring the app to use Keycloak for authentication. It adds the necessary dependencies, creates a JWT strategy and adds the required environment variables in the .env file.

General Configuration

To use the plugin, the following values are required to be provided in the plugin settings.

  • port: The port on which you want to run the Keycloak server. ( Optional, Default: 8080 )

  • realmID: The ID of the realm to be used. ( Required, Default: amplication-sample-realm )

  • clientID: The ID of the client to be used. ( Required, Default: amplication-server )

  • realmName: The name of the realm to be used. ( Optional, Default: Amplication Sample Realm )

  • clientName: The name of the client to be used. ( Optional, Default: Amplication Server )

  • clientDescription: The description of the client to be used. ( Optional, Default: Sample client for Amplication Serverr )

  • adminUsername: The username of the admin user to be created. ( Optional, Default: admin )

  • adminPassword: The password of the admin user to be created. ( Optional, Default: admin )

  • recipe: The type of Authentication recipe to be used.

    • emailFieldName: The name of the field to use for finding the user by email. If not provided, email field from payloadMapping will be used or a field of type Email will be used from your auth entity. ( Optional )

    • verifyEmail: Whether to verify the email of the user. ( Optional, Default: false )

    • registrationAllowed: Whether to allow registration of new users. ( Optional, Default: true )

    • payLoadMapping: The mapping of the fields to use for payload. This has to be given in the format of key: value where the key is the name of the field in the auth entity and the value is the name of the field in the payload. Currently supported fields from payload are email, email_verified, name, preferred_username, given_name, family_name, iss, sub, azp, scope, realm_access. ( Optional )

[!TIP] It is recommended not to use iss, sub, azp, scope, realm_access to prevent vulnerabilities. However, if you want to use them for some business logic, you are free to do so.

  • defaultUser: The default user to be created in the database. This has to be given in the format of key: value where the key is the name of the field in the auth entity and the value is the value of the field to be set for the default user. If a field is not provided, it will be set to default value according to the type of the field. For more information, see Default Values

[!WARNING] Although some required fields have default values, hence the plugin can be used without providing them, it is recommended to provide them to prevent any conflicts.

Example

{
  "settings": {
    "port": 8080,
    "realmID": "amplication-sample-realm",
    "clientID": "amplication-server",
    "realmName": "Amplication Sample Realm",
    "clientName": "Amplication Server",
    "clientDescription": "Sample client for Amplication Server",
    "adminUsername": "admin",
    "adminPassword": "admin",
    "recipe": {
      "emailFieldName": "email",
      "verifyEmail": false,
      "registrationAllowed": true,
      "payLoadMapping": {
        "username": "name",
        "name": "name"
      }
    },
    "defaultUser": {
      "username": "Ashish Padhy",
      "roles": ["admin"],
      "name": "Ashish Padhy",
      "bio": "",
      "email": "[email protected]",
      "age": 0,
      "birthDate": "2021-06-01T00:00:00.000Z",
      "score": 0,
      "interests": [],
      "priority": "high",
      "isCurious": false,
      "location": "(32.085300, 34.781769)",
      "extendedProperties": {
        "foo": "bar"
      }
    }
  }
}

Scripts

build

Running npm run build will bundle your plugin with Webpack for production.

dev

Running npm run dev will watch your plugin's source code and automatically bundle it with every change.

test

Running npm run test will run the tests for your plugin.

format:write

Running npm run format:write will format your plugin's code with Prettier.

Usage

The plugin works by adding new users to the database when they are authenticated by Keycloak. The plugin also adds the required environment variables in the .env file. In addition to this it adds the following files in the app:

Server

  • src/auth/jwt/base/jwtStrategy.base.ts: The base JWT strategy class which can be extended to create a custom JWT strategy.

  • src/auth/jwt/base/types.ts: The types used by the base JWT strategy class.

  • src/auth/jwt/jwtStrategy.ts: The JWT strategy class which is used by the app.

  • src/auth/jwt/jwtAuth.guard.ts: The JWT authentication guard which is used by the app.

  • src/auth/defaultAuth.guard.ts: The default authentication guard which is used by the app.

  • src/auth/auth.module.ts: The auth module which is used by the app.

  • src/auth/auth.resolver.ts: The auth resolver which is used by the app. It contains the ENTITY_INFO query which is used by the app to get the information about the auth entity.

Client

  • src/auth-provider/ra-auth-keycloak.ts: The auth provider which is used by the react-admin as adapter. It contains the logic for authentication and authorization from Keycloak.

  • src/data-provider/graphqlDataProvider.ts: The data provider which is used by the react-admin as adapter. It contains the logic for making the GraphQL requests to the server.

Config

  • src/keycloak/realm-export.json: The realm export file which is used by the Keycloak server to import the realm.

  • Docker compose files for ease in running the Keycloak server.