Skip to content

Commit 92221a0

Browse files
nathanjrobertsonnathanjrobertson
committed
Fix linting for README
1 parent 51c60e7 commit 92221a0

File tree

1 file changed

+20
-25
lines changed

1 file changed

+20
-25
lines changed

‎docs/sql.md‎

Lines changed: 20 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -1,21 +1,23 @@
11
# `sqlauth:SQL`
22

3-
43
These are authentication modules for authenticating a user against and retrieving attributes from an SQL database.
54

65
The authentication can be done in one of two ways:
6+
77
- Most commonly, as a part of the SQL query itself (ie. using SQL functions to hash a parameterized password and compare that to a value stored in the database).
88
- Less commonly, just store the hash in the database, retrieve that then compare that hash using PHP's `password_verify()` function to authenticate. This is useful in cases where there is minimal support in the database or to allow the same code to work against many databases without modification. The differences in how this is configured are in a section towards the bottom of this file.
99

1010
There are two different configuration formats supported ("version 1" and "version 2"). Version 1 is simpler, but is more limited in functionality. Version 2 is more powerful and configurable, but a little more verbose. If you wish to authenticate or gather attributes from more than one SQL database, or need more than one SQL query for authentication then you definitely need Version 2.
1111

1212
The Version 1 configuration support comes in two flavours (but identical configurations):
13+
1314
- `sqlauth:SQL` uses the legacy Version 1 configuration format and code. Eventually the old code will be phased out, and `sqlauth:SQL` will become a synonym for `sqlauth:SQL1Compat`.
1415
- `sqlauth:SQL1Compat` uses the legacy Version 1 configuration, but applies it to the Version 2 code.
1516

1617
If you are starting out we recommend the Version 2 (`sqlauth:SQL2`) configuration format.
1718

1819
You enable the module in `config/config.php`.
20+
1921
```php
2022
'module.enable' => [
2123
[...]
@@ -39,9 +41,9 @@ The basic concepts of how `sqlauth` works is common between versions 1 and 2.
3941

4042
As a worked example, consider the following example table useful for authentication:
4143

42-
| uid | password | salt | givenName | email |
43-
|-----|----------|------|-----------|-----------------|
44-
| bob | ******** | **** | Bob | [email protected] |
44+
| uid | password | salt | givenName | email |
45+
|-----|----------|------|-----------|-------------------|
46+
| bob | ******** | **** | Bob | "[email protected]" |
4547

4648
and another table (potentially in a completely separate database) which has attributes we want to return:
4749

@@ -75,10 +77,10 @@ In summary:
7577
- If multiple queries return the same column names, they will also be merged into the same attributes.
7678
- Duplicate values and NULL values will be removed.
7779

78-
7980
## Version 2 Configuration Format
8081

8182
The Version 2 configuration format supports:
83+
8284
- One or more database connections.
8385
- One or more authentication queries using any database defined in the `databases` section.
8486
- Zero or more attribute queries. Each query can use any database defined in the database section, and can be restricted to apply only to one or more authentication queries.
@@ -112,13 +114,12 @@ $config = [
112114

113115
Assuming the correct `:username` and `:password` are passed, the resulting SAML attributes returned by this configuration would be:
114116

115-
| Attribute Name | Attribute Value |
116-
|----------------|-----------------|
117-
| uid | [ bob ] |
118-
| givenName | [ Bob ] |
117+
| Attribute Name | Attribute Value |
118+
|----------------|---------------------|
119+
| uid | [ bob ] |
120+
| givenName | [ Bob ] |
119121
| email | [ [email protected] ] |
120122

121-
122123
It's really easy to add extra attributes by adding one or more attribute queries:
123124

124125
```php
@@ -155,13 +156,12 @@ $config = [
155156

156157
Assuming the correct `:username` and `:password` are passed, the resulting SAML attributes returned by this configuration would be:
157158

158-
| Attribute Name | Attribute Value |
159-
|----------------|-----------------|
160-
| uid | [ bob ] |
161-
| givenName | [ Bob ] |
159+
| Attribute Name | Attribute Value |
160+
|----------------|---------------------|
161+
| uid | [ bob ] |
162+
| givenName | [ Bob ] |
162163
| email | [ [email protected] ] |
163-
| groupName | [ users, staff ] |
164-
164+
| groupName | [ users, staff ] |
165165

166166
In the below example, we have users in two separate databases and two authentication queries. Authentication queries are run in the order they are configured, and once an authentication query successfully authenticates a user it is deemed to be authenticated using that query, and no further authentication queries are run. In the below case, the username formats are defined (single lower case word for staff, suppliers have a "supp_" prefix), and as a result we can use the optional `username_regex` parameter to get a slight performance boost out of not running unneccessary queries.
167167

@@ -211,7 +211,6 @@ An example staff login with the above configuration might result in SAML attribu
211211
| givenName | [ Brian ] |
212212
| email | [ [email protected] ] |
213213

214-
215214
The next example shows a case where we have a single database we are authenticating against, but are aggregating attributes from a number of different databases. In such cases it is common that users might login with an email address, however the shared User ID between databases is some other ID. To support this, the `extract_userid` takes the value from this other ID field in the authentication query and makes it available as `:userid` in the attribute queries instead of `:username`.
216215

217216
```php
@@ -281,7 +280,6 @@ and a student might look like:
281280
| course | [ Mathematics ] |
282281
| year | [ 2 ] |
283282

284-
285283
When you've got more than one authentication query, it is possible to restrict attribute queries to only run for certain authentication queries using the `only_for_auth` attribute query configuration parameter:
286284

287285
```php
@@ -360,9 +358,7 @@ and a student might look like:
360358
| year | [ 2 ] |
361359
| unit_code | [ MATH201, MATH202, MATH203] |
362360

363-
364-
365-
### Configuration Parameter Dictionary
361+
### Configuration Parameter Dictionary (Version 2)
366362

367363
There are three sections in the configuration, as follows:
368364

@@ -385,6 +381,7 @@ $this->config = [
385381
```
386382

387383
#### databases
384+
388385
`dsn`
389386
: The DSN which should be used to connect to the database server.
390387
Check the various database drivers in the [PHP documentation](http://php.net/manual/en/pdo.drivers.php) for a description of the various DSN formats.
@@ -395,7 +392,6 @@ $this->config = [
395392
`password`
396393
: The password which should be used when connecting to the database server.
397394

398-
399395
#### auth_queries
400396

401397
`database`
@@ -424,10 +420,10 @@ $this->config = [
424420
`only_for_auth`
425421
: (Optional) Only run the attribute query if the user authenticated using one of the authentication queries referenced in this list.
426422

427-
428423
## Version 1 Configuration Format
429424

430425
The Version 1 format is more basic, both in terms of configuration and different use cases it supports. Specifically, it supports:
426+
431427
- One database only
432428
- One authentication query
433429
- Zero or more attribute queries
@@ -522,8 +518,7 @@ In summary:
522518
- If multiple queries return the same column names, they will also be merged into the same attributes.
523519
- Duplicate values and NULL values will be removed.
524520

525-
526-
### Configuration Parameter Dictionary
521+
### Configuration Parameter Dictionary (Version 1)
527522

528523
`dsn`
529524
: The DSN which should be used to connect to the database server.

0 commit comments

Comments
 (0)