Comprehensive Logging

Logging and auditability of all approval and action flow transactions.

This documentation page has not been published yet. You can see the status of this page and contribute in the GitLab issue.

For planning and review guidance purposes, the following documentation will be used for creating detailed log entries for most operations.

You can learn more about the extensive logging capabilities in the Laravel documentation.

https://laravel.com/docs/8.x/logging

Laravel uses monolog and supports a wide variety of handlers for evolving security and logging needs with different providers.

All exception handling error logs will be sent to Sentry.

Updated format for Logs

Here's refactored logs based on original examples below.

  • The severity and timestamp would be auto-generated using the log engine and not explicitly declared as custom parameters.
  • The message shows the human readable log message. I've added message_slug to have a key for pivot tables.
  • The author_id field can be an AuthUser UUID or null.
  • The author_type field can be web (for authenticated users), cli (user interaction in php artisan or php hacky), or cron (Laravel background job).
  • The entity_* fields are what is getting modified in the database.
  • The logic_* fields are what database record contains the business logic values that made the decision when the class method executed. I don't know if logic is the right term here, I also thought of handler but that is a reserved term. Any ideas?
  • The class and method are where the logic was created from.
  • The ip_address and user_agent are associated with the author_id.
  • The *_id fields at the bottom at used for pivot table keys based on the log_event.
  • JSON encoding will automatically order these alphabetically at runtime.
1{
2"channel": "access-manager-auth",
3"level": "INFO",
4"timestamp": "2020-10-27 17:48:39",
5"message": "User created using provider metadata",
6"message_slug": "auth-provider-user-created",
7
8"author_id": "77b2f6f9-d104-492c-ac2d-aeddead2783f",
9"author_type": "web",
10
11"entity_id": "77b2f6f9-d104-492c-ac2d-aeddead2783f",
12"entity_model": "AuthUser",
13"entity_action": "created",
14
15"logic_id": "de5948b7-1de1-4c3f-91db-16589b464b85",
16"logic_model": "AuthProvider",
17
18"class": "App\\Http\\Controllers\\Auth\\Okta\\LoginController",
19"method": "handleProviderCallback",
20"ip_address":"12.34.56.78",
21"user_agent":"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/86.0.4240.80 Safari/537.36",
22
23"auth_tenant_id":"d60b47bd-d37b-4bae-973a-62ae680fba8b",
24"auth_provider_id":"de5948b7-1de1-4c3f-91db-16589b464b85",
25"auth_provider_slug":"okta",
26"auth_user_id":"77b2f6f9-d104-492c-ac2d-aeddead2783f"
27}
1{
2"channel": "access-manager-auth",
3"level": "INFO",
4"timestamp": "2020-10-27 17:48:39",
5"message": "Granted user access to group using provider default group mapping",
6"message_slug": "auth-provider-group-default-user-created",
7"author_id": "77b2f6f9-d104-492c-ac2d-aeddead2783f",
8"author_type": "web",
9"entity_id": "9bdbb982-cc72-41f7-baa7-21b5a29d7c5e",
10"entity_type": "AuthGroupUser",
11"entity_action": "created",
12"logic_id": "719e49d1-3820-4919-ba80-95b10fbb3d9a",
13"logic_model": "AuthProviderGroup",
14"class": "App\\Http\\Controllers\\Auth\\Okta\\LoginController",
15"method": "handleProviderCallback",
16"ip_address":"12.34.56.78",
17"user_agent":"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/86.0.4240.80 Safari/537.36",
18"auth_tenant_id":"d60b47bd-d37b-4bae-973a-62ae680fba8b",
19"auth_provider_id":"de5948b7-1de1-4c3f-91db-16589b464b85",
20"auth_provider_slug":"okta",
21"auth_user_id":"77b2f6f9-d104-492c-ac2d-aeddead2783f",
22"auth_group_id":"ac822df4-0528-40de-84a6-e1fd92ccf5b7",
23"auth_group_slug":"user-baseline-group"
24}
1{
2"channel": "access-manager-auth",
3"level": "INFO",
4"timestamp": "2020-10-27 17:48:39",
5"message": "User authentication successful",
6"message_slug": "auth-login-success",
7"author_id": "77b2f6f9-d104-492c-ac2d-aeddead2783f",
8"author_type": "web",
9"entity_id": "77b2f6f9-d104-492c-ac2d-aeddead2783f",
10"entity_type": "AuthUser",
11"entity_action": "authenticated",
12"logic_id": "de5948b7-1de1-4c3f-91db-16589b464b85",
13"logic_type": "AuthProvider",
14"class": "App\\Http\\Controllers\\Auth\\Okta\\LoginController",
15"method": "handleProviderCallback",
16"ip_address":"12.34.56.78",
17"user_agent":"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/86.0.4240.80 Safari/537.36",
18"auth_tenant_id":"d60b47bd-d37b-4bae-973a-62ae680fba8b",
19"auth_provider_id":"de5948b7-1de1-4c3f-91db-16589b464b85",
20"auth_provider_slug":"okta",
21"auth_user_id":"77b2f6f9-d104-492c-ac2d-aeddead2783f"
22}

Example Logs from HackyStack with original format

1[2020-10-27 17:48:39] access-manager-auth.INFO: User record created using provider meta data.
2{
3"log_event_type":"auth-provider-user-created",
4"log_class":"App\\Http\\Controllers\\Auth\\Okta\\LoginController",
5"ip_address":"127.0.0.1",
6"user_agent":"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/86.0.4240.80 Safari/537.36",
7"auth_tenant_id":"d60b47bd-d37b-4bae-973a-62ae680fba8b",
8"auth_provider_id":"de5948b7-1de1-4c3f-91db-16589b464b85",
9"auth_provider_slug":"okta",
10"auth_user_id":"77b2f6f9-d104-492c-ac2d-aeddead2783f"
11}
12=> App\Models\Auth\AuthUser {
13 id: "77b2f6f9-d104-492c-ac2d-aeddead2783f",
14 short_id: "77b2f6f9",
15 auth_tenant_id: "d60b47bd-d37b-4bae-973a-62ae680fba8b",
16 auth_provider_id: "de5948b7-1de1-4c3f-91db-16589b464b85",
17 full_name: "Jeff Martin",
18 job_title: “Senior Demo Systems Engineer”,
19 organization_name: null,
20 email: "jmartin@gitlab.com",
21 email_recovery: null,
22 provider_meta_data: {
23 "sub":"redacted",
24 "name":"Jeff Martin",
25 "email":"jmartin@gitlab.com",
26 "locale":"US",
27 "zoneinfo":"America/Los_Angeles",
28 "gl_entity":"Inc",
29 "updated_at":1594359204,
30 "gl_division":"Sales",
31 "gl_job_title":"Senior Demo Systems Engineer",
32 "gl_department":"Customer Success",
33 },
34 provider_token: <encrypted>,
35 timezone: “America/Los_Angeles”,
36 flag_account_expired: 0,
37 flag_account_locked: 0,
38 flag_account_verified: 0,
39 flag_terms_accepted: 0,
40 flag_privacy_accepted: 0,
41 expires_at: null,
42 locked_at: null,
43 verified_at: null,
44 terms_accepted_at: null,
45 privacy_accepted_at: null,
46 last_successful_login_at: null,
47 last_failed_login_at: null,
48 last_activity_at: null,
49 created_at: "2020-10-27 17:48:39",
50 updated_at: "2020-10-27 17:48:39",
51 deleted_at: null,
52 created_by: null,
53 updated_by: null,
54 deleted_by: null,
55 state: "active",
56 }
1[2020-10-27 17:48:39] access-manager-auth.INFO: Granted access to group using provider default group mapping.
2{
3"log_event_type":"auth-provider-group-default-user-created",
4"log_class":"App\\Http\\Controllers\\Auth\\Okta\\LoginController",
5"ip_address":"127.0.0.1",
6"user_agent":"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/86.0.4240.80 Safari/537.36",
7"auth_tenant_id":"d60b47bd-d37b-4bae-973a-62ae680fba8b",
8"auth_provider_id":"de5948b7-1de1-4c3f-91db-16589b464b85",
9"auth_provider_slug":"okta",
10"auth_user_id":"77b2f6f9-d104-492c-ac2d-aeddead2783f",
11"auth_group_id":"ac822df4-0528-40de-84a6-e1fd92ccf5b7",
12"auth_group_slug":"user-baseline-group"
13}
1[2020-10-27 17:48:39] access-manager-auth.INFO: Granted access to group using provider meta data mapping.
2{
3"log_event_type":"auth-provider-group-meta-user-created",
4"log_class":"App\\Http\\Controllers\\Auth\\Okta\\LoginController",
5"ip_address":"127.0.0.1",
6"user_agent":"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/86.0.4240.80 Safari/537.36",
7"auth_tenant_id":"d60b47bd-d37b-4bae-973a-62ae680fba8b",
8"auth_provider_id":"de5948b7-1de1-4c3f-91db-16589b464b85",
9"auth_provider_slug":"okta",
10"auth_user_id":"77b2f6f9-d104-492c-ac2d-aeddead2783f",
11"auth_group_id":"23b486ce-9d35-430a-bf56-d02cb532b641",
12"auth_group_slug":"division-sales"
13}
1[2020-10-27 17:48:39] access-manager-auth.INFO: Granted access to group using provider meta data mapping.
2{
3"log_event_type":"auth-provider-group-meta-user-created",
4"log_class":"App\\Http\\Controllers\\Auth\\Okta\\LoginController",
5"ip_address":"127.0.0.1",
6"user_agent":"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/86.0.4240.80 Safari/537.36",
7"auth_tenant_id":"d60b47bd-d37b-4bae-973a-62ae680fba8b",
8"auth_provider_id":"de5948b7-1de1-4c3f-91db-16589b464b85",
9"auth_provider_slug":"okta",
10"auth_user_id":"77b2f6f9-d104-492c-ac2d-aeddead2783f",
11"auth_group_id":"f0ea234f-adab-4d5d-b88d-00e12dbf6085",
12"auth_group_slug":"department-sales-cs"
13}
1[2020-10-27 17:48:39] access-manager-auth.INFO: User authentication successful.
2{
3"log_event_type":"auth-login-success",
4"log_class":"App\\Http\\Controllers\\Auth\\Okta\\LoginController",
5"ip_address":"127.0.0.1",
6"user_agent":"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/86.0.4240.80 Safari/537.36",
7"auth_tenant_id":"d60b47bd-d37b-4bae-973a-62ae680fba8b",
8"auth_provider_id":"de5948b7-1de1-4c3f-91db-16589b464b85",
9"auth_provider_slug":"okta",
10"auth_user_id":"77b2f6f9-d104-492c-ac2d-aeddead2783f"
11}