Purpose

Support for registration using email as 2nd factor to verify registration code.

It also supports password reset, by generating and sending a password reset email with a new code - when the user then enters this code, he can enter a new password and continue using that, having confirmed his access to his email address.

Features

• Registration / reset code generation
• OTP generation, sending and validation
• Code verification
• Password change
• New user registration
• Sending emails

Overview

The Email Authentication plugin has the following classname; dk.itp.portalprotect.useradmin.server.EmailUAAuthenticationPlugin - it uses Ceptor User Administration Server as user identity store, so it works with users stored there - e.g. API Management Developers.

Configuration

The following configuration properties exist:

Dynamic Email Message Content

Both the registration email and password email can contain the following strings, which are replaced with the dynamic information before being transmitted:

• {username}
  Replaced with the users name
• {userid}
  Replaced with the userid
• {code}
  Replaced with the generated registration code
• \n
  Replaced with linefeed

Using the Email Authentication Plugin

Creating New User

To create a new user, from an Agent; call:

CreateUserCredentials creds = new CreateUserCredentials();


// Fill in any details we want in the new user record	
creds.userid = "userid@example.com";
creds.email = "userid@example.com";
creds.password = "somePassword";
creds.firstname = "Sample";
creds.firstname = "User";
creds.company = "example.com";


Agent.getInstance().executeAuthpluginCommand( getSessionId(), AuthTypes.AUTHTYPE_EMAIL, "adduser", creds );

This wil lcreate the new user in the database, generate a registration code and send it to him.

For compatibility reasons, it is also possible to call it without using a CreateUserCredentials object, but a string array instead, like the example below - but in this case you are limited to specifying userid, email and username.

Agent.getInstance().executeAuthpluginCommand( getSessionId(), AuthTypes.AUTHTYPE_EMAIL, "adduser", new String[] {"userid", "userid@example.com", "Sample User"});

This will create a new user, and a userid/password challenge (login method ID 1)  with the password, and the status set to inactive.

It will also create a new challenge code, and store that in a new challenge (login method ID 11)  for the same user - the code is stored BCrypt encrypted.

After creation, an email with the registration code is sent - if the sending of the email fails for some reason, the created user/challenges are deleted again, and an error is returned.

Login / Verify Code

Simply do a regular login to authenticate the user

Agent.getInstance().login( getSessionId(), AuthTypes.AUTHTYPE_EMAIL, userid, registration_code);

If the call completes without errors, the code was correct.

Converting Authenticated User to Regular User

After authenticating, you can ask the plugin to convert to the user to a regular user - this means it removes the registration code challenge, and activates the userid/password challenge again.

Do the following:

Agent.getInstance().executeAuthpluginCommand( getSessionId(), AuthTypes.AUTHTYPE_EMAIL, "converttouidpw", new String[] {encryptedPassword});

Note that this requires that the user has previously authenticated using the correct userid/registration code. If the supplied password is not null or empty, this will be set on the userid/password challenge.

Send Reset Password Email

To send a new password reset email, call:

Agent.getInstance().executeAuthpluginCommand( getSessionId(), AuthTypes.AUTHTYPE_EMAIL, "resetpw", new String[] {userid});

This will lookup the user record, find the registered email address and generate a new password reset email to this user.

A new registration/rest code challenge is also created, and the code is saved within it - when the user later authenticates, his new password can be set.

Change Password

To change the password, after authenticating using this plugin, call 

Agent.getInstance().changePassword( getSessionId(), "oldpassword", "newpassword" );

If the old password is empty, the plugin will not validate it, and simply store the new password, otherwise it will fail unless the supplied password is correct.

After changing the password, it will delete an eventual earlier sent registration code challenge.

Generate OTP email

To send a new One-Time-PIN email, call:

Agent.getInstance().newToken( getSessionId(), AuthTypes.AUTHTYPE_EMAIL, "emailotp");

This will lookup the user record, find the registered email address and generate a new one-time pin email to this user.

Before calling this, login with userid and password using the userid/password authentication plugin AuthTypes.AUTHTYPE_USERADMINISTRATION - but before calling login, set the state variable "require_otp" to "true" - if that is set, it will not complete the login, but will wait for a pending 2nd factor to be used.

The OTP will be stored in the session, and is available for use when logging in.

Verify OTP

Verify OTP code previously sent via email

Agent.getInstance().login( getSessionId(), AuthTypes.AUTHTYPE_EMAIL, userid, new String[] {otpcode});

This will verify the code against the earlier sent one.

User Administration Server Login Methods

The email authentication plugin uses the challenge with the login method ID 11 (LoginMethods.LOGINMETHOD_EMAILREGCODE) to store the generated registration/reset code - and the login method ID 1 (Loginmethods.LOGINMETHOD_USERID_PASSWORD) to store updated passwords, and for generated users