Reset Password Flow
Registered users for your application may forget their password and lose the ability to log in to your app. Cloud CMS provides a "reset password" flow that you can use to provide a way for end users to securely reset their password using their username or registered email address.
On this page, we cover a public convenience method that applications can use to easily provide this functionality without having to through the most robust Cloud CMS object-level APIs. If you're interested in learning about the object-level APIs, take a look at:
- The Custom Domain Name where new users will be created.
- The Email Provider to be used to send emails to new users.
Let's now walk through the steps of using this convenience method.
Configure your Application Instance
To utilize the "reset password" convenience flow, you first need to have an Applications data store instantiated that will be used to store data for your mobile/web application. You can instantiate this through the Cloud CMS console or you can do so programmatically. Once you've done so, you will need to configure the application instance to have the following properties:
public.userDomainId- The ID of one of your platform's domains that should be used to store the new, registered users.public.emailProviderId- The ID of one of your platform's email providers that should be used to send emails.
Sample configuration
The following JSON can be appended into your Application JSON (which you can edit within the Cloud CMS console). Or you can edit your application and enter these values via a form.
```` { "public": { "userDomainId": "primary", // either "primary" or a domain ID "emailProviderId": "{Email Provider GUID}" } }<h2>The Reset Password Flow</h2>
<p>
The "reset password" flow works like this:
</p>
<ol>
<li>The web user tries to log in and realizes their password is incorrect, invalid or otherwise isn't working. They click a link that you provide to help them resolve this (usually something akin to "Forgot your password? Click here!").</li>
<li>The web user fills out a brief form where they provide their email address or username. They click submit.</li>
<li>Your application code calls Cloud CMS to create a "reset password" request.</li>
<li>Your application code calls Cloud CMS to send the email for the "forgot username" request.</li>
<li>Your web site informs the user that an email was sent and that they should click the link contained in the email to verify their email address and reset their password.</li>
<li>The user checks their email and clicks the link. The user's browser is taken to a password reset page on your web site. This page receives a "hash" request parameter which is used to commit the reset password (below).</li>
<li>The web site user fills in any additional information they need to supply. They click submit.</li>
<li>Your application code collects the new password, validates it and then commits the reset password request by calling to Cloud CMS.</li>
<li>Cloud CMS updates the user's password.</li>
</ol>
<h2>
API Methods
</h2>
<p>
Below we cover step-by-step how to use the API methods to complete a "reset password" flow.
For technical details on using the public application services API, please see:
<br/>
<a href="http://api.cloudcms.com/docs#!/public">Public Application Services API</a>
</p>
<h3>Create a Reset Password Request</h3>
<p>
To create a reset password request, you need to make a call to Cloud CMS:
<br/>
<br/>
<code>POST /pub/applications/{applicationId}/requests/resetpassword</code>
<br/>
<br/>
You need to specify the ID of your Application instance in the path to the method.
<br/>
<br/>
The body of your POST should contain two fields that contain the username and email definition. These are contained
in the <code>principal</code> and <code>email</code> fields, respectively. Like this:
</p>
{ "principal": "joe@joe.com", "email": { "body": "Click me to reset your password", "from": "webmaster@website.com" } }
<p>
Here is an example of using some straightforward jQuery to create the request:
</p>
// the application var applicationId = "GUID1";
// create the reset password request $.ajax({ "type": "POST", "dataType": "json", "processData": false, "url": "/pub/applications/" + applicationId + "/requests/resetpassword/create", "data": { "principal": "joe@joe.com", "email": { "body": "Click me to reset your password", "from": "webmaster@website.com" } } });
<p>
And here is a list of everything that can be passed in when defining the request:
</p>
{ "principal": "", // either the email, id or username of a principal "email": { // email properties (see email request API) } }
<p>
When you create a reset password request, you'll get back a JSON object containing the newly created
reset password ID (<code>_doc</code>). You will need to pass this ID to the next call in order to send the
reset password request email to the end user.
</p>
<p>
As part of creating the request, you need to provide an email definition that describes the email that is being
sent out. In defining the email body, you have access to a model which provides variables that you may choose
to use within your template. In particular, the <code>user</code> variable is available which provides all
properties about the user including their user name (provided as <code>user.name</code>).
<br/>
<br/>
There is also a <code>hash</code> variable which should be used to build the link back to your web site. The hash
is used by the next step to commit the password reset.
<br/>
<br/>
For more details on email definitions, see <a href='/documentation/gitana/3.2/guide/guide/actions/send-email.html' title='Send Email'>Send Email</a>.
</p>
<h3>Send the Reset Password Email</h3>
<p>
To send the reset password email, you can simply do an empty POST to:
<br/>
<br/>
<code>POST /pub/applications/{applicationId}/requests/resetpassword/{resetPasswordId}/send</code>
<br/>
<br/>
The reset password email will be sent and it will contain the body and properties as defined in the <code>email</code>
templates block within your request configuration.
<br/>
<br/>
Once the email is sent, the end user will receive an email that is formatted according to your template. Your
template can use the <code>user</code> model variable to provide the <code>user.name</code> username to the
end user.
<br/>
<br/>
This email must contain a link that they can follow to continue the reset password flow. This link must
connect to your web site and the link should also pass along a request parameter (or a hash link) that
contains the <code>${hash}</code> for the reset password request. This hash is generated by the reset password
flow and will only be made available to the email recipient. When the end user clicks on the link, the hash
is passed over to your web site.
<br/>
<br/>
Your web site then uses this hash to confirm the password reset. This is described in the next step.
</p>
<p>
Here is an example of using some straightforward jQuery to send the email:
</p>
// the application var applicationId = "GUID1";
// the reset password request id var resetPasswordId = "GUID2";
// send the registration confirmation email $.ajax({ "type": "POST", "dataType": "json", "processData": false, "url": "/pub/applications/" + applicationId + "/requests/resetpassword/" + resetPasswordId + "/send" });
<h3>Commit the Reset Password Request</h3>
<p>
To complete the password reset, you simply need to call over to Cloud CMS and pass along the new password
for the user. This is passed along in the POST payload, as shown here:
</p>
{ "password": "" // the password }
<p>
Here is an example of using some straightforward jQuery to commit the password reset:
</p>
// the application var applicationId = "GUID1";
// the reset password request hash var hash = "HASH";
// confirm the registration (and send welcome email) $.ajax({ "type": "POST", "dataType": "json", "processData": false, "url": "/pub/applications/" + applicationId + "/requests/resetpassword/" + hash + "/commit", "data": { "password": "password1" } });
<p>
When the method completes, the user's password will be updated.
</p>