Home A - Z

An Otter Wiki

Blame

6e7d20 Hargata Softworks 2024-02-16 02:25:37 1
# Authenticating via OpenID Connect
2
3
Configure OpenID Connect(OIDC) for LubeLogger via the following environment variables
4
5
```
6
OpenIDConfig__Name=Name of the OpenID Connect Provider
7
OpenIDConfig__ClientId=Client Id to Authenticate with the Provider
8
OpenIDConfig__ClientSecret=Client Secret to Authenticate with the Provider
9
OpenIDConfig__AuthURL=Authorization URL to the Provider's Login Page
10
OpenIDConfig__TokenURL=URL to retrieve user JWT from the Provider
11
OpenIDConfig__RedirectURL=https://<yourlubeloggerdomain.com>/Login/RemoteAuth(must be HTTPS)
2c9cf6 Hargata Softworks 2025-03-30 17:26:57 12
OpenIDConfig__Scope=Scope to request from Provider(default: openid email)
639e27 Hargata Softworks 2024-02-24 16:58:08 13
OpenIDConfig__ValidateState=true/false(default: false) - whether LubeLogger should validate state.
0449d6 Hargata Softworks 2024-08-20 19:58:08 14
OpenIDConfig__UsePKCE=true/false(default: false) - whether LubeLogger should use PKCE
8a02d9 Hargata Softworks 2024-03-21 01:57:18 15
OpenIDConfig__DisableRegularLogin=true/false(default: false) - auto re-direct user to OIDC login.
7dc2b7 Hargata Softworks 2024-03-21 01:57:46 16
OpenIDConfig__LogOutURL=Log Out URL for OIDC Provider, required if DisableRegularLogin=true.
6e7d20 Hargata Softworks 2024-02-16 02:25:37 17
```
18
9b47f1 Hargata Softworks 2024-02-16 03:18:13 19
If you're using the Windows Standalone executable, add the following section into `appsettings.json`
20
21
```
22
"OpenIDConfig": {
23
"Name": "",
24
"ClientId": "",
25
"ClientSecret": "",
26
"AuthURL": "",
27
"TokenURL": "",
28
"RedirectURL": "",
2c9cf6 Hargata Softworks 2025-03-30 17:26:57 29
"Scope": "openid email",
c8565f Hargata Softworks 2024-03-21 01:55:57 30
"ValidateState": true/false,
0449d6 Hargata Softworks 2024-08-20 19:58:08 31
"UsePKCE": true/false,
c8565f Hargata Softworks 2024-03-21 01:55:57 32
"DisableRegularLogin": true/false,
33
"LogOutURL": ""
9b47f1 Hargata Softworks 2024-02-16 03:18:13 34
}
35
```
36
d9b4ab Hargata Softworks 2024-02-16 06:43:52 37
The following sample shows how to set up OIDC with Google as the provider with the LubeLogger instance running on `https://localhost:5011`
6e7d20 Hargata Softworks 2024-02-16 02:25:37 38
39
```
40
OpenIDConfig__Name=Google
5e9566 Hargata Softworks 2024-02-16 03:04:40 41
OpenIDConfig__ClientId=xxx.apps.googleusercontent.com
42
OpenIDConfig__ClientSecret=<your Google API Client Secret>
6e7d20 Hargata Softworks 2024-02-16 02:25:37 43
OpenIDConfig__AuthURL=https://accounts.google.com/o/oauth2/auth
44
OpenIDConfig__TokenURL=https://oauth2.googleapis.com/token
45
OpenIDConfig__RedirectURL=https://localhost:5011/Login/RemoteAuth
46
OpenIDConfig__Scope=email
639e27 Hargata Softworks 2024-02-24 16:58:08 47
OpenIDConfig__ValidateState=true
0449d6 Hargata Softworks 2024-08-20 19:58:08 48
OpenIDConfig__UsePKCE=false
c8565f Hargata Softworks 2024-03-21 01:55:57 49
OpenIDConfig__DisableRegularLogin=false
6e7d20 Hargata Softworks 2024-02-16 02:25:37 50
```
51
639e27 Hargata Softworks 2024-02-24 16:58:08 52
## State Validation
53
The ValidateState environment variable determines if LubeLogger should validate the state token echoed back by the OIDC provider. This is set to false by default, if enabled, LubeLogger will fail any login attempts where the state token is not identical to what it sent to the provider. Leave this disabled if you wish to have IdP-initiated SSO.
54
0449d6 Hargata Softworks 2024-08-20 19:58:08 55
## Proof of KeyCode Exchange(PKCE)
56
The UsePKCE environment variable determines if LubeLogger should generate and pass in a SHA-256-hashed challenge code to the OIDC provider.
57
639e27 Hargata Softworks 2024-02-24 16:58:08 58
## Testing
6e7d20 Hargata Softworks 2024-02-16 02:25:37 59
Once you have all these environment variables injected correctly, you should see the ability to login via your OIDC provider. Note: Currently LubeLogger only supports one OIDC provider.
5e9566 Hargata Softworks 2024-02-16 03:04:40 60
2b40a9 DESKTOP-T0O5CDB\DESK-555BD 2024-09-20 15:19:12 61
![](/Advanced/OpenID/a/image-1726781322923.png)
5e9566 Hargata Softworks 2024-02-16 03:04:40 62
2b40a9 DESKTOP-T0O5CDB\DESK-555BD 2024-09-20 15:19:12 63
![](/Advanced/OpenID/a/image-1726781326911.png)
5e9566 Hargata Softworks 2024-02-16 03:04:40 64
d483b9 Hargata Softworks 2024-02-17 00:06:23 65
LubeLogger uses the user's email address to authenticate against a registered user, the email address provided by the OIDC provider must match the email address of the user in the system.
5e9566 Hargata Softworks 2024-02-16 03:04:40 66
c73afa Hargata Softworks 2024-02-17 00:08:13 67
If the user is attempting to login via OIDC but does not have an account with LubeLogger, they will be prompted for a registration token and to set up a username which will then allow them to log in. Note that the registration token is only required for their first time logging in.
12fe29 Hargata Softworks 2025-03-31 15:07:07 68
69
### Advanced Troubleshooting
70
fb31a1 Hargata Softworks 2025-04-02 14:44:20 71
The Remote Auth Debug endpoint allows users to diagnose OIDC-related issues by stepping through it:
12fe29 Hargata Softworks 2025-03-31 15:07:07 72
73
1. Set `OpenIDConfig__RedirectURL` to `https://yourlubeloggerdomain/Login/RemoteAuthDebug`
74
2. Configure your OpenID Provider so that `https://yourlubeloggerdomain/Login/RemoteAuthDebug` is a valid Redirect URL
75
3. Login using OIDC, instead of being redirected to login, you will be redirected to a page that displays checks and results.
76
27e815 Hargata Softworks 2025-03-31 15:09:18 77
Example scenarios(details redacted):
12fe29 Hargata Softworks 2025-03-31 15:07:07 78
79
All checks passed and a user is identified:
80
81
![](/Advanced/OpenID/a/image-1743433228696.png)
82
998cc8 Hargata Softworks 2025-03-31 15:29:57 83
All checks passed but no user is identified with the email(will be redirected to register under normal circumstances)
12fe29 Hargata Softworks 2025-03-31 15:07:07 84
85
![](/Advanced/OpenID/a/image-1743433340241.png)
86
37a95e Hargata Softworks 2025-03-31 15:08:29 87
Failed State Validation, Expired OpenID Code and/or OpenID not returning `id_token`:
12fe29 Hargata Softworks 2025-03-31 15:07:07 88
89
![](/Advanced/OpenID/a/image-1743433430561.png)
90
91
Failed Claim Validation(no email returned from OpenID Provider):
92
93
![](/Advanced/OpenID/a/image-1743433568647.png)
3b61c5 Hargata Softworks 2025-04-05 14:46:04 94
95
#### Authelia >= v4.39
96
97
There are [breaking changes](https://www.authelia.com/integration/openid-connect/openid-connect-1.0-claims/#restore-functionality-prior-to-claims-parameter) for users using Authelia with version >= 4.39
98
99
This is because LubeLogger utilizes the legacy method of retrieving the email claim via the id_token, which Authelia has deprecated as of v4.39, a workaround is outlined in the article linked above until we're able to future-proof the OpenID auth flow used by LubeLogger:
100
101
Authelia config in identity_providers:
102
103
```
104
identity_providers:
105
oidc:
106
claims_policies:
107
legacy_claims:
108
id_token: ['email', 'email_verified', 'preferred_username', 'name']
109
...
110
```
111
112
Authelia config for LubeLogger client:
113
114
```
115
- client_id: lubelogger
116
client_name: "Lube Logger"
117
...
118
claims_policy: "legacy_claims"
119
```