What is TOTP?
TOTP stands for Time-based One-Time Passwords and is a common form of two factor authentication (2FA). Unique numeric passwords are generated with a standardized algorithm that uses the current time as an input. The time-based passwords are available offline and provide user friendly, increased account security when used as a second factor.
TOTP is also known as app based authentication, software tokens, or soft tokens. Authentication apps like Microsoft Authenticator and Google Authenticator support the TOTP standard.
When TOTP ?
Imagine a secure system that combines something you know (like a password) with something you have (a device generating a one-time password). That’s where TOTP comes in.
How TOTP works?
When user register into our application system will generate a secret key and that will be stored in DB. System will generate a QR code that combines the Algorithm, number of digits and period that will be used by the server to generate the TOTP.
Upon login user will provide the credential and validate. As a next step they will be prompted for OTP. This will be generated by the authenticator application, this will be validated by the server using the time bucket the OTP is entered.
Project:
We are going to implement the Backend server in Spring Boot and Mongo DB as Persistence layer. Angular 14 is our Front end which will connect to backend over rest endpoints. We will be using “dev.samstevens.totp” to generate and verify TOTP.
End-Point Implementation overview:
/register
register endpoint will accept the registration details including the username and password as payload. It will check for user existence, if user already exist then respond with UserAlreadyExist exception, else Generate the Secret key, encode the password received and persist the user details. Further generate the QR code and add it to the response.
/verifyTotp
This endpoint accepts username and TOTP as payload. It will fetch the secret key with the username provided and pass it the verify method of “dev.samstevens.totp” code verifier. If the code is valid then it will generate the JWT and respond back. Else it will respond as Invalid Token.
/login
This endpiont will get the username and password as payload and validate with the AuthProvider. If the credentials are valid and user opted for MFA then respond with MFA Required. Else generate the JWT.
Project Setup:
Create a Spring Boot Project with following dependencies,
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-data-mongodb</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-mail</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-security</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
<groupId>dev.samstevens.totp</groupId>
<artifactId>totp</artifactId>
<version>1.7.1</version>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-validation</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-devtools</artifactId>
<scope>runtime</scope>
<optional>true</optional>
</dependency>
<dependency>
<groupId>org.projectlombok</groupId>
<artifactId>lombok</artifactId>
<optional>true</optional>
</dependency>
application.yaml
spring:
application:
name: mfa-server
data:
mongodb:
host: localhost
port: 27017
database: mfa-server
Create a websecurity configuration class to all endpoints. Also create a bean if BCryptPasswordEncoder.
`@EnableWebSecurity
@Configuration
public class AppSecurityConfig {
@Bean
public PasswordEncoder passwordEncoder(){
return new BCryptPasswordEncoder();
}
@Bean
public SecurityFilterChain defaultFilterChain(HttpSecurity httpSecurity) throws Exception {
return httpSecurity
.cors(cors-> cors.disable())
.csrf(csrf-> csrf.disable())
.sessionManagement(session-> session.sessionCreationPolicy(SessionCreationPolicy.STATELESS))
.authorizeHttpRequests(auth-> auth
.requestMatchers("/error**","/register**","/login**","/verifyTotp**").permitAll()
.anyRequest().authenticated()
)
.build();
}
}`
Create User Entity. This stores the user details, credentials and roles.
`@Document(collection = "users")
@NoArgsConstructor
@AllArgsConstructor
@Data
public class User {
@Id
private String id;
@Indexed
@NotBlank
private String username;
private String password;
boolean mfaEnabled;
@JsonIgnore
private String secretKey;
private String firstName;
private String lastName;
private boolean active;
@DBRef
private Set<Role> roles = new HashSet<>();
}`
Create UserRepository.
`@Repository
public interface UserRepository extends MongoRepository<User, Long> {
Optional<User> findByUsername(String username);
}`
Create a Service that Helps us Register and Verify Totp
`public interface UserService {
MfaTokenData registerUser(User user) throws UserAlreadyExistException, QrGenerationException;
boolean verifyTotp(final String code,String username);
}`
Createa a Controller exposing the endpoints for /register, /login and /verifyTotp.
We will look into the Implementation in our next blog.
Angular Project Setup
Create angular project and include bootstrap.
`"styles": [
"node_modules/bootstrap/scss/bootstrap.scss" ,
"src/styles.scss"
],
"scripts": [
"node_modules/bootstrap/dist/js/bootstrap.bundle.js"
]
`
Create client service that connects with backend over the rest endpoints.
`@Injectable({
providedIn: 'root'
})
export class AuthClientService {
constructor(private http: HttpClient) { }
public login(payload: string): Observable<MfaVerificationResponse> {
const httpOptions = {
headers: new HttpHeaders({
'Content-Type': 'application/json'
})
};
return this.http.post<MfaVerificationResponse>(
environment.apiUrl + '/login', payload, httpOptions
);
}
public verifyTotp(payload: MfaVerificationRequest): Observable<MfaVerificationResponse> {
return this.http.post<MfaVerificationResponse>(
environment.apiUrl + '/verifyTotp', payload
);
}
public register(
payload: string
): Observable<string> {
return this.http.post(
environment.apiUrl + '/register',payload,
{ responseType: 'text' }
);
}
}
`
Create Login, Register components as per your wish and connect them with client. You can refer my implementation from below GitHub.
Mfaapplication
Application developed using Angular 14 and Bootstrap.
Components involved.
- Login
- Register
- TOTP
- Home Module
Check out the complete code implementation here