Skip to content

Commit 6aa41dc

Browse files
dcblogdevdcblogdev
committed
added docs
1 parent 42c05ab commit 6aa41dc

15 files changed

+1551
-0
lines changed

‎docs/v3/install.md

+216
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,216 @@
1+
---
2+
title: Install
3+
---
4+
5+
## Via Composer
6+
7+
```php
8+
composer require dcblogdev/laravel-microsoft-graph
9+
```
10+
11+
## Config
12+
You can publish the config file with:
13+
14+
```php
15+
php artisan vendor:publish --provider="Dcblogdev\MsGraph\MsGraphServiceProvider" --tag="config"
16+
```
17+
18+
When published, the `config/msgraph.php` config file contains:
19+
20+
```php
21+
<?php
22+
23+
return [
24+
25+
/*
26+
* the clientId is set from the Microsoft portal to identify the application
27+
* https://apps.dev.microsoft.com
28+
*/
29+
'clientId' => env('MSGRAPH_CLIENT_ID'),
30+
31+
/*
32+
* set the application secret
33+
*/
34+
35+
'clientSecret' => env('MSGRAPH_SECRET_ID'),
36+
37+
/*
38+
* Set the url to trigger the oauth process this url should call return MsGraph::connect();
39+
*/
40+
'redirectUri' => env('MSGRAPH_OAUTH_URL'),
41+
42+
/*
43+
* set the url to be redirected to once the token has been saved
44+
*/
45+
46+
'msgraphLandingUri' => env('MSGRAPH_LANDING_URL'),
47+
48+
/*
49+
set the tenant authorize url
50+
*/
51+
52+
'tenantUrlAuthorize' => env('MSGRAPH_TENANT_AUTHORIZE'),
53+
54+
/*
55+
set the tenant token url
56+
*/
57+
'tenantUrlAccessToken' => env('MSGRAPH_TENANT_TOKEN'),
58+
59+
/*
60+
set the authorize url
61+
*/
62+
'urlAuthorize' => 'https://login.microsoftonline.com/'.env('MSGRAPH_TENANT_ID', 'common').'/oauth2/v2.0/authorize',
63+
64+
/*
65+
set the token url
66+
*/
67+
'urlAccessToken' => 'https://login.microsoftonline.com/'.env('MSGRAPH_TENANT_ID', 'common').'/oauth2/v2.0/token',
68+
69+
/*
70+
set the scopes to be used, Microsoft Graph API will accept up to 20 scopes
71+
*/
72+
73+
'scopes' => 'offline_access openid calendars.readwrite contacts.readwrite files.readwrite mail.readwrite mail.send tasks.readwrite mailboxsettings.readwrite user.readwrite',
74+
75+
/*
76+
The default timezone is set to Europe/London this option allows you to set your prefered timetime
77+
*/
78+
'preferTimezone' => env('MSGRAPH_PREFER_TIMEZONE', 'outlook.timezone="Europe/London"'),
79+
];
80+
```
81+
82+
## Migrations
83+
You can publish the migration with:
84+
85+
```php
86+
php artisan vendor:publish --provider="Dcblogdev\MsGraph\MsGraphServiceProvider" --tag="migrations"
87+
```
88+
89+
## Listeners
90+
Optionally if you plan on using Microsoft Graph as a login system you can publish a listener:
91+
92+
```php
93+
php artisan vendor:publish --provider="Dcblogdev\MsGraph\MsGraphServiceProvider" --tag="Listeners"
94+
```
95+
96+
This contains the following listener:
97+
98+
```php
99+
<?php
100+
101+
namespace App\Listeners;
102+
103+
use App\Models\User;
104+
use Illuminate\Contracts\Queue\ShouldQueue;
105+
use Illuminate\Queue\InteractsWithQueue;
106+
use Dcblogdev\MsGraph\Models\MsGraphToken;
107+
use Illuminate\Support\Facades\Auth;
108+
109+
class NewMicrosoft365SignInListener
110+
{
111+
public function handle($event)
112+
{
113+
$tokenId = $event->token['token_id'];
114+
$token = MsGraphToken::find($tokenId)->first();
115+
116+
if ($token->user_id == null) {
117+
$user = User::create([
118+
'name' => $event->token['info']['displayName'],
119+
'email' => $event->token['info']['mail'],
120+
'password' => ''
121+
]);
122+
123+
$token->user_id = $user->id;
124+
$token->save();
125+
126+
Auth::login($user);
127+
128+
} else {
129+
$user = User::findOrFail($token->user_id);
130+
$user->save();
131+
132+
Auth::login($user);
133+
}
134+
}
135+
}
136+
```
137+
138+
You can customise this to suit your application.
139+
140+
After the migration has been published you can create the tokens tables by running the migration:
141+
142+
```php
143+
php artisan migrate
144+
```
145+
146+
.ENV Configuration
147+
Ensure you've set the following in your .env file:
148+
149+
```php
150+
MSGRAPH_CLIENT_ID=
151+
MSGRAPH_SECRET_ID=
152+
153+
MSGRAPH_OAUTH_URL=https://domain.com/msgraph/oauth
154+
MSGRAPH_LANDING_URL=https://domain.com/msgraph
155+
```
156+
157+
If you've setup a single-tenant application make sure to include the tenant ID in the .env:
158+
159+
The tenantID value can be seen in the application you've created at https://portal.azure.com/#blade/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/RegisteredApps click on your application, the Directory (tenant) ID will be listed at the top of the page.
160+
161+
Adding the tenant_id changed some of the URLs from using /common/ to using the supplied tenant ID
162+
163+
```php
164+
MSGRAPH_TENANT_ID=
165+
```
166+
167+
When logging in as a tenant (for Admin access) add the tenant ID .env:
168+
169+
```php
170+
MSGRAPH_TENANT_AUTHORIZE=https://login.microsoftonline.com/{tenant_id}/adminconsent
171+
MSGRAPH_TENANT_TOKEN=https://login.microsoftonline.com/{tenant_id}/oauth2/v2.0/token
172+
```
173+
174+
Optionally add
175+
176+
```php
177+
MSGRAPH_PREFER_TIMEZONE='outlook.timezone="Europe/London"'
178+
```
179+
180+
## Application Register
181+
182+
To use Microsoft Graph API an application needs creating.
183+
184+
Sign in to the https://portal.azure.com/ using either a work or school account or a personal Microsoft account.
185+
186+
If your account gives you access to more than one tenant, select your account in the top right corner, and set your portal session to the Azure AD tenant that you want.
187+
188+
In the left-hand navigation pane, select the Azure Active Directory service, and then select `App registrations > New registration`.
189+
190+
When the Register an application page appears, enter your application's registration information:
191+
192+
Name - Enter a meaningful application name that will be displayed to users of the app.
193+
Supported account types - Select which accounts you would like your application to support.
194+
Enter you desired redirect url. This is the url your application will use to connect to Graph API.
195+
196+
Next click Register on the next page take a note of the Application (client) ID.
197+
198+
Add the following to your .env file, change the domain to match your own.
199+
200+
```php
201+
MSGRAPH_CLIENT_ID=
202+
MSGRAPH_SECRET_ID=
203+
MSGRAPH_TENANT_ID=
204+
MSGRAPH_OAUTH_URL=http://domain.com/msgraph/oauth
205+
MSGRAPH_LANDING_URL=http://domain.com/msgraph
206+
```
207+
208+
Add the client id to the .env file.
209+
210+
Next click Certificate & Secrets and click new client secret
211+
212+
Enter a description and expiration option. Copy secret to .env
213+
214+
Now go to API Permissions. click add permission.
215+
216+
First, select the group type followed by the permission. For instance, when working with emails select the exchange group.

‎docs/v3/introduction.md

+14
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
---
2+
title: Introduction
3+
---
4+
5+
A Laravel package for working with Microsoft Graph API.
6+
7+
https://github.com/dcblogdev/laravel-microsoft-graph
8+
9+
MsGraph comes in two flavours:
10+
11+
MsGraph: login in as a user.
12+
MsGraphAdmin: login as a tenant (administrator) useful for running background tasks.
13+
Microsoft Graph API documentation can be found at:
14+
https://docs.microsoft.com/en-us/graph/api/overview?view=graph-rest-1.0

‎docs/v3/msgraph.md

+62
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
---
2+
title: MsGraph
3+
---
4+
5+
Note this package expects a user to be logged in.
6+
7+
A routes example:
8+
9+
```php
10+
Route::group(['middleware' => ['web', 'auth']], function(){
11+
Route::get('msgraph', function(){
12+
13+
if (! MsGraph::isConnected()) {
14+
return redirect('msgraph/oauth');
15+
} else {
16+
//display your details
17+
return MsGraph::get('me');
18+
}
19+
20+
});
21+
22+
Route::get('msgraph/oauth', function(){
23+
return MsGraph::connect();
24+
});
25+
});
26+
```
27+
28+
Or using a middleware route, if the user does not have a graph token then automatically redirect to get authenticated:
29+
30+
```php
31+
Route::group(['middleware' => ['web', 'MsGraphAuthenticated']], function(){
32+
Route::get('msgraph', function(){
33+
return MsGraph::get('me');
34+
});
35+
});
36+
37+
Route::get('msgraph/oauth', function(){
38+
return MsGraph::connect();
39+
});
40+
```
41+
42+
Once authenticated you can call MsGraph:: with the following verbs:
43+
44+
```php
45+
MsGraph::get($endpoint, $array = [], $headers, $id = null)
46+
MsGraph::post($endpoint, $array = [], $headers, $id = null)
47+
MsGraph::put($endpoint, $array = [], $headers, $id = null)
48+
MsGraph::patch($endpoint, $array = [], $headers, $id = null)
49+
MsGraph::delete($endpoint, $array = [], $headers, $id = null)
50+
```
51+
52+
The second param of array is not always required, its requirement is determined from the endpoint being called, see the API documentation for more details.
53+
54+
The third param `$headers` is a collection of header options, useful for passing additional header options as required.
55+
56+
$id is optional when used the access token will be attempted to be retrieved based on the id. When omitted the logged-in user will be used.
57+
58+
These expect the API endpoints to be passed, the URL https://graph.microsoft.com/beta/ is provided, only endpoints after this should be used ie:
59+
60+
```php
61+
MsGraph::get('me/messages')
62+
```

0 commit comments

Comments
 (0)