@amplication/plugin-auth-keycloak
v0.0.11
Published
Keycloak Authentication plugin for Amplication
Downloads
152,192
Keywords
Readme
@amplication/plugin-auth-keycloak
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 typeEmail
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 ofkey: 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 areemail
,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 ofkey: 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.