Daming in 15 minutes

How to use Daming to setup a sms pin micro service in 15 minutes

The basic idea of using daming is adding its spring boot starter to your spring boot project. The starter will import libraries and boot spring beans automatically. With a few lines of configuration codes, you'll get a production ready sms verification feature.

Prerequisites

1. A blank Spring Boot 2 project, you may use Initializer to setup one
2. A dependence management tool, such as gradle
3. A local deployed Redis instance
4. A private key for JWT, you may create your own, or use our demo private key(demo only, do NOT use it for production)
5. Your favorite IDE, such as IntelliJ IDEA

Install Daming

1. Installation
   You can get latest binary release of Daming from Maven Central: , for gradle user:

# install daming
compile "com.github.hippoom:sms-verification-starter:${latestVersion}"

# use spring-data-redis 2.x 
compile "org.springframework.data:spring-data-redis:2.1.2.RELEASE"

2. Configuration
   The following configurations are required to make Daming work, you can use spring-boot profile or environment variables：

# src/main/resources/application.properties

# setup sms verification scopes
daming.sms.verification.scope.valid=DEMO

# setup private key to sign JWT
daming.jwt.key.file=/home/your-app/sms-verification-private.der 

3. Boot your application Daming is ready, start your spring-boot application now!

Request for SMS PIN

Open your favorite terminal, type the request as following:

curl -v -H 'Content-Type:application/json;charset=UTF-8' -XPOST localhost:8080/api/sms/verification/code -d '{"mobile": "your-mobile-phone-number", "scope": "DEMO"}'

Daming will print the PIN on the console instead of sending a real sms by default (to save your money)：

c.t.d.sms.SmsVerificationCodeSenderStub  : Sending [DEMO] code 262843 to [your-mobile-phone-number], the code is expiring in PT1M

Extract your PIN(6 bit digits) after code

Request for SMS PIN verification

Open your favorite terminal, type the request as following:

curl -v -H 'Content-Type:application/json;charset=UTF-8' -XDELETE localhost:8080/api/sms/verification/code -d '{"mobile": "your-mobile-phone-number", "scope": "DEMO", "code": "the code"}'

You shall see similar outputs like this:

{"token":"eyJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJ2ZXJpZmllZE1vYmlsZVBob25lTnVtYmVyIiwibW9iaWxlIjoiMTM5MTc3Nzc3NjMiLCJzY29wZSI6IkRFTU8iLCJleHAiOjE1NjAyNjgzNjV9.hAmB725zVor3mu0lCNlyIjdvnmaRhFmoVRdJUUUMHEEXFo2lBRTlV_1Te02Br0_Juz8gnpAW-8rtVptaFV3fIYogd-T4pVQw4ahXnWV7u_pOkLZLdvOg38v2WRL6YOYDAF1EoFqJU5unnG6bgCFY3dfQFOuggExyPoUUV6ZLh7pvNuDz-fhGzjH9fVrpC9zuxjUU_EHxXxqGg-FTyB9cprqorNdYUvoHJcWSeGUjvVhiSMdn_QqetYFECPyWsFaL7uDtNbBP3ePD-17jcJg_QG1S9mwtnOaD4tNgR0muKbzxoNP7Wzn6BpuQ0dKk-aLzJ5sIMcJ_ZFa5ysB1mDTCRA"}

Decode this token(you can use https://jwt.io/), you shall see

{
  "sub": "verifiedMobilePhoneNumber",
  "mobile": "your-mobile-phone-number",
  "scope": "DEMO",
  "exp": 1560268365
}

It means Daming has verified the PIN is for mobile with scope, and the token is valid before exp.

Congratulations, you have implement SMS PIN feature within just 15 minutes without written any code!

What's next

TODO: translation the following: 另一方面，如果您有以下疑惑：

1. 请求验证码时要求的scope是用来做什么的？请参考这里
2. 为什么要签发JWT？请参考这里
3. 如何集成短信供应商？请参考这里
4. 我能为单体应用嵌入Daming吗？请参考这里