Skip to main content

Authentication Plugin Guide

Authentication and authorization are crucial components of your Amplication service. This guide will help you implement secure user authentication using Amplication's authentication plugins.

Enable Authentication​

Make sure you have an Authentication Entity set up. Next, follow these steps to add authentication:

  1. Navigate to your service's Plugins page.
  2. Go to the "Authentication" category in the left sidebar.
  3. Ensure you install the "NestJS Auth Module" plugin first.
  4. Choose and add an Auth Provider plugin that suits your needs (e.g., Auth0, Supertokens, etc.).
note

By default, Node.js services are created with a user with the credentials username: admin and password: admin.

After adding the required Authentication plugins, configure your authentication settings in the plugin options page.

Disable Authentication​

If you no longer need authentication on a specific service, you can disable it.

  1. Visit your service's Plugins page and toggle the Authentication-related plugins into the off state.
  2. Delete the Authentication Entity from your list of entities.
  3. Re-build your project and commit your changes to your preferred git provider.

Authentication Providers​

Amplication supports multiple authentication providers to suit different needs:

  1. JWT Auth Provider
  2. Auth0 Auth Provider
  3. Supertokens Auth Provider
  4. SAML Auth Provider
  5. Basic Auth Provider
  6. KeyCloak Auth Provider
  7. ASP.NET Core Identity

JWT Auth Provider​

  • Adds JSON Web Token (JWT) authentication and authorization to your service.
  • Must be installed with the "NestJS Auth Module" plugin.
  • For detailed configuration, visit the JWT Auth Provider GitHub README.

Auth0 Auth Provider​

  • Integrates Auth0 authentication and authorization into your service.
  • Requires an Auth0 account and configuration of an Auth0 application.
  • For setup instructions and configuration options, check the Auth0 Auth Provider GitHub README.

Supertokens Auth Provider​

  • Adds Supertokens authentication to your service.
  • Supports various authentication recipes (e.g., email-password, passwordless, third-party).
  • Requires setup of the Supertokens core service.
  • For detailed configuration and usage, refer to the Supertokens Auth Provider GitHub README.

SAML Auth Provider​

  • Enables SAML authentication on your service.
  • Uses Passport SAML strategy and generates JWT tokens for authorization.
  • For usage details, check the SAML Auth Provider GitHub README.

Basic Auth Provider​

  • Enables a straightforward authentication scheme built into the HTTP protocol.
  • Requires sending user's credentials in the form of a username and password, encoded in base64, included in the Authorization header of the request.
note

If you use the Basic Auth Provider plugin, your service comes with one user with the username admin and the password admin by default.

KeyCloak Auth Provider​

  • Integrates KeyCloak authentication and authorization into your service.
  • Provides single sign-on (SSO) capabilities and support for various identity protocols.
  • Requires setup of a KeyCloak server and configuration of a KeyCloak realm.
  • For detailed setup instructions and configuration options, refer to the KeyCloak Auth Provider GitHub README.

ASP.NET Core Identity​

If you're using a .NET service, refer to the .NET Auth Core Identity plugin documentation for setup and usage instructions.

Plugin Configuration Settings​

You can customize your authentication settings, including the default username and password, in the authentication plugin's options page.

Let's look at detailed configuration settings for some of the available authentication plugins:

ASP.NET Core Identity​

This plugin adds authentication and authorization to your .NET services.

Configuration​

{
  "seedUserEmail":"test@email.com",
  "seedUserPassword":"P@ssw0rd!"
}
  • seedUserEmail: The email address for the default seed user created when initializing the service (default: "test@email.com")
  • seedUserPassword: The password for the default seed user created when initializing the service (default: "P@ssw0rd!")

JWT Auth Provider​

The JWT Auth Provider adds JSON Web Token (JWT) authentication and authorization to your service.

Configuration​

{
  "settings": {
    "tokenExpiresIn": 3600,
    "refreshTokenExpiresIn": 604800,
    "grantType": "PASSWORD",
    "jwtSecretKey": "Change_ME!!!"
  }
}
  • tokenExpiresIn: Expiration time of the access token in seconds (default: 3600)
  • refreshTokenExpiresIn: Expiration time of the refresh token in seconds (default: 604800)
  • grantType: The grant type for token generation (default: "PASSWORD")
  • jwtSecretKey: Secret key for JWT signing (default: "Change_ME!!!")

For detailed configuration, visit the JWT Auth Provider GitHub README.

Auth0 Auth Provider​

The Auth0 Auth Provider integrates Auth0 authentication and authorization into your service.

Configuration​

{
  "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"
    }
  }
}
  • useManagementApi: Set to true to use the Auth0 Management API
  • managementParams: Configuration for the Management API
    • identifier: The identifier of the Auth0 Management API
    • accessToken: The access token of the Auth0 Management API
    • actionName: The name of the action to create in Auth0
    • clientName: The name of the client to create in Auth0
    • apiName: The name of the API to create in Auth0
    • audience: The audience/identifier of the API

For setup instructions and configuration options, check the Auth0 Auth Provider GitHub README.

Supertokens Auth Provider​

The Supertokens Auth Provider adds Supertokens authentication to your service, supporting various authentication recipes.

Configuration​

{
  "settings": {
    "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": "email-password"
    }
  }
}
  • apiDomain: The API domain for Supertokens
  • appName: The name of your application
  • websiteDomain: The website domain for Supertokens
  • websiteBasePath: The base path for authentication on the website
  • apiBasePath: The base path for authentication API endpoints
  • connectionUri: The URI for connecting to the Supertokens core
  • supertokensIdFieldName: The field name to store the Supertokens user ID
  • recipe: The authentication recipe to use (e.g., "emailpassword", "passwordless", "thirdparty")

For detailed configuration and usage, refer to the Supertokens Auth Provider GitHub README.

Keycloak Auth Provider​

The Keycloak Auth Provider integrates Keycloak authentication and authorization into your service.

Configuration​

{
  "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"
      }
    }
  }
}
  • port: The port on which to run the Keycloak server
  • realmID: The ID of the Keycloak realm to use
  • clientID: The ID of the Keycloak client to use
  • realmName: The name of the Keycloak realm
  • clientName: The name of the Keycloak client
  • adminUsername: The username for the Keycloak admin user
  • adminPassword: The password for the Keycloak admin user
  • recipe: Configuration for the authentication recipe

For detailed setup instructions and configuration options, refer to the Keycloak Auth Provider GitHub README.

Basic Auth Provider​

{
  "username":"admin",
  "password":"admin"
}
  • username: The username for the default seed user created when initializing the service.
  • seedUserPassword: The password for the default seed user created when initializing the service.

Examples​

This section provides you with in-depth examples on how to use and interact with some of the available authentication plugins.

JWT Authentication​

When generating an app with JWT authentication, the process includes the following two steps:

  1. Send a login request to the server with username and password to get back from the server the JWT token.
  2. Add an authentication header with the JWT token to every consecutive request.

Following are examples of how to log in with REST API and GraphQL API.

Rest API​

Rest API Curl Request Example
curl -X 'POST' \
  'https://[server-url]/api/login' \
  -H 'accept: */*' \
  -H 'Content-Type: application/json' \
  -d '{
  "username": "admin",
  "password": "admin"
}'

Swagger playground for login endpoint.

GraphQL API​

mutation {
  login(credentials: { username: "admin", password: "admin" }) {
    accessToken
  }
}

Header with JWT Included​

JWT Authorization Header Example
 Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJkYXRhIjoieW91IGFyZSBzb29vb28gY29vbCB0aGF0IHlvdSBjaGVjayB0aGF0ISIsIm5hbWUiOiJPZmVrIGdhYmF5IDspIiwiaWF0IjoxNTE2MjM5MDIyfQ.vaYJaP9SUlOU0u4NfFCRm5tmBVDKeCwvN6ByCkqJt8U

Basic Authentication​

When using Basic HTTP authentication and sending a request to the API you must provide a Basic HTTP authentication header with the format:

Authorization: 'type' 'credentials'

where type is Basic and credentials is the Base64 encoding of a string "username:password".

Basic Authentication Example
Authorization: Basic YWRtaW46YWRtaW4=
tip

You can use a tool to create the header. There are several generators available, such as https://www.blitter.se/utils/basic-authentication-header-generator/

Next Steps​

After you've successfully added authentication to your service, you can do the following:

  1. Add authenticated users to your system.
  2. Set up roles and permissions for authorization.