Skip to main content

Authentication

General​

Services generated by Amplication contain authentication mechanisms based on the NestJS/Passport library.

Authentication Plugins​

Use plugins to support your choice of authentication method.

note

The auth plugins are installed by default when a new service is created.

NestJS Auth Module (mandatory)​

The NestJS Auth Module plugin provides all the basic modules required for authentication of the service. Installation of this plugin is mandatory for the service to be authenticated, and must be installed together with the JWT Auth Provider plugin or the Basic Auth Provider plugin.

JWT Auth Provider​

Passport based JWT authentication involves the client sending a request to the server with a user's credentials in the form of a username and password. The server then authenticates the user and issues a JWT if the credentials are valid. This allows the client to authenticate subsequent requests to the server using the JWT. Read more about authentication here.

tip

We recommend using JWT as a more secure alternative to Basic authentication.

Basic Auth Provider​

Basic authentication is a simple authentication scheme built into the HTTP protocol that involves sending a request to a server with a user's credentials in the form of a username and password. The credentials are encoded in base64 and included in the Authorization header of the request.

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​

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 (example)​

 Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJkYXRhIjoieW91IGFyZSBzb29vb28gY29vbCB0aGF0IHlvdSBjaGVjayB0aGF0ISIsIm5hbWUiOiJPZmVrIGdhYmF5IDspIiwiaWF0IjoxNTE2MjM5MDIyfQ.vaYJaP9SUlOU0u4NfFCRm5tmBVDKeCwvN6ByCkqJt8U

Basic Authentication​

When using Basic HTTP authentication, when 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".

For example:

Authorization: Basic YWRtaW46YWRtaW4=

By default, your app comes with one user with the username "admin" and password "admin".

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/

Read here to find out more: HTTP authentication.

Uninstalling auth plugins after pushing to GitHub​

Currently, the auth plugins are installed by default when a new service is created.

If you choose to uninstall auth plugins after pushing it to GitHub, the changes may not be reflected in the customizable files (files that are not in the base folder), and you will receive the following compilation errors:

You need to fix it manually, as follows:

  • Remove imports from files that do not exist, for example: ../auth/gqlDefaultAuth.guard
  • Remove the rolesBuilder from the super() in the constructor (in each entity controller/resolver).

Custom Authentication with Passport​

You can further develop the code generated by Amplication to rollout your own authentication system.

Amplication uses the @nestjs/passport module as middleware to support authentication. Passport is a popular node.js authentication library, widely used by the community.

Passport supports many authentication strategies available as npm modules, which you can implement in your generated project. You can easily integrate the library with a Nest application using the @nestjs/passport module.

Passport has a rich ecosystem of strategies that implement various authentication mechanisms.

Creating a Service Without Authentication​

Amplication enables you to set up a service in the generated app that can run without authentication and authorization.

This is useful for a public-facing service that does not handle sensitive or personal information and you wish to enable access to anyone without the need for a login or password. Typical use cases include displaying public information, such as a public event or a weather forecast, and returning search results from a public database.

Alternatively, this might be useful when you need background services that don't expose endpoints to end users. The service may be part of a larger system where authentication is handled at a different level, such as a gateway or reverse proxy. Typical use cases include where an organization’s internal services communicate with each other, and public facing APIs that do not require authentication.

To create a service without authentication, do not install the authentication plugins.