@amplication/plugin-auth-keycloak

@amplication/plugin-auth-keycloak

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

Table of Contents

1. Purpose
2. Working with the plugin
3. Scripts
4. Usage

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": "[e-mail]",
      "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.