Skip to main content
Version: v0.15

Local Authentication

The Authentication module offers a local email address based authentication strategy available for users to register with right out of the box.
Making use of it does not require any administrative intervention other than simply bringing up the Authentication module.

In this tutorial, we'll be utilizing Conduit's REST API to create and authenticate our users.

JWT functionality​

The Authentication module also provides a JWT authentication strategy that can be used to authenticate users with a JWT token. This is useful for applications that have a separate authentication service that generates JWT tokens for users. The Authentication module can then be used to verify the JWT token and retrieve the user's information.

User Creation​

Request
curl --location --request POST 'http://localhost:3000/authentication/local' \
     --header 'Content-Type: application/json' \
     --data-raw '{
     "email": "example@mail.com",
     "password": "I_h4t3_p4ss_r3qu1r3m3nts"
     } '
Response
{
  "userId": "6242f1bb10a09901827738fe",
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjYyNDJmMWJiMTBhMDk5MDE4Mjc3MzhmZSIsImlhdCI6MTY0ODU1NDUyNywiZXhwIjoxNzM0OTU0NTI3fQ.Fjqa7ORBBF2giwG7OgiWr2HMgHDL7R6ddFq2E730Djc",
  "refreshToken": "BsKhe3ARhL/FfDfK1REphKkkqQaxRCj/LvvRHOg5wCXCBaUSOwafRHyFYIttaORY/NmHS7NAuT6+knBQegVOwQ=="
}

User Authentication​

Having created our first user, it's time to d-d-d-d d-d-d-d-d-d-duel generate an authentication token.
Send a POST request to /authentication/local, passing in your user credentials.

Request
curl --location --request POST 'http://localhost:3000/authentication/local' \
     --header 'Content-Type: application/json' \
     --data-raw '{
     "email": "example@mail.com",
     "password": "I_h4t3_p4ss_r3qu1r3m3nts"
     }'
Response
{
  "userId": "6242f1bb10a09901827738fe",
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjYyNDJmMWJiMTBhMDk5MDE4Mjc3MzhmZSIsImlhdCI6MTY0ODU1NDUyNywiZXhwIjoxNzM0OTU0NTI3fQ.Fjqa7ORBBF2giwG7OgiWr2HMgHDL7R6ddFq2E730Djc",
  "refreshToken": "BsKhe3ARhL/FfDfK1REphKkkqQaxRCj/LvvRHOg5wCXCBaUSOwafRHyFYIttaORY/NmHS7NAuT6+knBQegVOwQ=="
}

Nice, we got more of these weird sequences of seemingly random characters.

In order for your users to perform user authenticated application requests you'll need to pass their accessToken as an authorization header.

Now, what about that refreshToken then? User access tokens are only valid for a fairly short amount of time. Refresh tokens take longer to expire, therefore you may conveniently generate new authentication tokens without storing sensitive user credentials in your end-user applications.

caution

While Router's security client validation feature is enabled, tokens are tied to the security client they were generated with. Meaning you can't reuse or refresh tokens across different clients.

Requesting a token refresh invalidates your existing access and refresh tokens, returning you a new pair to be used in subsequent requests. Let's finish off with an example on how to do just that.

Request
curl --location --request POST 'http://localhost:3000/authentication/renew'
Response
{
  "accessToken": "eyxhbGmZSIsImlhdCI6MTYciOiJIUzI3Mzh0OXVCJ9.RBBF2giwG7OgiWr2HMgHDLMjcR6ddFq2E730Djce71NiIsInR5cCI6IkpMDkmMWJiMTBhDU1NDUyNywiZXhwIjoxNzM0OTU0NTI3fQ.5MDE4yJpZCI6IjYyNDJFjqa7O",
  "refreshToken": "xEuQegVOwQ==KhREphKkkqQaxRCj/LvvRe3ARhL/yFYIttaORY/NmHSFfDfK1HOg5wCXCBaUSOwafRH7NAuT6+k"
}

A number of endpoints are also available to users to manage their account.

Resend Verification​

Resend Verification Request
# Used to resend email verification after new user is created.

curl --location --request POST 'http://localhost:3000/authentication/local/resent-verification' \
     --header 'Content-Type: application/json' \
     --header 'Accept: application/json' \
     --data-raw '{
       "email": "example@mail.com"
     }'

Forgot Password​

Forgot Password Request
# Generates a password reset token and forwards a verification link to the user's email address.

curl --location --request POST 'http://localhost:3000/authentication/forgot-password' \
     --header 'Content-Type: application/json' \
     --header 'Accept: application/json' \
     --data-raw '{
       "email": "example@mail.com"
     }'

Reset Password​

Reset Password Request

# Used after the user clicks on the 'forgot password' link and
# requires the token from the url and the new password.
# New password must not be the same as the old password.

curl --location --request POST 'http://localhost:3000/authentication/reset-password' \
     --header 'Content-Type: application/json' \
     --header 'Accept: application/json' \
     --data-raw '{
       "passwordResetToken": "passwordResetToken",
       "password": "pass"
     }'

Change Password​

Change Password Request

# Changes the user's password but requires the old password first.
# If 2FA is enabled then a message will be returned asking for token input.
# Re-login is required to enter sudo mode
# The new password can not be the same as the old password

curl --location --request POST 'http:/localhost:3000/authentication/local/change-password' \
     --header 'Content-Type: application/json' \
     --header 'Accept: application/json' \
     --header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjYzNjNjZGNkMDhkNTU2MDk1NmM4MGQ4OSIsImlhdCI6MTY2OTk4MTIwOSwiZXhwIjoxNjcwMDUzMjA5fQ.sxIQDgJv5zzZo8PV6logbvyLO0WbXgES9EWEtUo_kEg' \
     --data-raw '{
       "oldPassword": "your_old_password",
       "newPassword": "your_new_password"
     }'

Change Email​

Change Email Request

# Sends a verification link to the new email address.
# Changes the user's email (requires sudo access).
# The new email can not be the same as the old email

curl --location --request POST 'http://localhost:3000/authentication/local/change-email' \
     --header 'Content-Type: application/json' \
     --header 'Accept: application/json' \
     --header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjYzNjNjZGNkMDhkNTU2MDk1NmM4MGQ4OSIsImlhdCI6MTY2OTk4MTIwOSwiZXhwIjoxNjcwMDUzMjA5fQ.sxIQDgJv5zzZo8PV6logbvyLO0WbXgES9EWEtUo_kEg' \
     --data-raw '{
       "newEmail": "newEMail@mail.com"
     }'

Verify Email​

Verify Email Request
# A webhook used to verify user email. This bypasses the need for client id/secret.

curl --location --request GET 'http://localhost:3000/hook/authentication/verify-email/:verificationToken'

Verify Change Email​

Verify Change Email Request

# A webhook used to verify an email address change. This bypasses the need for client id/secret.

curl --location --request GET 'http://localhost:3000/hook/authentication/verify-change-email/:verificationToken'

Logout​

Logout Request
# logs out authenticated user and removes cookies

curl --location --request POST 'http://localhost:3000/authentication/logout' \
     --header 'Content-Type: application/json' \
     --header 'Accept: application/json' \
     --header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjYzNjNjZGNkMDhkNTU2MDk1NmM4MGQ4OSIsImlhdCI6MTY2OTk4MTIwOSwiZXhwIjoxNjcwMDUzMjA5fQ.sxIQDgJv5zzZo8PV6logbvyLO0WbXgES9EWEtUo_kEg'
}'