You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+55-11Lines changed: 55 additions & 11 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -9,13 +9,9 @@ This OAuth for Laravel package provides a simple and reusable integration for im
9
9
10
10
The package is designed to work flexibly with any user model that implements the Authenticatable interface, ensuring that it can be easily adapted to various projects without direct dependencies on a specific user model.
We invest a lot of resources into creating [best in class open source packages](https://spatie.be/open-source). You can support us by [buying one of our paid products](https://spatie.be/open-source/support-us).
17
-
18
-
We highly appreciate you sending us a postcard from your hometown, mentioning which of our package(s) you are using. You'll find our address on [our contact page](https://spatie.be/about-us). We publish all received postcards on [our virtual postcard wall](https://spatie.be/open-source/postcards). -->
When this command is executed, the user will be guided through a series of steps to properly configure the necessary variables in both the configuration file and the environment file.
35
31
36
-
Steps in the installation process:
32
+
#### Steps in the installation process:
37
33
38
34
### Setting variables in the configuration file
39
35
-**Authenticatable model name**: Here you need to enter the name of the user management model used in the project, which must implement the `Authenticatable` interface.
@@ -42,6 +38,10 @@ Steps in the installation process:
42
38
43
39
-**Login route**: You need to provide the route defined in the project where the login process takes place.
44
40
41
+
-**Route name when callback is OK**: Here you indicate the name of your project path where the redirection will be made after a correct response from the provider.
42
+
43
+
-**Will you use the refresh token system in your app?**: Checking 'Yes' will allow the 'offline_access' scope to be added to the provider configuration. Which will allow the use of refresh token (as long as it is enabled in your OAuth provider).
44
+
45
45
### Creation of variables in the .env file
46
46
-**OAuth base URL**: Enter the base URL of the OAuth provider, which will be used for authorization and authentication requests.
47
47
@@ -53,6 +53,16 @@ Steps in the installation process:
53
53
54
54
-**OAuth mode**: Select the mode of operation of the OAuth system, which will allow 3 modes: “OAUTH”, “PASSWORD” or “BOTH”.
55
55
56
+
## IMPORTANT
57
+
58
+
~~~
59
+
If the process is not completed correctly or is aborted, the implementation and use of the package will result in errors, such as:
60
+
61
+
- Missing the new database table required to store OAuth user data.
62
+
- Incorrectly configured configuration file.
63
+
- Environment variables that are improperly defined or missing.
64
+
~~~
65
+
56
66
Once all steps are completed, the migrations will be automatically executed and the configuration file will be published.
Before starting to develop the workflow, it is recommended to understand how the package works when creating or modifying users and groups.
89
+
90
+
To achieve this, two interfaces have been created: [OAuthUserHandlerInterface](src/Contracts/OAuthUserHandlerInterface.php) and [OAuthGroupHandlerInterface](src/Contracts/OAuthGroupHandlerInterface.php). These interfaces can be implemented in the user model of your application, allowing you to override the `handleUser()` and `handleGroup()` methods, respectively.
91
+
92
+
There are also two predefined classes: [BaseOAuthUserHandler](src/Handlers/BaseOAuthUserHandler.php) and [BaseOAuthGroupHandler](src/Handlers/BaseOAuthGroupHandler.php), which implement these interfaces with default logic. These will serve as an example for the developer and will also help, if it is a simple application, for the package to work without having to overwrite anything.
93
+
94
+
**IMPORTANT**
95
+
96
+
It is likely necessary to implement these interfaces to override the logic for handling the users and groups returned by the OAuth service.
97
+
98
+
However, **do not forget** to override the `user_handler` and `group_handler` variables in the [configuration file](config/oauth.php), specifying which model will override the interface methods.
99
+
100
+
```php
101
+
return [
102
+
...
103
+
104
+
'user_handler' => App\Models\User::class,
105
+
'group_handler' => App\Models\User::class,
106
+
];
107
+
```
108
+
109
+
---
110
+
77
111
Once you have installed the package in your project, the next step is to configure your own login flow. This can be done through a button, link, or any other interface element that triggers a function in a controller. In this function, you'll implement the package and call the `request()` function:
78
112
79
113
```php
80
114
$authController = new OAuthController;
81
115
$authController->request();
82
116
```
83
117
84
-
####1. Create a Controller to Handle OAuth Authentication
118
+
### 1. Create a Controller to Handle OAuth Authentication
85
119
86
120
First, you'll need to create a controller that handles the OAuth authentication logic. You can use the `OAuthController` provided by the package or create your own controller. The main goal is to call the `request()` method from the package to start the OAuth authentication process.
87
121
@@ -104,7 +138,7 @@ class AuthController extends Controller
104
138
}
105
139
```
106
140
107
-
####2. Set Up a Login Route
141
+
### 2. Set Up a Login Route
108
142
109
143
In your routes file (`routes/web.php`), define a route that points to the controller you just created. This route will trigger the OAuth authentication process when the user interacts with the login button or link.
110
144
@@ -114,7 +148,7 @@ use App\Http\Controllers\AuthController;
In your application's view (e.g., `resources/views/auth/login.blade.php`), add a button or link that points to the route you defined in the previous step. When the user clicks the button, the OAuth authentication process will begin.
120
154
@@ -124,14 +158,24 @@ In your application's view (e.g., `resources/views/auth/login.blade.php`), add a
124
158
</a>
125
159
```
126
160
127
-
####4. Authentication Process
161
+
### 4. Authentication Process
128
162
129
163
When the user clicks the button or link, a request will be sent to the `login()` function of the `AuthController`. From there, the controller will call the `request()` method of the package's `OAuthController`, which handles the OAuth authentication flow by redirecting the user to the OAuth provider for authorization.
130
164
131
165
Once the user completes the authorization process, the OAuth provider will redirect back to your application, where you can handle the response and authenticate the user in your system.
132
166
133
167
This will complete the integration of the OAuth package into your project, allowing you to set up a login flow that triggers the OAuth authentication process with a button or link.
134
168
169
+
### Other features
170
+
171
+
This section talks about certain functions of the package, which are good to know.
172
+
173
+
#### Renew tokens
174
+
175
+
For token renewal, simply set the 'offline_access' variable in [the configuration file](config/oauth.php) to `true`; the package will handle the rest.
176
+
177
+
A [middleware](src/Middleware/OAuthTokenRenewal.php) is available that calls the `renew()` function of the `OAuthController`. This function checks whether the authenticated user has an OAuth token and if the expiration time has not passed. If the token has expired, it will determine if a refresh token is being handled. It will either generate a new token or reject and unauthenticate the user's session accordingly.
0 commit comments