Setting Up Forgot Password

Devii provides a built-in whitelisted get_role_token() function that returns a refresh token to securely handle password resets without exposing sensitive information. This process requires setting up tables and configuring an automated email rule. When a user requests a reset, their email is added to the forgot_password table, triggering the email rule. This rule checks if the email exists in the users table and, if found, generates a temporary refresh token. The token is embedded in a reset link sent via email, allowing the user to securely reset their password. The token expires after a set duration to enhance security. The following steps outline how to set up the necessary tables and configurations.

Step 1: Set Up Tables

1. Create a users Table (If Not Already Existing)

   • If your system does not already have a users table, create one with at least the following columns. Populate it with current users and ensure new users are added:

     type users {
         id: ID!  //Primary Key, which is a users Devii roleid
         email: String! // email of the user 
     }

   • The id should be the roleid from devii and will be the primary key for this table, which is required for authentication.

   • If your system already has a users table, ensure that it includes a column for the Devii role ID (devii_roleid) and populate it with the appropriate values for both existing and new users. This column is required for authentication processes such as forgot password to function correctly. Without it, authentication will not work, as devii_roleid is necessary to verify and enforce user access.

2. Create a user forgot_password Role and Policy Rule

   • Create a forgot_password role (recommended via the portal).

   • Define a policy rule allowing the forgot_password role to select from the users table (best done via the portal).

3. Create table forgot_password

type forgot_password {
    id: ID!  // Needs to be a serial identifier  
    email: String!  // Email inserted by the user  
    createtime: DateTime  // Timestamp when the record is created
}

Step 2: Set Up Emailer

1. Configure Email Type

   • The email type should use the whitelisted function get_role_token(roleid, tenantid, expiration) in the email template, this will create a refresh token for your user to change their password that will only last as long as the specified expiration.
     • The roleid will be retrieved via a query in the email type, the tenantid will need to manually entered and the expiration will need to be manually entered in seconds.
   • this can be completed either in a graphql program or in Devii portal.

This is an example of graphql input:

 {
     "email_type": "forgot_password",
     "options": null,
     "queries": [
       {
         "filter": "email = "{{records['new']['email']}}"",
         "limit": null,
         "offset": null,
         "ordering": null,
         "outvar": "rolequery",
         "query": "query users($filter: String, $ordering: [String], $limit: Int, $offset: Int) { users(filter: $filter, ordering: $ordering, limit: $limit, offset: $offset) { roleid email }}"
       }
     ],
     "recipients": [
       "{{rolequery['email']}}"
     ],
     "sender": "info@projectphoenix.io",
     "subject": "Password reset request for your account.",
     "template": "https://example.com/reset-password?rst={{get_role_token(rolequery['roleid'], $TENANTID, $EXPIRATION)}}"
    }

This is an example of using the portal Email Template

• Replace $TENANTID with your tenant ID.
• Replace $EXPIRATION with the desired token lifetime in seconds (e.g., 900 seconds = 15 minutes).

2. Set Up Email Rule

This rule triggers the forgot password email whenever a new record is added to the forgot_password table.

mutation new_rule($i: email_ruleInput){
create_email_rule(input:$i){
    operations
    targets
    email_type
    query_roleid
    name
  }
}

Variables

{
  "i":{
    "email_type": "forgot_password",
    "name": "forgot_password_rule",
    "operations": [
    "insert"
    ],
    "targets": [
    "forgot_password"
    ],
    "query_roleid": $ROLEID
    }

    }

• Replace $ROLEID the forgot_password role's roleid that you created in step 1.

• The example below is using the 'Email Rule' in portal, what would be the users table is devii_users from my database.

Step 3: Create Event to Trigger Password Reset

When a user initiates a password reset (e.g., by clicking a "Forgot Password" link), their email is inserted into the forgot_password table.

1. This insertion triggers the email rule.
2. The email rule invokes the forgot_password role to query the users table using the inserted email.
3. If a matching email exists, an email is sent with a reset link.
4. If no match is found, the email process fails.

Step 4: Handle Token Authentication via Reset Link

When the user clicks the password reset link in their email, the client application must extract the refresh token (rst) and use it to obtain an access token before proceeding with the password reset.

1. Extract the refresh token

• The reset link in the email is structured as:

  https://example.com/reset-password?rst={{get_role_token(rolequery['roleid'], $TENANTID, $EXPIRATION)}}

• The client extracts the rst parameter from the URL.

2. Exchange the refresh token for an access token

• The client calls the authentication endpoint to obtain an access token, you can see an example of this in the create auth module in the tutorial.

3. Authenticate the session

• The client stores the access token in memory or local storage as needed.
• The user is now considered logged in.

4. Trigger the password reset flow

• Once authenticated, the client automatically displays the password reset form.
• The user enters and confirms their new password.
• The client submits the password change request using the authenticated session.

This ensures a secure and seamless password reset process where the user is authenticated before resetting their password.