tabshift/soul-server
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge pull request #197 from thevahidal/add-auth-examples

Browse Source 
Add examples for auth endpoints
This commit is contained in:
Vahid Al
2024-06-04 18:33:59 +03:30
committed by GitHub
parent e497fbf479 1dfd5bbafd
commit 88a766465c
4 changed files with 313 additions and 10 deletions
Download Patch File Download Diff File Expand all files Collapse all files

14
README.md
View File

@@ -68,16 +68,16 @@ Run the Soul command with the necessary parameters:
```
Note: When configuring your JWT Secret, it is recommended to use a long string value for enhanced security. It is advisable to use a secret that is at least 10 characters in length.
> Note: When configuring your JWT Secret, it is recommended to use a long string value for enhanced security. It is advisable to use a secret that is at least 10 characters in length.
In this example:
The `-a` flag instructs Soul to run in auth mode.
The `--ts` flag allows you to pass a JWT secret value for the `access and refresh tokens` generation and verification. Replace <your_jwt_secret_value> with your desired secret value.
The `--atet` flag sets the JWT expiration time for the access token. In this case, it is set to four hours (4H), meaning the token will expire after 4 hours.
The `--rtet` flag sets the JWT expiration time for the refresh token. In this case, it is set to three days (3D), meaning the token will expire after 3 days.
The `--iuu` flag is used to pass a username for the initial user
The `--iup` flag is used to pass a password for the initial user
- The `-a` flag instructs Soul to run in auth mode.
- The `--ts` flag allows you to pass a JWT secret value for the `access and refresh tokens` generation and verification. Replace <your_jwt_secret_value> with your desired secret value.
- The `--atet` flag sets the JWT expiration time for the access token. In this case, it is set to four hours (4H), meaning the token will expire after 4 hours.
- The `--rtet` flag sets the JWT expiration time for the refresh token. In this case, it is set to three days (3D), meaning the token will expire after 3 days.
- The `--iuu` flag is used to pass a username for the initial user
- The `--iup` flag is used to pass a password for the initial user
Here are some example values for the `atet` and `rtet` flags

8
docs/api-examples.md
View File

@@ -33,9 +33,11 @@ soul -d ./Chinook_Sqlite.sqlite -p 8000
## Namespaces
1. [/api/tables](api/tables-examples.md) Examples for Tables endpoints
2. [/api/rows](api/rows-examples.md) Examples for Rows endpoints
3. [/api/](api/root-examples.md) Examples for Root endpoints
1. [/api/tables/](api/tables-examples.md) Examples for Tables endpoints
2. [/api/<table-name>/rows/](api/rows-examples.md) Examples for Rows endpoints
3. [/api/auth/](api/auth-examples.md) Examples for Authentication / Authorization endpoints
1. [/api/<table-name>/rows/](api/rows-auth-examples.md) Examples for Rows endpoints in Auth mode
4. [/api/](api/root-examples.md) Examples for Root endpoints
## Handling Errors

164
docs/api/auth-examples.md Normal file
View File

@@ -0,0 +1,164 @@
## Authentication / Authorization
These endpoints are for Soul in the Auth mode. For that you need to enable auth mode by setting the `AUTH=true` environment variable or using the `-a` argument when starting a Soul server.
### 1. Obtain an access token
To obtain an access token call `/auth/token/obtain/` endpoint with `POST` method.
```bash
curl -v --request POST \
--url http://localhost:8000/api/auth/token/obtain \
--header 'Content-Type: application/json' \
--data '{
"fields": {
"username": "damien",
"password": "strongpass"
}
}'
```
Response
```
...
< Set-Cookie: accessToken=<jwt-access-token>; Path=/; HttpOnly
< Set-Cookie: refreshToken=<jwt-refresh-token>; Path=/; HttpOnly
...
```
> You can see that when login is successful, Soul sets two cookies one for the access token and the other for the refresh token.
```json
{
"message": "Success",
"data": {
"userId": 1
}
}
```
#### Body Params
- `fields` containing `username` and `password` e.g.
```json
"fields": {
"username": "damien",
"password": "strongpass"
}
```
> Here's how the jwt access token payload looks like:
```json
{
"subject": "accessToken",
"username": "damien",
"userId": 1,
"isSuperuser": "false",
"roleIds": [1],
"iat": 1717427688,
"exp": 1717463688
}
```
### 2. Refresh token
To refresh and obtain a new access token call `/auth/token/refresh/` endpoint with `GET` method.
```bash
curl -v http://localhost:8000/api/auth/token/refresh \
--cookie 'refreshToken=<jwt-refresh-token>'
```
Response
```
...
< Set-Cookie: accessToken=<jwt-access-token>; Path=/; HttpOnly
< Set-Cookie: refreshToken=<jwt-refresh-token>; Path=/; HttpOnly
...
```
> There you get a new token pair
```json
{
"message": "Success",
"data": {
"userId": 1
}
}
```
#### Cookies
- `refreshToken` the refresh token that you acquired before
### 3. Change password
To change your account password call `/auth/change-password/` endpoint with `PUT` method.
```bash
curl --request PUT \
--url http://localhost:8000/api/auth/change-password \
--header 'Content-Type: application/json' \
--data '{
"fields": {
"currentPassword": "strongpass",
"newPassword": "anotherstrongpass"
}
}' \
--cookie 'accessToken=<jwt-access-token>'
```
Response
```json
{
"message": "Password updated successfully",
"data": {
"id": 1,
"username": "damien"
}
}
```
#### Body Params
- `fields` containing `currentPassword` and `newPassword` e.g.
```json
"fields": {
"currentPassword": "strongpass",
"newPassword": "anotherstrongpass"
}
```
#### Cookies
- `accessToken` the access token that you acquired before
### 4. Logout
In order to logout from your account e.g. remove access and refresh cookies and also revoke your refresh token (access token lifetime is very short and doesn't need to be revoked) call `/auth/logout/` endpoint with `GET` method.
```bash
curl http://localhost:8000/api/auth/logout \
--cookie 'accessToken=<jwt-access-token>' \
--cookie 'refreshToken=<jwt-refresh-token>'
```
Response
```json
{
"message": "Logout successful"
}
```
#### Cookies
- `accessToken` the access token that you acquired before
- `refreshToken` the refresh token that you acquired before

137
docs/api/rows-auth-examples.md Normal file
View File

@@ -0,0 +1,137 @@
## Rows in Auth mode
### 1. List Rows of a Table in Auth mode
To list rows in auth mode we call `/tables/<table-name>/rows/` endpoint with `GET` method and pass the jwt access token via Cookies.
> Note that your account needs to have access to read this table.
> Access (Authorization) in Soul is handled via "\_roles" table aka Roles.
> If you want to learn about granting permissions proceed to the next example.
```bash
curl 'localhost:8000/api/tables/Album/rows/' \
--cookie 'accessToken=<jwt-access-token>'
```
Response
```json
{
"data": [
{
"AlbumId": 1,
"Title": "For Those About To Rock We Salute You",
"ArtistId": 1
},
{ "AlbumId": 2, "Title": "Balls to the Wall", "ArtistId": 2 }
// ...
],
"total": 347,
"next": "/tables/Album?page=2",
"previous": null
}
```
#### Cookies
- `accessToken` the access token that you acquired before
### 2. Granting access to users
Only super users (e.g. `is_superuser=true`) or those with roles that have access to '\_roles' table can grant access to other users.
> Head over to [README](/README.md) and _Updating Super Users_ section to learn how to promote someone to a super user.
#### 2.1. Create a new Role
To create a new Role call `/tables/_roles/rows/` endpoint with `POST` method.
```bash
curl --request POST \
--url http://localhost:8000/api/tables/_roles/rows/ \
--header 'Content-Type: application/json' \
--header 'Cookie: accessToken=<jwt-access-token>' \
--data '{
"fields": {
"name": "editor"
}
}'
```
Response
```json
{
"message": "Row inserted",
"data": {
"changes": 1,
"lastInsertRowid": 2
}
}
```
Now that we have our `editor` Role, we can give it some permissions. Here we want to give it permission to `read` `Album` table.
#### 2.2. Create permissions for a Role
To create permissions for a Role call `/tables/_roles_permissions/rows/` endpoint with `POST` method.
```bash
curl --request POST \
--url http://localhost:8000/api/tables/_roles_permissions/rows/ \
--header 'Content-Type: application/json' \
--header 'Cookie: accessToken=<jwt-access-token>' \
--data '{
"fields": {
"role_id": 2,
"table_name": "Album",
"create": 0,
"read": 1,
"update": 0,
"delete": 0
}
}'
```
Response
```json
{
"message": "Row inserted",
"data": {
"changes": 1,
"lastInsertRowid": 6
}
}
```
#### 2.3. Assign Role to a User
To assign roles to a user call `/tables/_users_roles/rows/` endpoint with `POST` method.
```bash
curl --request POST \
--url http://localhost:8000/api/tables/_users_roles/rows/ \
--header 'Content-Type: application/json' \
--header 'Cookie: accessToken=<jwt-access-token>' \
--data '{
"fields": {
"user_id": 1,
"role_id": 2
}
}'
```
Response
```json
{
"message": "Row inserted",
"data": {
"changes": 1,
"lastInsertRowid": 2
}
}
```
Now that we assigned `editor` role to a user, he / she can read the `Album` table.