8000 initial readme.md for BAA - totaljs/examples#43 · JavaScriptExpert/examples@5ea05d4 · GitHub
[go: up one dir, main page]

Skip to content
8000

Commit 5ea05d4

Browse files
aubergine10aubergine10
aubergine10
authored and
aubergine10
committed
initial readme.md for BAA - totaljs#43
Still waiting for infos about user/pass embedded in URL then will update doc to include details.
1 parent b453456 commit 5ea05d4

File tree

1 file changed

+93
-0
lines changed

1 file changed

+93
-0
lines changed

authorization-www-basic/readme.md

Lines changed: 93 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
## Example: Basic Access Authentication (BAA)
2+
3+
This example shows how to use [Basic Access Authentication](https://en.wikipedia.org/wiki/Basic_access_authentication) to authenticate users.
4+
5+
Features covered by this example:
6+
7+
* `controller.baa()` - read login details from request
8+
* `controller.baa('prompt')` - send login prompt on response (ask user to login)
9+
10+
See the `/controllers/default.js` for sample code.
11+
12+
### Reading credentials
13+
14+
To read credentials, use the `.baa()` method in a route handler function:
15+
16+
```javascript
17+
function authorization() {
18+
var auth = this.baa(); // this === controller
19+
20+
// ...
21+
}
22+
```
23+
24+
This looks for the `Authorization: Basic <mime-encoded-userid-and-password>` HTTP header in the request, and returns an object containing relevant details:
25+
26+
```javascript
27+
auth.empty // if true, no credentials were found
28+
auth.user // the user name, if found
29+
auth.password // the password, if found
30+
```
31+
32+
### Requesting credentials
33+
34+
If the user hasn't logged in yet, the `auth.empty` property will be `true` (no username or password found)... so, we need to prompt them for those details:
35+
36+
```javascript
37+
function authorization() {
38+
39+
// ...
40+
41+
if (auth.empty) { // ask user to login
42+
this.baa('Log in, bro.'); // or whatever prompt you want the user to see
43+
return;
44+
}
45+
46+
// ...
47+
}
48+
```
49+
50+
This sends a response back to the browser which has a `WWW-Authenticate` HTTP header like this:
51+
52+
```
53+
WWW-Authenticate: Basic realm="Log in, bro."
54+
```
55+
56+
On seeing that header, the browser will display the prompt (`Log in, bro.`) along with a basic login form with fields for username and password. When the user submits the form, the browser will retry the request, only this time it will have the required `Authorization` HTTP header that we are looking for.
57+
58+
### Validating credentials
59+
60+
The resulting request should include the login credentials, now all we need to do is validate them:
61+
62+
```javascript
63+
function authorization() {
64+
65+
// ...
66+
67+
// isValidLogin() would be custom function written by you
68+
// that checks whether user exists and also that the password
69+
// is correct for that user
70+
if ( isValidLogin( auth.user, auth.password ) ) {
71+
72+
// do authorised stuff
73+
74+
} else {
75+
76+
// ask them to login again?
77+
this.baa('Wrong details, try again, bro.');
78+
return;
79+
80+
// or maybe just throw a #401 error?
81+
this.view401('Invalid login details');
82+
return;
83+
84+
}
85+
86+
}
87+
```
88+
89+
> Note: The browser will keep sending the `Authorization` header on subsequent requests for about 15 minutes or more, effectively keeping the user logged in (from user perspective). Downside is that, server-side, you have to re-check the credentials on every request.
90+
91+
## Notes
92+
93+
BAA doesn't make any attempt to encrypt the login details it sends via the `Authorization` HTTP header so, ideally, you should only ever use BAA over HTTPS connections.

0 commit comments

Comments
 (0)
0