Skip to content

Commit 3586894

Browse files
knadhknadh
committed
Fix doc errors
1 parent 425932b commit 3586894

File tree

1 file changed

+55
-39
lines changed

1 file changed

+55
-39
lines changed

‎README.md‎

Lines changed: 55 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
11
# OTP Gateway
2+
23
OTP (One Time Password) Gateway is a standalone web app that provides a central gateway to verify user addresses such as e-mails and phone numbers or get a 2FA confirmations from thse addresses. An e-mail / SMTP verification provider is bundled and it is easy to write custom providers as Go plugins, for instance a plugin that uses Twilio to send out verification codes to phone numbers as text messages.
34

45
- Use the built in web UI to easily integrate with existing applications
@@ -9,55 +10,62 @@ OTP (One Time Password) Gateway is a standalone web app that provides a central
910
![otp](https://user-images.githubusercontent.com/547147/51735115-7d4a5d00-20ac-11e9-8a86-3985665a7820.png)
1011
![email-otp](https://user-images.githubusercontent.com/547147/51734344-407d6680-20aa-11e9-8e8e-03db29d8f900.png)
1112

12-
1313
## How does it work?
14+
1415
The application is agnostic of the address and the OTP or verification code involved. These are handled by provider plugins. Addresses are strings, for example, e-mail IDs, phone numbers, bank account numbers etc., and so are OTPs, for instance, 6 digit codes sent as SMSes or a penny value dropped to a bank account. The gateway pushes the OTP value to the user's target address and the user then has to view the OTP and enter it on the gateway's web view to complete the verification.
1516

1617
## Providers
18+
1719
Providers are written as [Go plugins](https://golang.org/pkg/plugin/) that can be dynamically loaded into the gateway. An SMTP provider is bundled that enables e-mail address verifications by sending an OTP / verification link to user's e-mails. Refer to `providers/smtp/smtp.go`. To write a custom provider, copy the `smtp` plugin and change the methods to conform to the `otpgateway.Provider` interface and compile it as a go plugin (see the `Makefile`).
1820

1921
- [solsms](https://github.com/knadh/otpgateway-solsms) - SMS provider for Solutions Infini (Indian gateway)
2022

2123
# Usage
22-
Download the latest release from the [releases page](https://github.com/knadh/otpgateway/releases) or clone this repository and run `make deps && make build`. Redis is a requirement.
24+
25+
Download the latest release from the [releases page](https://github.com/knadh/otpgateway/releases) or clone this repository and run `make deps && make build`. OTP Gateway requires a Redis installation.
26+
2327
- Copy config.toml.sample to config.toml and edit the configuration
24-
- Run `./otpgateway --prov smtp`
25-
28+
- Run `./otpgateway --prov smtp.prov`
29+
2630
### Built in UI
31+
2732
1. Generate an OTP for a user server side in your application:
28-
`curl -u "myAppName:mySecret" -X PUT -d "to=john@doe.com&provider=smtp" localhost:9000/api/otp/uniqueIDForJohnDoe`
33+
`curl -u "myAppName:mySecret" -X PUT -d "to=john@doe.com&provider=smtp" localhost:9000/api/otp/uniqueIDForJohnDoe`
2934
2. Use the `OTPGateway()` Javascript function (see the Javascript plugin section) to initiate the modal UI on your webpage. On receiving the Javascript callback, post it back to your application and confirm that the OTP is indeed verified:
30-
`curl -u "myAppName:mySecret" -X POST localhost:9000/api/otp/uniqueIDForJohnDoe/status`
35+
`curl -u "myAppName:mySecret" -X POST localhost:9000/api/otp/uniqueIDForJohnDoe/status`
3136

3237
### Your own UI
38+
3339
Use the APIs described below to build your own UI.
3440

3541
# API reference
42+
3643
### List providers
44+
3745
`curl localhost:9000/api/providers`
46+
3847
```json
3948
{
4049
"status": "success",
41-
"data": [
42-
"smtp"
43-
]
50+
"data": ["smtp"]
4451
}
4552
```
4653

4754
### Initiate an OTP for a user
55+
4856
```shell
4957
curl -u "myAppName:mySecret" -X PUT -d "to=john@doe.com&provider=smtp&extra={\"yes\": true}" localhost:9000/api/otp/uniqueIDForJohnDoe
5058
```
5159

52-
| param | description |
53-
|------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
54-
| :id | (optional) A unique ID for the user being verified. If this is not provided, an random ID is generated and returned. It's good to send this as a permanent ID for your existing users to prevent users from indefinitely trying to generate OTPs. For instance, if your user's ID is 123 and you're verifying the user's e-mail, a simple ID can be MD5("email.123"). *Important*. The ID is only unique per namespace and not per provider. |
55-
| provider | ID of the provider plugin to use for verification. The bundled e-mail provider's ID is "smtp". |
56-
| to | (optional) The address of the user to verify, for instance, an e-mail ID for the "smtp" provider. If this is left blank, a view is displayed to collect the address from the user. |
57-
| channel_description | (optional) Description to show to the user on the OTP verification page. If left empty, it'll show the default description or help text from the provider plugin. |
58-
| address_description | (optional) Description to show to the user on the address collection page. If left empty, it'll show the default description or help text from the provider plugin. |
59-
| otp | (optional) The OTP or code to send to the user for verification. If this is left empty, a random OTP is generated and sent |
60-
| extra | (optional) An extra payload (JSON string) that will be returned with the OTP |
60+
| param | description |
61+
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
62+
| :id | (optional) A unique ID for the user being verified. If this is not provided, an random ID is generated and returned. It's good to send this as a permanent ID for your existing users to prevent users from indefinitely trying to generate OTPs. For instance, if your user's ID is 123 and you're verifying the user's e-mail, a simple ID can be MD5("email.123"). _Important_. The ID is only unique per namespace and not per provider. |
63+
| provider | ID of the provider plugin to use for verification. The bundled e-mail provider's ID is "smtp". |
64+
| to | (optional) The address of the user to verify, for instance, an e-mail ID for the "smtp" provider. If this is left blank, a view is displayed to collect the address from the user. |
65+
| channel_description | (optional) Description to show to the user on the OTP verification page. If left empty, it'll show the default description or help text from the provider plugin. |
66+
| address_description | (optional) Description to show to the user on the address collection page. If left empty, it'll show the default description or help text from the provider plugin. |
67+
| otp | (optional) The OTP or code to send to the user for verification. If this is left empty, a random OTP is generated and sent |
68+
| extra | (optional) An extra payload (JSON string) that will be returned with the OTP |
6169

6270
```json
6371
{
@@ -68,7 +76,7 @@ curl -u "myAppName:mySecret" -X PUT -d "to=john@doe.com&provider=smtp&extra={\"y
6876
"to": "john@doe.com",
6977
"channel_description": "",
7078
"address_description": "",
71-
"extra": {"yes": true},
79+
"extra": { "yes": true },
7280
"provider": "smtp",
7381
"otp": "354965",
7482
"max_attempts": 5,
@@ -78,10 +86,10 @@ curl -u "myAppName:mySecret" -X PUT -d "to=john@doe.com&provider=smtp&extra={\"y
7886
"url": "http://localhost:9000/otp/myAppName/uniqueIDForJohnDoe"
7987
}
8088
}
81-
8289
```
8390

8491
### Validate an OTP entered by the user
92+
8593
Every incorrect validation here increments the attempts before further attempts are blocked.
8694
`curl -u "myAppName:mySecret" -X POST -d "action=check&otp=354965" localhost:9000/api/otp/uniqueIDForJohnDoe`
8795

@@ -94,7 +102,7 @@ Every incorrect validation here increments the attempts before further attempts
94102
"to": "john@doe.com",
95103
"channel_description": "",
96104
"address_description": "",
97-
"extra": {"yes": true},
105+
"extra": { "yes": true },
98106
"provider": "smtp",
99107
"otp": "354965",
100108
"max_attempts": 5,
@@ -107,6 +115,7 @@ Every incorrect validation here increments the attempts before further attempts
107115
```
108116

109117
### Check whether an OTP request is verified
118+
110119
This is used to confirm verification after a callback from the built in UI flow.
111120
`curl -u "myAppName:mySecret" -X POST localhost:9000/api/otp/uniqueIDForJohnDoe/status`
112121

@@ -119,7 +128,7 @@ This is used to confirm verification after a callback from the built in UI flow.
119128
"to": "john@doe.com",
120129
"channel_description": "",
121130
"address_description": "",
122-
"extra": {"yes": true},
131+
"extra": { "yes": true },
123132
"provider": "smtp",
124133
"otp": "354965",
125134
"max_attempts": 5,
@@ -133,31 +142,38 @@ This is used to confirm verification after a callback from the built in UI flow.
133142
or an error such as
134143

135144
```json
136-
{"status":"error","message":"OTP not verified"}
145+
{ "status": "error", "message": "OTP not verified" }
137146
```
138147

139-
140148
# Javascript plugin
149+
141150
The gateway comes with a Javascript plugin that enables easy integration of the verification flow into existing application. Once a server side call to generate an OTP is made and a namespace and id are obtained, calling `OTPGateway()` opens the verification UI in a modal popup, and once the user finishes the verification, gives you a callback.
142151

143152
```html
144153
<!-- The id #otpgateway-script is required for the script to work //-->
145-
<script id="otpgateway-script" src="http://localhost:9000/static/otp.js"></script>
154+
<script
155+
id="otpgateway-script"
156+
src="http://localhost:9000/static/otp.js"
157+
></script>
146158
<script>
147-
// 1. Make an Ajax call to the server to generate and send an OTP and return the
148-
// the :namespace and :id for the OTP.
149-
// 2. Invoke the verification UI for the user with the namespace and id values,
150-
// and a callback which is triggered when the user finishes the flow.
151-
OTPGateway(namespaceVal, idVal, function(nm, id) {
152-
console.log("finished", nm, id);
153-
154-
// 3. Post the namespace and id to your server that will make the
155-
// status request to the gateway and on success, update the user's
156-
// address in your records as it's now verified.
157-
}, function() {
158-
console.log("cancelled");
159-
});
160-
159+
// 1. Make an Ajax call to the server to generate and send an OTP and return the
160+
// the :namespace and :id for the OTP.
161+
// 2. Invoke the verification UI for the user with the namespace and id values,
162+
// and a callback which is triggered when the user finishes the flow.
163+
OTPGateway(
164+
namespaceVal,
165+
idVal,
166+
function(nm, id) {
167+
console.log("finished", nm, id);
168+
169+
// 3. Post the namespace and id to your server that will make the
170+
// status request to the gateway and on success, update the user's
171+
// address in your records as it's now verified.
172+
},
173+
function() {
174+
console.log("cancelled");
175+
}
176+
);
161177
</script>
162178
```
163179

0 commit comments

Comments
 (0)