Skip to content

Commit b1adfa8

Browse files
datamwebdatamweb
authored
Merge pull request #860 from datamweb/improve-site-part2
Improve site part2
2 parents 7d6c685 + 48d0118 commit b1adfa8

File tree

22 files changed

+242
-167
lines changed

22 files changed

+242
-167
lines changed

‎.github/workflows/docs.yml‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,5 +13,6 @@ jobs:
1313
- uses: actions/setup-python@v4
1414
with:
1515
python-version: 3.x
16-
- run: pip install mkdocs-material
16+
- run: pip3 install mkdocs-material
17+
- run: pip3 install mkdocs-git-revision-date-localized-plugin
1718
- run: mkdocs gh-deploy --force

‎docs/addons/jwt.md‎

Lines changed: 12 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,8 @@
11
# JWT Authentication
22

3-
> **Note**
4-
> Shield now supports only JWS (Singed JWT). JWE (Encrypted JWT) is not supported.
3+
!!! note
4+
5+
Shield now supports only JWS (Singed JWT). JWE (Encrypted JWT) is not supported.
56

67
## What is JWT?
78

@@ -87,9 +88,10 @@ Configure **app/Config/AuthJWT.php** for your needs.
8788

8889
### Set the Default Claims
8990

90-
> **Note**
91-
> A payload contains the actual data being transmitted, such as user ID, role,
92-
> or expiration time. Items in a payload is called *claims*.
91+
!!! note
92+
93+
A payload contains the actual data being transmitted, such as user ID, role,
94+
or expiration time. Items in a payload is called *claims*.
9395

9496
Set the default payload items to the property `$defaultClaims`.
9597

@@ -121,8 +123,9 @@ with the following command:
121123
php -r 'echo base64_encode(random_bytes(32));'
122124
```
123125

124-
> **Note**
125-
> The secret key is used for signing and validating tokens.
126+
!!! note
127+
128+
The secret key is used for signing and validating tokens.
126129

127130
## Issuing JWTs
128131

@@ -231,7 +234,7 @@ class LoginController extends BaseController
231234

232235
You could send a request with the existing user's credentials by curl like this:
233236

234-
```console
237+
```curl
235238
curl --location 'http://localhost:8080/auth/jwt' \
236239
--header 'Content-Type: application/json' \
237240
--data-raw '{"email" : "admin@example.jp" , "password" : "passw0rd!"}'
@@ -242,7 +245,7 @@ the `Authorization` header as a `Bearer` token.
242245

243246
You could send a request with the `Authorization` header by curl like this:
244247

245-
```console
248+
```curl
246249
curl --location --request GET 'http://localhost:8080/api/users' \
247250
--header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJTaGllbGQgVGVzdCBBcHAiLCJzdWIiOiIxIiwiaWF0IjoxNjgxODA1OTMwLCJleHAiOjE2ODE4MDk1MzB9.DGpOmRPOBe45whVtEOSt53qJTw_CpH0V8oMoI_gm2XI'
248251
```

‎docs/assets/css/dark_mode.css‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -42,4 +42,33 @@
4242
.hljs-subst {
4343
color: #ddba52
4444
}
45+
46+
.md-typeset .note > .admonition-title,
47+
.md-typeset .note > summary {
48+
background-color: #0000001a;
49+
}
50+
51+
.md-typeset .admonition.note,
52+
.md-typeset details.note {
53+
border-color: #675647;
54+
}
55+
56+
.md-typeset .note > .admonition-title:before,
57+
.md-typeset .note > summary:before {
58+
background-color: #65686d;
59+
-webkit-mask-image: var(--md-admonition-icon--note);
60+
mask-image: var(--md-admonition-icon--note);
61+
}
62+
63+
.md-typeset .admonition.warning,
64+
.md-typeset details.warning {
65+
border-color: #776144;
66+
}
67+
68+
.md-typeset .warning > .admonition-title:before,
69+
.md-typeset .warning > summary:before {
70+
background-color: #d9913bc2;
71+
-webkit-mask-image: var(--md-admonition-icon--warning);
72+
mask-image: var(--md-admonition-icon--warning);
73+
}
4574
}

‎docs/assets/js/curl.min.js‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
/*! `curl` grammar compiled for Highlight.js 11.3.1 */
2+
(()=>{var e=(()=>{"use strict";return e=>{const n={className:"string",begin:/"/,
3+
end:/"/,contains:[e.BACKSLASH_ESCAPE,{className:"variable",begin:/\$\(/,
4+
end:/\)/,contains:[e.BACKSLASH_ESCAPE]}],relevance:0},a={className:"number",
5+
variants:[{begin:e.C_NUMBER_RE}],relevance:0};return{name:"curl",
6+
aliases:["curl"],keywords:"curl",case_insensitive:!0,contains:[{
7+
className:"literal",begin:/(--request|-X)\s/,contains:[{className:"symbol",
8+
begin:/(get|post|delete|options|head|put|patch|trace|connect)/,end:/\s/,
9+
returnEnd:!0}],returnEnd:!0,relevance:10},{className:"literal",begin:/--/,
10+
end:/[\s"]/,returnEnd:!0,relevance:0},{className:"literal",begin:/-\w/,
11+
end:/[\s"]/,returnEnd:!0,relevance:0},n,{className:"string",begin:/\\"/,
12+
relevance:0},{className:"string",begin:/'/,end:/'/,relevance:0
13+
},e.APOS_STRING_MODE,e.QUOTE_STRING_MODE,a,{match:/(\/[a-z._-]+)+/}]}}})()
14+
;hljs.registerLanguage("curl",e)})();

‎docs/customization/login_identifier.md‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -21,8 +21,9 @@ This only works with the Session authenticator.
2121
'employee_id'
2222
];
2323
```
24-
> **Warning**
25-
> It is very important for security that if you add a new column for identifier, you must write a new **Validation Rules** and then set it using the [Customizing Validation Rules](./validation_rules.md) description.
24+
!!! warning
25+
26+
It is very important for security that if you add a new column for identifier, you must write a new **Validation Rules** and then set it using the [Customizing Validation Rules](./validation_rules.md) description.
2627

2728
3. Edit the login form to change the name of the default `email` input to the new field name.
2829

‎docs/customization/table_names.md‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -17,5 +17,6 @@ public array $tables = [
1717

1818
Set the table names that you want in the array values.
1919

20-
> **Note**
21-
> You must change the table names before running database migrations.
20+
!!! note
21+
22+
You must change the table names before running database migrations.

‎docs/customization/validation_rules.md‎

Lines changed: 63 additions & 64 deletions
Original file line numberDiff line numberDiff line change
@@ -39,83 +39,82 @@ Shield has the following rules for registration by default:
3939
];
4040
```
4141

42-
> **Note**
43-
> If you customize the table names, the table names
44-
> (`users` and `auth_identities`) in the above rules will be automatically
45-
> changed. The rules are implemented in
46-
> `RegisterController::getValidationRules()`.
42+
!!! note
43+
44+
If you customize the table names, the table names(`users` and `auth_identities`) in the above rules will be automatically changed.
45+
The rules are implemented in `RegisterController::getValidationRules()`.
4746

4847
If you need a different set of rules for registration, you can specify them in your `Validation` configuration (**app/Config/Validation.php**) like:
4948

5049
```php
51-
//--------------------------------------------------------------------
52-
// Rules For Registration
53-
//--------------------------------------------------------------------
54-
public $registration = [
55-
'username' => [
56-
'label' => 'Auth.username',
57-
'rules' => [
58-
'required',
59-
'max_length[30]',
60-
'min_length[3]',
61-
'regex_match[/\A[a-zA-Z0-9\.]+\z/]',
62-
'is_unique[users.username]',
63-
],
64-
],
65-
'email' => [
66-
'label' => 'Auth.email',
67-
'rules' => [
68-
'required',
69-
'max_length[254]',
70-
'valid_email',
71-
'is_unique[auth_identities.secret]',
72-
],
73-
],
74-
'password' => [
75-
'label' => 'Auth.password',
76-
'rules' => 'required|max_byte[72]|strong_password[]',
77-
'errors' => [
78-
'max_byte' => 'Auth.errorPasswordTooLongBytes'
79-
]
50+
//--------------------------------------------------------------------
51+
// Rules For Registration
52+
//--------------------------------------------------------------------
53+
public $registration = [
54+
'username' => [
55+
'label' => 'Auth.username',
56+
'rules' => [
57+
'required',
58+
'max_length[30]',
59+
'min_length[3]',
60+
'regex_match[/\A[a-zA-Z0-9\.]+\z/]',
61+
'is_unique[users.username]',
8062
],
81-
'password_confirm' => [
82-
'label' => 'Auth.passwordConfirm',
83-
'rules' => 'required|matches[password]',
63+
],
64+
'email' => [
65+
'label' => 'Auth.email',
66+
'rules' => [
67+
'required',
68+
'max_length[254]',
69+
'valid_email',
70+
'is_unique[auth_identities.secret]',
8471
],
85-
];
72+
],
73+
'password' => [
74+
'label' => 'Auth.password',
75+
'rules' => 'required|max_byte[72]|strong_password[]',
76+
'errors' => [
77+
'max_byte' => 'Auth.errorPasswordTooLongBytes'
78+
]
79+
],
80+
'password_confirm' => [
81+
'label' => 'Auth.passwordConfirm',
82+
'rules' => 'required|matches[password]',
83+
],
84+
];
8685
```
8786

88-
> **Note**
89-
> If you customize the table names, set the correct table names in the
90-
> rules.
87+
!!! note
88+
89+
If you customize the table names, set the correct table names in the rules.
9190

9291
## Login
9392

9493
Similar to the process for validation rules in the **Registration** section, you can add rules for the login form to **app/Config/Validation.php** and change the rules.
9594

9695
```php
97-
//--------------------------------------------------------------------
98-
// Rules For Login
99-
//--------------------------------------------------------------------
100-
public $login = [
101-
// 'username' => [
102-
// 'label' => 'Auth.username',
103-
// 'rules' => 'required|max_length[30]|min_length[3]|regex_match[/\A[a-zA-Z0-9\.]+\z/]',
104-
// ],
105-
'email' => [
106-
'label' => 'Auth.email',
107-
'rules' => [
108-
'required',
109-
'max_length[254]',
110-
'valid_email'
111-
],
112-
],
113-
'password' => [
114-
'label' => 'Auth.password',
115-
'rules' => 'required|max_byte[72]',
116-
'errors' => [
117-
'max_byte' => 'Auth.errorPasswordTooLongBytes',
118-
]
96+
//--------------------------------------------------------------------
97+
// Rules For Login
98+
//--------------------------------------------------------------------
99+
public $login = [
100+
// 'username' => [
101+
// 'label' => 'Auth.username',
102+
// 'rules' => 'required|max_length[30]|min_length[3]|regex_match[/\A[a-zA-Z0-9\.]+\z/]',
103+
// ],
104+
'email' => [
105+
'label' => 'Auth.email',
106+
'rules' => [
107+
'required',
108+
'max_length[254]',
109+
'valid_email'
119110
],
120-
];
111+
],
112+
'password' => [
113+
'label' => 'Auth.password',
114+
'rules' => 'required|max_byte[72]',
115+
'errors' => [
116+
'max_byte' => 'Auth.errorPasswordTooLongBytes',
117+
]
118+
],
119+
];
121120
```

‎docs/getting_started/concepts.md‎

Lines changed: 10 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -80,14 +80,13 @@ public $passwordValidators = [
8080

8181
You use `strong_password` rule for password validation explained above.
8282

83-
> **Note**
84-
> The `strong_password` rule only supports use cases to check the user's own password.
85-
> It fetches the authenticated user's data for **NothingPersonalValidator**
86-
> if the visitor is authenticated.
87-
>
88-
> If you want to have use cases that set and check another user's password,
89-
> you can't use `strong_password`. You need to use `service('passwords')` directly
90-
> to check the password.
91-
>
92-
> But remember, it is not good practice to set passwords for other users.
93-
> This is because the password should be known only by that user.
83+
!!! note
84+
85+
The `strong_password` rule only supports use cases to check the user's own password.
86+
It fetches the authenticated user's data for **NothingPersonalValidator**
87+
if the visitor is authenticated.
88+
If you want to have use cases that set and check another user's password,
89+
you can't use `strong_password`. You need to use `service('passwords')` directly
90+
to check the password.
91+
But remember, it is not good practice to set passwords for other users.
92+
This is because the password should be known only by that user.

‎docs/getting_started/install.md‎

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -62,10 +62,10 @@ Require it with an explicit version constraint allowing its desired stability.
6262
php spark shield:setup
6363
```
6464

65-
> **Note**
66-
> If you want to customize table names, you must change the table names
67-
> before running database migrations.
68-
> See [Customizing Table Names](../customization/table_names.md).
65+
!!! note
66+
67+
If you want to customize table names, you must change the table names before running database migrations.
68+
See [Customizing Table Names](../customization/table_names.md).
6969

7070
2. Configure **app/Config/Email.php** to allow Shield to send emails with the [Email Class](https://codeigniter.com/user_guide/libraries/email.html).
7171

@@ -140,10 +140,10 @@ your project.
140140

141141
5. **Migration** Run the migrations.
142142

143-
> **Note**
144-
> If you want to customize table names, you must change the table names
145-
> before running database migrations.
146-
> See [Customizing Table Names](../customization/table_names.md).
143+
!!! note
144+
145+
If you want to customize table names, you must change the table names before running database migrations.
146+
See [Customizing Table Names](../customization/table_names.md).
147147

148148
```console
149149
php spark migrate --all

‎docs/guides/api_hmac_keys.md‎

Lines changed: 14 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,18 @@
11
# Protecting an API with HMAC Keys
22

3-
> **Note**
4-
> For the purpose of this documentation and to maintain a level of consistency with the Authorization Tokens,
3+
!!! note
4+
5+
For the purpose of this documentation and to maintain a level of consistency with the Authorization Tokens,
56
the term "Token" will be used to represent a set of API Keys (key and secretKey).
67

78
HMAC Keys can be used to authenticate users for your own site, or when allowing third-party developers to access your
89
API. When making requests using HMAC keys, the token should be included in the `Authorization` header as an
910
`HMAC-SHA256` token.
1011

11-
> **Note**
12-
> By default, `$authenticatorHeader['hmac']` is set to `Authorization`. You can change this value by
13-
> setting the `$authenticatorHeader['hmac']` value in the **app/Config/AuthToken.php** config file.
12+
!!! note
13+
14+
By default, `$authenticatorHeader['hmac']` is set to `Authorization`. You can change this value by
15+
setting the `$authenticatorHeader['hmac']` value in the **app/Config/AuthToken.php** config file.
1416

1517
Tokens are issued with the `generateHmacToken()` method on the user. This returns a
1618
`CodeIgniter\Shield\Entities\AccessToken` instance. These shared keys are saved to the database in plain text. The
@@ -63,9 +65,10 @@ $token = $user->generateHmacToken('token-name', ['users-read']);
6365
return json_encode(['key' => $token->secret, 'secretKey' => $token->secret2]);
6466
```
6567

66-
> **Note**
67-
> At this time, scope names should avoid using a colon (`:`) as this causes issues with the route filters being
68-
> correctly recognized.
68+
!!! note
69+
70+
At this time, scope names should avoid using a colon (`:`) as this causes issues with the route filters being
71+
correctly recognized.
6972

7073
When handling incoming requests you can check if the token has been granted access to the scope with the `hmacTokenCan()` method.
7174

@@ -111,5 +114,6 @@ parses the raw token and looks it up the `key` portion in the database. Once fou
111114
to validate the remainder of the Authorization raw token. If it passes the signature test it can determine the correct user,
112115
which will then be available through an `auth()->user()` call.
113116

114-
> **Note**
115-
> Currently only a single scope can be used on a route filter. If multiple scopes are passed in, only the first one is checked.
117+
!!! note
118+
119+
Currently only a single scope can be used on a route filter. If multiple scopes are passed in, only the first one is checked.

0 commit comments

Comments
 (0)