Password

Learn to add password-based authentication to an Organization directly in your app. From the activation of the password connection to final login

• Quickstart
• 45 min

Password authentication has been a key element of online security for many years. Using advanced cryptographic techniques such as hashing and salting, passwords have been used to protect Users' confidential information. However, we don't just follow established standards. We have sought to improve security and enhance the User experience by introducing modern methods. Our aim is to offer more secure approaches and rethink the use of traditional passwords.

With the Password Connection, Cryptr provides you:

• A password algorithm strength analysis Zxcvbn
• A Time To Live password management

Before starting

Create your free Cryptr account now, and you will have the three elements needed for this guide.

• API Key: You will receive a client_id and a client_secret. Read our guide to learn how to authenticate with these elements to use the Cryptr API.
• Organization: You will create your first organization, which could be your customer or yourself for a first test. Learn more about Organization.
• Redirection: A redirect, also called a redirect_uri, is the URI your user will be sent to after successful authentication.

1. Activate a PasswordConnection for an Organization

In order to enable Cryptr Password, you need to activate a Password Connection for the organization you previously created in your dashboard.

To do so, navigate to the page dedicated to the organization for which you wish to activate the Password connection. Select the organization via the User Directory side navigation bar on the left side of your screen.

You can now use Password Endpoints in your Application.

Customize Password Settings

It is possible to customize Password Settings by clicking on Password Connectionin your Dashboard.

2. Request a new password with a MagicLink

First of all, of course, you'll need to create a password for your user.

First, validate the mailbox with a magic link

It is important to check the mailbox of the User before let him choose the password. If the User forgot the password, and the email address is not correct, the account will be locked. To initiate the process of creating a new password using a Magic Link, you'll need to trigger a password request for the user.

cURL

curl -X POST ${cryptr_service_url}/api/v2/password-request \
   -d user_email="john@communitiz-app.com" \
   -d redirect_uri=${redirect_uri} \
   -d org_domain=${org_domain} \
   -d find_or_create_user=true

With this API request, you'll get a Magic Link. Send it to your users by email. Once your users have clicked on this Magic Link, we will use the redirect_uri provided to redirect the User. After the redirect you will get a password_code that will be used to create a new password. The user will have to enter a new password. Send this new password and the password code to our next API endpoint.

Create the User with the Password

Note that there is a find_or_create_user option. Thanks to this option, you can ask to create the user at the time of password creation. To do so, set this option to true. If you do not wish to create a user at the same time as the password, leave this option set to false or leave it blank. The default setting is false.

Secondly, create the new Password from the validated mailbox

Now that you have the password_code from the validated mailbox, your user can choose its password.

cURL

curl -X POST ${cryptr_service_url}/api/v2/password \
   -d user_email="john@communitiz-app.com" \
   -d plain_text="2vK79^41aokzi6lc8" \
   -d password_code="9DGykvCVPZDEZ1rD8pie7xl8s4fQtG" \
   -d org_domain="communitiz-app"

Using the Create a new Password request, you'll obtain a code. You can then consume this code with a POST request to ${cryptr_service_url}/oauth/token to retrieve the associated tokens. These tokens contain both the user's access rights and identity.

Password Code VS Authorization Code

With the Password Code password_code, you will get the right to create the new Password for your user.

While with the Authorization Code code, you can fetch the final tokens, that contains the access and the identity tokens of the User.

Create the new Password directly without email verification

If you wish, you can create a password for your users without having to check their mailbox. To do this, use the code below:

cURL

curl -X POST ${cryptr_service_url}/api/v2/password \
   -d user_email="john@communitiz-app.com" \
   -d plain_text="2vK79^41aokzi6lc8" \
   -d org_domain="communitiz-app"

Now that your users have their passwords, you can manage their sessions using the password challenge.

Cryptr secures the connection by generating a password challenge using the email address and password supplied by the User. If the challenge is successful, authentication token is generated, enabling the User to access the service. If the password has expired, Cryptr provides you a code to request a new password. Otherwise, access is denied.

3. Login with an existing password

cURL

curl -X POST ${cryptr_service_url}/api/v2/password-challenge \
   -d user_email="emilie@communitiz-app.co" \
   -d password="2vK79^41aokzi6lc8"

The user_email domain is used to retrieve your organization domain but you can also use this endpoint with org_domain as parameter.

Password Challenge using Organization Domain

Password Challenge with Org Domain

This request will help you to Challenge the Password if you can't only use the user_email.

cURL

curl -X POST ${cryptr_service_url}/api/v2/password-challenge \
  -d user_email="emilie@communitiz-app.co" \
  -d org_domain=${org_domain} \
  -d plain_text="2vK79^41aokzi6lc8"

This API call takes an email address and a plain text password to create a password challenge, which verifies that the person is authorized to access the service.

Org Domain & Email Domain

We are using email to find the User, the email domain helps Cryptr to find the Organization owner, and that email domain is recommended for the creation of an Organization. That's why the Organization domain is an optional parameter.

Renew expired password

The provided password may be correct, however we also check if the password has expired by checking the expiredPassword property of the passwordChallenge object. If the password is correct but has actually expired, Cryptr provides a renew_code, which can be exploited via the Password Renewal Endpoint.

Once the User has created a new password, you can use Cryptr's Password creation endpoint, passing the renewal code (renew_code) supplied by the password challenge and the new password in plain text.

If none of the above conditions are met, the User is not authorized and cannot access the service or application.

cURL

curl -X POST ${cryptr_service_url}/api/v2/password \
   -d user_email="john@communitiz-app.com" \
   -d plain_text="2vK79^41aokzi6lc8" \
   -d password_code="9DGykvCVPZDEZ1rD8pie7xl8s4fQtG" \
   -d org_domain="communitiz-app"

Full example of processing of results

After generating a password Challenge, we check whether the Challenge was successful (success property) or not. If so, the password authentication is valid.

In this case, the code generates authentication Token from the password Challenge. This Token enables the User to access the service or application. In the case of an expired Password you can see that we also check the password expiration. We will talk about this in the next part.

Reset a forgotten Password

During the login step, Users may encounter errors that can block access. Here are two common errors and their meanings:

• not_found: This means that the email address the User entered when logging was not found in the system. This error may also be received if the Password Connection has not been created or if the domain entered does not exist / has been entered incorrectly.

• unauthorized_credentials: This error occurs when the credentials provided when trying to log in are incorrect. The User should be asked to ensure that they enters their email address and password correctly, also checking the case of the characters.

If the User encounters any of these errors, or has forgotten their password, we offer a request feature to enable them to create a new password. Using the request process, the User receives an email inviting them to create a new password. They will then have to validate the new password, respecting the required security criteria (such as password strength), and once completed, they will should be redirected back to the application, ready-to-use it again.

Reset password

If the User forget their password, or if their password is involved in a data breach. This is a two-step process to ensure the security of the account.

cURL

curl -X POST ${cryptr_service_url}/api/v2/password-request \
   -d user_email="john@communitiz-app.com" \
   -d redirect_uri="http://authent.me/password-creation" \
   -d org_domain="communitiz-app"

# Send the Magic Link by Email to your user.
# After clicking the link they will be redirected to your App.

# You can then allow the User to create a new Password
curl -X POST ${cryptr_service_url}/api/v2/password \
   -d plain_text="2vK79^41aokzi6lc8" \
   -d password_code="9DGykvCVPZDEZ1rD8pie7xl8s4fQtG"

In the first step, the User is asked to enter the email address associated with their account. You will then receive an unique Token in a link that you can send to the user through email. This Token is a specific code that identifies the password reset request.

The second stage begins when the User clicks on the link provided in the reset email. This link contains the unique Token which is sent to the server. The server checks the validity of the token and redirects the user to one of your page where they can set a new password. Here you can notice that it's possible to only pass the plain_text & the password_code. Indeed Cryptr can retrieve the user and the org_domain thanks to the password_code

In the event of an error, if the User tries to reset the password with a non-existent email address, an error message should be displayed to inform the user of this situation.

Conclusion

I hope this guide has given you a better understanding of the steps involved in password authentication in your application. Here is a summary of the topics covered:

• The initial configuration of the password login to create a new password for your Users.
• Password challenge, a feature that enhances security while simplifying authentication.
• Password security, with emphasis on password strength.
• Error messages and hints to provide a clear and informative user experience during authentication.
• Password reset & renew, enabling users to create a new password in the event of expiry or forgetfulness.

If you'd like to go even further, we encourage you to explore our advanced features such as two-factor authentication to further enhance security.

Alternatives

If the User forgets their password, we offer an alternative: the Magic Link. Find out more about this authentication method in our Magic Link integration guide. So, even if the User forgets their password, they can still access your App securely and conveniently.
To offer your users a convenient and secure login experience, we also offer one more alternative authentication method: Single Sign-On (SSO). Find out more about this authentication method in our SSO integration guide To benefit from these features, the organization must support these specific authentication methods.

It's important to note that Magic Link enables fast, password-free log-in by clicking on a unique link sent by email, allowing the user to reset their password once you've logged in.

What’s next

To verify tokens and ensure data trust, you can use our guide: How to validate a JWT

You can also refer to our API references to perform these actions via the Rest API.