Product
Introducing SSO
Streamline your login process and enhance security by enabling Single Sign-On (SSO) on the Socket platform, now available for all customers on the Enterprise plan, supporting 20+ identity providers.
@amplication/plugin-auth-supertokens
Advanced tools
Use supertokens for authentication in the service generated by Amplication
Readme
Use supertokens for authentication in the service generated by Amplication.
This plugin adds the required code to use supertokens for authentication in the service generated by Amplication.
Supertokens is an open source Auth0 alternative. It provides 3 components that need to be setup: the frontend SDK, the backend SDK, and the SuperTokens core service. For more information on these, you can check the supertokens docs (https://supertokens.com/docs/emailpassword/introduction#architecture).
Authentication methods are setup with the use of recipes.
This plugin generates code for the email password recipe that allows users to be authenticated with their emails and passwords, the passwordless recipe that allows users to be authenticated with only their phone numbers or emails, the third party recipe that allows users to be authenticated using third party providers like Google, phone password recipe that allows users to be authenticated using their phone number and passwords and combinations of third party with other recipes that SuperTokens provides guides for on their guides page: https://supertokens.com/docs/guides.
It updates the following parts:
package.json
, both for the server and the admin UI..env
, both for the server and the admin UI.auth
directory.connectMicroservices.ts
file.Amplication uses roles for authorization. The generated code integrates with this and only uses SuperTokens for authentication.
You will also need to setup the SuperTokens core which is what handles the storage of user data. You can follow this guide: https://supertokens.com/docs/emailpassword/nestjs/guide#10-setup-the-supertokens-core to set it up.
The settings for this plugin looks like this:
export interface Settings {
apiDomain: string;
appName: string;
websiteDomain: string;
websiteBasePath: string;
apiBasePath: string;
connectionUri: string;
apiGatewayPath: string;
apiKey: string;
supertokensIdFieldName: string;
recipe: {
/* Recipe Settings */
};
}
The apiDomain
specified will become the SUPERTOKENS_API_DOMAIN
environment variable in the server's
.env file and REACT_APP_SUPERTOKENS_API_DOMAIN
in the admin UI's .env file. This will be used as the
apiDomain
value in the SuperTokens appInfo configuration.
The appName
specified will become the SUPERTOKENS_APP_NAME
environment variable in the server's .env
file and the REACT_APP_SUPERTOKENS_APP_NAME
in the admin UI's .env file. This will be used as the
appName
value in the SuperTokens appInfo configuration.
The websiteDomain
specified will become the SUPERTOKENS_WEBSITE_DOMAIN
environment variable in the
server's .env file and the REACT_APP_SUPERTOKENS_WEBSITE_DOMAIN
environment variable in the admin UI's .env
file. The will be used as the websiteDomain
value in the SuperTokens appInfo configuration.
The websiteBasePath
specified will become the SUPERTOKENS_WEBSITE_BASE_PATH
environment variable in the
server's .env file. This will be used as the websiteBasePath
value in the server SuperTokens appInfo
configuration.
The apiBasePath
specified will become the SUPERTOKENS_API_BASE_PATH
environment variable in the server's
.env file and the REACT_APP_SUPERTOKENS_API_BASE_PATH
in the admin UI's .env file. This will be used as the
apiBasePath
value in the SuperTokens appInfo configuration.
The connectionUri
specified will become the SUPERTOKENS_CONNECTION_URI
environment variable in the
server's .env file. This will be used as the connectionUri
value in the server's SuperTokens
configuration.
The apiGatewayPath
specified will become the SUPERTOKENS_API_GATEWAY_PATH
environment variable in the
server's .env file. This will be used as the apiGatewatPath
value in the server's appInfo SuperTokens
configuration.
The apiKey
specified will become the SUPERTOKENS_API_KEY
environment variable in the server's .env file.
This will be used as the apiKey
value in the server's SuperTokens configuration.
The supertokensIdFieldName
is the name of the field that will hold a user's SuperTokens ID in the auth entity. An error will be thrown if the field does not exist on the auth entity.
The recipe
setting is an object whose properties depend on which authentication recipe code is being
generated for. It always has a name
property which indicates the name of the authentication method
being used.
For more info about the SuperTokens appInfo settings: https://supertokens.com/docs/emailpassword/appinfo
For the email password recipe, the recipe setting is like:
type Recipe = {
name: "emailpassword",
};
The passwordless recipe setting:
type Recipe = {
name: "passwordless",
flowType: "USER_INPUT_CODE_AND_MAGIC_LINK" | "USER_INPUT_CODE" | "MAGIC_LINK",
contactMethod: "EMAIL" | "PHONE" | "EMAIL_OR_PHONE",
};
The flowType
and contactMethod
settings are used to configure SuperTokens. They are also used to determine
which code should be added in the admin UI's login page.
The thirdparty recipe setting:
type Recipe = {
name: "thirdparty",
google?: {
clientId: string,
clientSecret?: string,
additionalConfig?: { [key: string]: string },
},
github?: {
clientId: string,
clientSecret?: string,
additionalConfig?: { [key: string]: string },
},
apple?: {
clientId: string,
clientSecret?: string,
additionalConfig?: { [key: string]: string },
},
twitter?: {
clientId: string,
clientSecret?: string,
additionalConfig?: { [key: string]: string },
},
};
The client ID, client secret and/or additional configurations specified for each desired third party provider will be used to configure SuperTokens and to generate code for the admin UI's login page.
The settings for the thirdpartyemailpassword is identical to that of the thirdparty settings. Code to store emails and passwords in the local database is only generated for the emailpassword recipe.
The settings for this is a combination of the passwordless and the thirdparty recipe settings.
The flowType
, contactMethod
and third party provider settings have to be set.
This recipe doesn't require any additional configuration.
If no configuration is provided the .amplicationrc.json file will use be used as the default values.
{
"apiDomain": "http://localhost:3000",
"appName": "Amplication App",
"websiteDomain": "http://localhost:3001",
"websiteBasePath": "/auth",
"apiBasePath": "/api/auth",
"connectionUri": "https://try.supertokens.com",
"apiGatewayPath": "",
"apiKey": "",
"supertokensIdFieldName": "supertokensId",
"recipe": {
"name": "emailpassword"
}
}
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 plugin's test suite.
The auth-core plugin must be installed for this plugin to work.
To configure supertokens, set the following environment variables in the server's .env file
SUPERTOKENS_CONNECTION_URI - The url link to the supertokens core.
SUPERTOKENS_APP_NAME - The name of the app.
SUPERTOKENS_API_DOMAIN - The API domain.
SUPERTOKENS_WEBSITE_DOMAIN - The website domain.
SUPERTOKENS_API_BASE_PATH - The API server base path for the auth urls.
SUPERTOKENS_WEBSITE_BASE_PATH - The website base path.
SUPERTOKENS_API_KEY - The supertokens API key.
SUPERTOKENS_API_GATEWAY_PATH - The API gateway path.
In the admin UI's .env file,
REACT_APP_SUPERTOKENS_APP_NAME corresponds to the server's SUPERTOKENS_APP_NAME REACT_APP_SUPERTOKENS_API_DOMAIN corresponds to the server's SUPERTOKENS_API_DOMAIN REACT_APP_SUPERTOKENS_WEBSITE_DOMAIN corresponds to the server's SUPERTOKENS_WEBSITE_DOMAIN REACT_APP_SUPERTOKENS_API_BASE_PATH corresponds to the server's SUPERTOKENS_API_BASE_PATH
The generated code creates a new user in the DB upon user creation with the user's SuperTokens ID stored in the supertokensIdFieldName
field.
You have to manually create the corresponding supertokens user on the supertokens core and store the ID in the user's
supertokensId
field.
This plugin generates the code for the initial setup of SuperTokens configuration and some utility functions
that can be used to handle user data stored on the SuperTokens core in the generated
src/auth/supertokens/supertokens.service.ts
.
The signatures of the functions that are generated depend on the selected auth recipe.
For example, when the auth recipe is emailpassword, the generated createSupertokensUser
function
looks like this:
async createSupertokensUser(
email: string,
password: string
): Promise<string> {
/* ... */
}
But for the passwordless recipe, the arguments will accept an email or phone number but no password. This function, along with the other generated functions in the SuperTokens service code can be used to handle user data on the SuperTokens core and should be customized to your specific use case.
Although the generated code uses SuperTokens for authentication, authorization is left to the role-based
mechanism that generated Amplication code already uses. The authorization is done by a generated auth guard
in src/auth/supertokens/auth.guard.ts
.
This auth guard assumes that every user in the DB has an associated and valid SuperTokens user ID stored
in the field supertokensIdFieldName
. In all guarded endpoints, the SuperTokens session is used to retrieve
the SuperTokens user ID, which is then used to find the roles of the corresponding user in the DB.
It's these roles that are used to determine what the user is and isn't allowed to do.
Because of the way authorization works in the generated code, you have to make sure that for every user
stored in the DB, there is a corresponding valid SuperTokens user ID stored in the user's supertokensIdFieldName
.
Exactly how you should do this depends on your specific use case, so the plugin doesn't generate code for this.
So, when a new user is created in the DB (maybe with a POST endpoint), you have to also create a user on the SuperTokens core (you can use the generated SuperTokens service code for this) and store the SuperTokens user ID in the DB.
Code is also generated for the admin UI's authentication. The code generated depends on the specific auth recipe used. For example, if the auth recipe is emailpassword, then the generated admin UI code will have an email and password form in the login page.
The SuperTokens frontend SDK is used for the session creation of a user.
To login a user on the admin UI, you first have to create that user on the SuperTokens core, either through the SuperTokens backend SDK (which the generated SuperTokens service functions use) or through the SuperTokens dashboard (which you can learn more about here: https://supertokens.com/docs/userdashboard/about).
You also have to create the user in the DB and store the SuperTokens ID of the user in the
supertokensIdFieldName
. This is necessary because SuperTokens is used for authentication and the
roles in the DB is then what is used for authorization.
You then use the details of the user to login.
For example, some steps you can follow to do this when using the emailpassword recipe:
createSupertokensUser
with the
supplied email and password.FAQs
Use supertokens for authentication in the service generated by Amplication
The npm package @amplication/plugin-auth-supertokens receives a total of 30,298 weekly downloads. As such, @amplication/plugin-auth-supertokens popularity was classified as popular.
We found that @amplication/plugin-auth-supertokens demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 8 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Product
Streamline your login process and enhance security by enabling Single Sign-On (SSO) on the Socket platform, now available for all customers on the Enterprise plan, supporting 20+ identity providers.
Security News
Tea.xyz, a crypto project aimed at rewarding open source contributions, is once again facing backlash due to an influx of spam packages flooding public package registries.
Security News
As cyber threats become more autonomous, AI-powered defenses are crucial for businesses to stay ahead of attackers who can exploit software vulnerabilities at scale.