# Forgot Username - Password Management

Source: https://apereo.github.io/cas/development/password_management/Password-Management-ForgotUsername.html

CAS provides the ability to retrieve a forgotten username. This behavior is tightly integrated with the password management functionality where each account storage service is allowed to retrieve the user record using a supplied identifier from the user (typically an email address) and supply the username via email notifications, etc.

The following settings and properties are available from the CAS configuration catalog:

- `cas.authn.pm.forgot-username.google-recaptcha.enabled` (Required; type `Boolean`; default `true`): Whether reCAPTCHA should be enabled.
- `cas.authn.pm.forgot-username.google-recaptcha.score` (Required; type `Double`; default `0.5`): Google reCAPTCHA v3 returns a score (1.0 is very likely a good interaction, 0.0 is very likely a bot). reCAPTCHA learns by seeing real traffic on your site. For this reason, scores in a staging environment or soon after implementing may differ from production. As reCAPTCHA v3 doesn't ever interrupt the user flow, you can first run reCAPTCHA without taking action and then decide on thresholds by looking at your traffic in the admin console. By default, you can use a threshold of 0.5.
- `cas.authn.pm.forgot-username.google-recaptcha.secret` (Required; type `String`): The reCAPTCHA site secret.
- `cas.authn.pm.forgot-username.google-recaptcha.site-key` (Required; type `String`): The reCAPTCHA site key.
- `cas.authn.pm.forgot-username.mail.attribute-name` (Required; type `List<String>`): Principal attribute names that indicates the destination email address for this message. The attributes must already be resolved and available to the CAS principal. When multiple attributes are specified, each attribute is then examined against the available CAS principal to locate the email address value, which may result in multiple emails being sent.
- `cas.authn.pm.forgot-username.mail.from` (Required; type `String`): Email from address.
- `cas.authn.pm.forgot-username.mail.subject` (Required; type `String`): Email subject line. The subject can either be defined verbatim, or it may point to a message key in the language bundle using the syntax `#{subject-language-key}`. This key should point to a valid message defined in the appropriate language bundle that is then picked up via the active locale. In case where the language code cannot resolve the real subject, a default subject value would be used.
- `cas.authn.pm.forgot-username.enabled` (Optional; type `Boolean`; default `true`): Whether forgot/reset username functionality should be enabled.
- `cas.authn.pm.forgot-username.google-recaptcha.activate-for-ip-address-pattern` (Optional; type `String`): A regular expression pattern to indicate that captcha should be activated when the remote IP address matches this pattern, and otherwise skipped and disabled.
- `cas.authn.pm.forgot-username.google-recaptcha.headers` (Optional; type `Map<String,String>`): Headers, defined as a `Map`, to include in the request when making the verification call to the recaptcha API.
- `cas.authn.pm.forgot-username.google-recaptcha.invisible` (Optional; type `Boolean`; default `false`): Whether google reCAPTCHA invisible should be enabled.
- `cas.authn.pm.forgot-username.google-recaptcha.position` (Optional; type `String`; default `bottomright`): The google reCAPTCHA badge position (only if invisible is enabled). Accepted values are: - `bottomright`: bottom right corner, default value. - `bottomleft`: bottom left corner - `inline`: allows one to control the CSS.
- `cas.authn.pm.forgot-username.google-recaptcha.verify-url` (Optional; type `String`; default `https://www.google.com/recaptcha/api/siteverify`): The reCAPTCHA endpoint for verification of the reCAPTCHA response. The endpoint is specific to the reCAPTCHA provider: - For Google reCAPTCHA, the endpoint is `https://www.google.com/recaptcha/api/siteverify`. - For hCaptcha, the endpoint is `https://hcaptcha.com/siteverify`. - For Turnstile, the endpoint is `https://challenges.cloudflare.com/turnstile/v0/siteverify`.
- `cas.authn.pm.forgot-username.google-recaptcha.version` (Optional; type `GoogleRecaptchaProperties.RecaptchaVersions`; default `GOOGLE_RECAPTCHA_V2`): Indicate the version of the recaptcha api. Available values are as follows: - `GOOGLE_RECAPTCHA_V2`: V2 version of the recaptcha API. - `GOOGLE_RECAPTCHA_V3`: V3 version of the recaptcha API. - `HCAPTCHA`: hCaptcha is an alternative to reCAPTCHA that requires website visitors to label images as part of its business model. The provider is more focused on manual image recognition challenges. It is a image classification task based CAPTCHA provider employing visual challenges like identifying objects. - `TURNSTILE`: Offers a CAPTCHA alternative by Cloudflare that prioritizes user experience and privacy. Turnstile delivers frustration-free, CAPTCHA-free web experiences to website visitors - with just a simple snippet of free code. Moreover, Turnstile stops abuse and confirms visitors are real without the data privacy concerns or awful user experience of CAPTCHAs. - `FRIENDLY_CAPTCHA`: Friendly captcha is a European alternative, accessible and GDPR compliant.
- `cas.authn.pm.forgot-username.mail.bcc` (Optional; type `List<String>`): Email BCC address, if any.
- `cas.authn.pm.forgot-username.mail.cc` (Optional; type `List<String>`): Email CC address, if any.
- `cas.authn.pm.forgot-username.mail.html` (Optional; type `Boolean`; default `false`): Indicate whether the message body should be evaluated as HTML text. The application of this setting depends on the email provider implementation and may not be fully supported everywhere. This is typically relevant for the default `org.springframework.mail.javamail.JavaMailSender`.
- `cas.authn.pm.forgot-username.mail.priority` (Optional; type `Integer`; default `1`): Set the priority (`X-Priority` header) of the message. Values: `1 (Highest)`, `2 (High)`, `3 (Normal)`, `4 (Low)`, `5 (Lowest)`. The application of this setting depends on the email provider implementation and may not be fully supported everywhere. This is typically relevant for the default `org.springframework.mail.javamail.JavaMailSender`.
- `cas.authn.pm.forgot-username.mail.reply-to` (Optional; type `String`): Email Reply-To address, if any.
- `cas.authn.pm.forgot-username.mail.text` (Optional; type `String`): Email message body. Could be plain text or a reference to an external file that would serve as a template. If specified as a path to an external file with an extension `.gtemplate`, then the email message body would be processed using the Groovy template engine. The template engine uses JSP style <% %> script and <%= %> expression syntax or GString style expressions. The variable `out` is bound to the writer that the template is being written to. If using plain text, the contents are processed for string substitution candidates using named variables. For example, you may refer to an expected url variable in the email text via `${url}`, or use `${token}` to locate the token variable. In certain cases, additional parameters are passed to the email body processor that might include authentication and/or principal attributes, the available locale, client http information, etc.
- `cas.authn.pm.forgot-username.mail.validate-addresses` (Optional; type `Boolean`; default `false`): Set whether to validate all addresses which get passed to this helper. The application of this setting depends on the email provider implementation and may not be fully supported everywhere. This is typically relevant for the default `org.springframework.mail.javamail.JavaMailSender`.

**Email servers**

The following settings may also need to be defined to describe the mail server settings:

- `spring.mail.default-encoding` (Third party; type `Charset`; default `UTF-8`): Default MimeMessage encoding.
- `spring.mail.host` (Third party; type `String`): SMTP server host. For instance, 'smtp.example.com'.
- `spring.mail.jndi-name` (Third party; type `String`): Session JNDI name. When set, takes precedence over other Session settings.
- `spring.mail.password` (Third party; type `String`): Login password of the SMTP server.
- `spring.mail.port` (Third party; type `Integer`): SMTP server port.
- `spring.mail.properties` (Third party; type `Map<String,String>`): Additional JavaMail Session properties.
- `spring.mail.protocol` (Third party; type `String`; default `smtp`): Protocol used by the SMTP server.
- `spring.mail.ssl.bundle` (Third party; type `String`): SSL bundle name. If set, 'mail.(protocol).ssl.socketFactory' property is set to an SSLSocketFactory obtained from the corresponding SSL bundle. Note that the STARTTLS command can use the corresponding SSLSocketFactory, even if the 'mail.(protocol).ssl.enable' property is not set.
- `spring.mail.ssl.enabled` (Third party; type `Boolean`; default `false`): Whether to enable SSL support. If enabled, 'mail.(protocol).ssl.enable' property is set to 'true'.
- `spring.mail.ssl.verify-hostname` (Third party; type `Boolean`; default `true`): Whether to enable hostname verification.
- `spring.mail.test-connection` (Third party; type `Boolean`; default `false`): Whether to test that the mail server is available on startup.
- `spring.mail.username` (Third party; type `String`): Login user of the SMTP server.
