@amplication/plugin-auth-auth0
v1.0.16
Published
Auth0 plugin for Amplication
Downloads
230,238
Keywords
Readme
@amplication/plugin-auth-auth0
This plugin helps in integrating Auth0 into your app generated by Amplication and provides the required configuration files.
Purpose
Provides a way to integrate Auth0 into your app generated by Amplication by adding the required dependencies and configuration files. Auth0 is an authentication and authorization platform that provides the required tools to secure your 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 the method you want to use as well as the general settings.
Note: Have to add the auth-core-plugin plugin before adding this plugin.
Results in configuring the app to use auth0 for authentication. It adds the necessary dependencies, creates a JWT strategy and adds the required environment variables in the .env
file.
General Configuration
The following values are required to be provided in the plugin settings.
recipe
: The type of Authenticated recipe to use.type
:password
orpasswordless
( Optional, Default:password
)method
:email
orsms
ormagic-link
( Optional, Default:email
)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 )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
,nickname
,picture
,username
. ( Optional )
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
Example
{
"settings": {
"recipe": {
"type": "password",
"emailFieldName": "email",
"payloadFieldMapping": {
"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"
}
}
// Method specific settings ( See Method Specific Configuration )
}
}
Using Management API
This method uses the Auth0 Management API to get the required values.
Note: This method requires the user to have an auth0 account or have access to JWT token of the auth0 account.
Method Specific Configuration
This method requires the following values to be provided in the plugin settings.
useManagementApi
:true
( To use this method )managementParams
:identifier
: The identifier of the Auth0 Management API ( See get management api token )accessToken
: The access token of the Auth0 Management API ( See get management api token )actionName
: The name of the action which you want to create in the Auth0 account. ( Optional, Default:Add user details to access token
)clientName
: The name of the client which you want to create in the Auth0 account. ( Optional, Default:Amplication SPA
)apiName
: The name of the API which you want to create in the Auth0 account. ( Optional, Default:Amplication API
)audience
: The audience/identifier of the API which you want to create in the Auth0 account. ( Optional, Default:http://localhost:3001
)
Example
{
"settings": {
"useManagementApi": true,
"managementParams": {
"identifier": "https://{TENANT_NAME}.{REGION}.auth0.com/api/v2/",
"accessToken": "{ACCESS_TOKEN}",
"actionName": "Add user details to access token",
"clientName": "Custom SPA",
"apiName": "Custom API",
"audience": "http://example.com"
}
// General settings ( See General Configuration )
}
}
Manually
This method requires the user to manually create the required values in the Auth0 account and provide the values in the plugin settings.
Method Specific Configuration
This method requires the following values to be provided in the plugin settings.
useManagementApi
:false
( To use this method )domain
: The domain of the Auth0 application (client) ( See copy domain )clientID
: The client id of the Auth0 application (client) ( See copy client id )audience
: The audience/identifier of the API which you have created in the Auth0 account. ( See copy audience )issuerURL
: The issuer base url of the API which you have created in the Auth0 account. ( See copy issuer base url )
Example
{
"settings": {
"useManagementApi": false,
"domain": "dev-p27ryta7rrcalcea.us.auth0.com",
"clientID": "A9Dvb0BS8His5lrzRNduNxtGcoTHagid",
"audience": "https://sample-nest.demo.com",
"issuerURL": "https://dev-p27ryta7rrcalcea.us.auth0.com/"
// General settings ( See General Configuration )
}
}
Elaboration
This section elaborates on the steps to be followed to get the required values for the plugin settings. Prerequisite for this is to have an Auth0 account.
Get Management API Token
Go to Management Explorer and copy the token as shown there. If there is no token, click on the
Create Testing Application
button and create a testing application. Then copy the token. This is the value of theaccessToken
field in the plugin settings.Go to Management Settings Page and copy the value of the
Identifier
field. This is the value of theidentifier
field in the plugin settings.
Create an Auth0 application
Go to Applications Page and create a new application of type
Single Page Web Applications
.Select React in the Quickstart tab or follow the steps below.
Change the following values to their keys :-
- Allowed Callback URLs : http://localhost:3001/auth-callback
- Allowed Logout URLs : http://localhost:3001/login
- Allowed Web Origins : http://localhost:3001
Go to the settings tab and copy the values of the following :-
- Domain
- Client ID
Create an Auth0 API
Go to the API Dashboard and create a new API with the following values :-
- Identifier : http://localhost:3001
- Signing Algorithm : RS256
Go to the quickstart tab and switch to NodeJS tab and copy the values of the following :-
- Audience
- IssuerBaseURL
Sample Auth0 API Settings
const jwtCheck = auth({ audience: "http://localhost:3001", issuerBaseURL: "https://dev-z4opqj3d1oykaaaw.us.auth0.com/", tokenSigningAlg: "RS256", });
Create an Auth0 action
Go to the Actions Library and click on the Build Custom button.
Set the following values :-
- Name : Add user details to access token ( Or any name you want )
- Trigger : Login / Post Login
- Runtime : Node18 ( Or any runtime you want )
Click Create Button.
In the code editor, set the following code :-
exports.onExecutePostLogin = async (event, api) => { if (event.authorization) { // Set claims api.accessToken.setCustomClaim("user", event.user); } };
Save and click on the Deploy button.
Go to the Actions Flows and the action you have created between Start and Complete nodes. For more information, see Auth0 Actions.