////
Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements.  See the NOTICE file
distributed with this work for additional information
regarding copyright ownership.  The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License.  You may obtain a copy of the License at

https://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied.  See the License for the
specific language governing permissions and limitations
under the License.
////

[[ui-forgotPassword]]
== Forgot Password

Like the Registration workflow, the Forgot Password workflow is expected to be user-facing. So it's not available in the admin menu like the User, Role, and other backend functionality - you'll need to expose them to your users.

One way to do this is to replace the default `login.gsp` that's provided by the Spring Security Core plugin with this plugin's version. You can do this by running `grails s2ui-override auth` - see the section on <<ui-customization>> for more details. If you do this your users will have links to both workflows from the login screen:

image::login.png[]

=== Forgot Password

Navigate to `/register/forgotPassword`:

image::forgot_password_start.png[]

The default is to have e-mail validation for forgetting a password.  This is now configurable which will be explained below.

After entering a valid username an email will be sent and you'll see a success screen:

image::forgot_password_sent.png[]

Click on the link in the email:

image::forgot_password_email.png[]

and you'll open the reset password form:

image::forgot_password_form.png[]

After entering a valid password you'll finalize the process, which involves storing the new password hashed in the user table and pre-authenticating, then redirecting to the configured destination:

image::forgot_password_final.png[]

=== Configuration

The post-reset destination url is configurable in `grails-app/conf/application.groovy` using the `postResetUrl` attribute:

[source,groovy]
----
grails.plugin.springsecurity.ui.forgotPassword.postResetUrl = '/reset'
----
If you don't specify a value then the `defaultTargetUrl` value will be used, which is `'/'` by default.

=== Email Validation Configuration

You can customize if you want to have the user get e-mails for validation before they can reset their password.  To turn off
e-mail validation set the parameter `requireForgotPassEmailValidation` to false.  If not set it will default to true.  This
can be set in `grails-app/conf/application.groovy` or `grails-app/conf/application.yml` under
[source,groovy]
----
grails.plugin.springsecurity.ui.forgotPassword.requireForgotPassEmailValidation = false
----
**If e-mail validation is turned off, it is recommended to use the forgotPasswordExtraValidation below.**


=== Challenge Questions Configuration

It is recommended the provided script named `s2ui-create-challenge-questions` be used to generate challenge questions.



All the answers will be encrypted and it will use the same encryption settings as the what is used to store the password
for each user.  The service to handle this listener is automatically created and configured when
you use the plugin.

The option to add challenge questions can be turned on will work independent of e-mail validation.  If the e-mail validation is turned on this step will occur before the e-mail is sent out.

To make this work, the domain object must have a link to your User Object. This is done by setting the `validationUserLookUpProperty` which defaults to 'user'.

This can be customized in either `grails-app/conf/application.groovy` or `grails-app/conf/application.yml`
[source,groovy]
----
grails.plugin.springsecurity.ui.forgotPassword.validationUserLookUpProperty = 'user'
----

Each list item in the `forgotPasswordExtraValidation` has three options, though each should only have two.  If you have both
`labelDomain` and `labelMessage` then `labelDomain` will be used as it takes precedences.

.forgotPasswordExtraValidation List items
|===
|Header 1 |Header 2

|labelDomain
|This is the property in the domain object that will used to ask the question

|labelMessage
|If labelDomain is not present then this can be used as a message property to ask a question (ie if your questions are static).

|prop
|This is used as the property of the domain object to determine if the answer is correct.
|===


This can be customized in either `grails-app/conf/application.groovy` or `grails-app/conf/application.yml`

[source,groovy]
.grails-app/conf/application.yml
----
grails:
  plugin:
    springsecurity:
     ui:
      forgotPassword:
         forgotPasswordExtraValidation:
            -
               labelDomain: myQuestion
               prop: myAnswer
            -
               labelMessage: securityvalidations.labelMessage.label1
               prop: myAnswer2
----

If the above is configured you will see a menu item to List and Create Challenge questions for each
user.


To use the challenge questions functionality please set the domain class which will hold the answers with the
`forgotPasswordExtraValidationDomainClassName` property.  This is Domain object that contains any reference that is needed by prop (question) and labelDomain (answer).

----
grails:
  plugin:
    springsecurity:
     ui:
      forgotPassword:
          forgotPasswordExtraValidationDomainClassName: com.mycompany.Profile
----


=== Mail configuration

By default the plugin uses the https://github.com/gpc/grails-mail[Mail] plugin to send emails, but only if it is installed. This is configurable by registering your own `MailStrategy` implementation - see the section on <<ui-customization>> for more information. The plugin assumes that the Mail plugin and an SMTP server are already configured.


You can customize the subject, body, and from address of the reset email by overriding the default values in `grails-app/conf/application.groovy`, for example:

[source,groovy]
----
grails.plugin.springsecurity.ui.forgotPassword.emailBody = '...'
grails.plugin.springsecurity.ui.forgotPassword.emailFrom = '...'
grails.plugin.springsecurity.ui.forgotPassword.emailSubject = '...'
----

The `emailBody` property should be a GString and will have the User domain class instance in scope in the `user` variable, and the generated url to click to reset the password in the `url` variable.

=== Notes

Like the registration code, consider this workflow as starter code. Run `grails s2ui-override register` to copy the registration controller and GSPs into your application to be customized.

[NOTE]
====
`RegisterController` and its GSPs assume that your User domain class has an `email` field.
====
