Access Tokens
If you want to use an access token through GraphSpy, you will have to set it as the "Active Access Token". Whenever GraphSpy performs an action that would require authentication, it will use the currently active access token to authenticate to the resource.
There are multiple ways to set the active access token:
- From the Access Tokens List on the Access Tokens page, click on the checkmark icon (✓) to activate a specific access token
- On the Access Tokens page, enter the ID of the access token you wish to activate and click the
Set active tokenbutton - From the
Token OptionsSide Bar on any page, fill in the ID of the access token you wish to activate and click theSet active access tokenbutton
The last option will usually be the most convenient if you quickly want to switch the active access token without switching to the Access Token page.
The sidebar will also show a quick summary of your current access token. If your access token is expired, the background of the token summary will be red as shown in the following image.
If you quickly want to refresh your current access token with the exact same resource and client id, you can simply click the Refresh and activate button at the top. This will request a new access token with your current active refresh token, and will automatically activate the new access token.
By default, the Resource and Client ID are set to the values of your current access token, however, you can easily change these parameters as well to request an access token for a different Resource and/or Client ID.
The background of the access token summary will be green if it has not expired yet. (Note: The color is just an indication and is determined by comparing the current time with the expiry time. It will not actually verify whether the token is still valid.)
When using access tokens in GraphSpy, there are two things you need to look at to determine what you can do with it:
- Resource
- Scope
The resource needs to match the specific API which is used. For instance, if you want to use a feature that interacts with the Microsoft Graph API in the background, you will need an access token for the resource https://graph.microsoft.com.
Secondly, the Scope is also important as this actually defines which privileges you have over specific types of objects. For instance, if you want to view the files in the user's OneDrive, you will require one of the following scopes: Files.Read, Files.Read.All, Files.ReadWrite, Files.ReadWrite.All, ...
While you can't directly control which scopes you get in most cases (because Microsoft ignores whatever scopes you request), you can still indirectly influence what kind of scope you are going to receive. In fact, Microsoft seems to look at the Client ID in the access token request, and will automatically set the required scopes which Microsoft believes are required for that specific type of client.
For instance, when you request an access token for the Microsoft Graph API resource with the Client ID of Microsoft Teams, you will always receive the following scope:
AppCatalog.Read.All Channel.ReadBasic.All Contacts.ReadWrite.Shared Files.ReadWrite.All InformationProtectionPolicy.Read MailboxSettings.ReadWrite Notes.ReadWrite.All People.Read Place.Read.All Sites.ReadWrite.All Tasks.ReadWrite Team.ReadBasic.All TeamsAppInstallation.ReadForTeam TeamsTab.Create User.ReadBasic.All
If you want to list which SharePoint sites exist, you will require either Sites.Read.All or Sites.ReadWrite.All according to the documentation. As we can see, we can receive the Sites.ReadWrite.All scope from the Microsoft Teams Client ID. This scope is not available when using the Microsoft Office Client ID for instance, so the SharePoint Sites tab will not work with such an access token.
The following table provides a brief overview of what resources and scopes are required for which specific page. (You only need one of the scopes listed in the scopes column, not all of them.
| Page | Resource | Scope |
|---|---|---|
| Custom Requests | Any resource you want | Depends on the API used. Refer to the Microsoft documentation. |
| Generic MSGraph Search | https://graph.microsoft.com | Depends on the entity type you want to search. A full list can be found here |
| Recent Files | https://graph.microsoft.com | Files.Read, Files.Read.All, Files.ReadWrite, Files.ReadWrite.All, Sites.Read.All, Sites.ReadWrite.All |
| Files Shared With Me | https://graph.microsoft.com | Files.Read.All, Files.ReadWrite.All, Sites.Read.All, Sites.ReadWrite.All |
| OneDrive | https://graph.microsoft.com | Files.Read, Files.ReadWrite, Files.Read.All, Files.ReadWrite.All, Sites.Read.All, Sites.ReadWrite.All |
| SharePoint Sites | https://graph.microsoft.com | Sites.Read.All, Sites.ReadWrite.All |
| SharePoint Drives | https://graph.microsoft.com | Files.Read, Files.Read.All, Files.ReadWrite, Files.ReadWrite.All, Sites.Read.All, Sites.ReadWrite.All |
| SharePoint Files | https://graph.microsoft.com | Files.Read, Files.ReadWrite, Files.Read.All, Files.ReadWrite.All, Sites.Read.All, Sites.ReadWrite.All |
| Outlook | https://outlook.office365.com | * |
| Microsoft Teams | https://api.spaces.skype.com/ | * |
| MFA Methods |
0000000c-0000-0000-c000-000000000000 [1]
|
user_impersonation |
Most functionality in GraphSpy is built to interact with the Microsoft Graph API. As such, you will usually want to utilize access tokens for the resource https://graph.microsoft.com.
[1] Use the v2 API to request an access token for this resource, otherwise the access token will not be accepted by Microsoft when you try to use it.
The Access Tokens page contains the following main sections:
The bottom section of the page is where you can view all the access tokens that are currently stored in the GrapSpy database. Anytime GraphSpy obtains an access token through any means, it will store it in its database. For example:
- Using a refresh token to create a new access token
- Manually adding an access token
- Using the device code flow
Every time a new access token is stored, a unique incremental ID is automatically assigned to it. This ID acts as the primary key to interact with these access tokens.
The checkmark icon (✓) is used to set the access token as the active access token.
If you want to copy the raw access token to your clipboard, you can click on the copy icon. To permanently delete an access token, the delete button can be used.
GraphSpy also allows you to view the full decoded access token by using the dropdown arrow.
The top left section allows you to manually import an access token into GraphSpy.
GraphSpy will automatically extract all the necessary information from the access token itself.
A custom description can optionally be provided, which allows you to keep track of how you obtained this token.
The top right section of the page allows you to create a new access token with a specific refresh token.
Both the Resource and Client ID fields come with a small list of the most common resources and client IDs you might want to use. However, you are free to manually enter any custom resource and client ID not defined by default as well.
There is one special token that can be used in the Resource field as well. When setting the resource to defined_in_token, GraphSpy will use the resource linked to the refresh token itself.
By default, the ID of the Active Refresh token is filled in the Refresh Token id field. If you want to use a different refresh token than the active one, the ID of that token can be selected manually.
The Activate access token and Store refresh token checkboxes do exactly what they advertise. The Activate access token checkbox is enabled by default and will automatically activate the access token after it is requested.
When a refresh token is used to obtain a new access token, Microsoft will also return a completely new refresh token. By default, GraphSpy will not save this new refresh token to its database. However, you can instruct GraphSpy to save this new refresh token using the Store refresh token option. This can be useful if your original refresh token is starting to near its default 90-day expiry date, as the newly obtained refresh token will once again be valid for up to 90 days. In theory, this can be indefinitely refreshed as long as you don't let it expire, unless an action occurs that triggers all refresh tokens for the user to be revoked (e.g. a password reset). For any assessment shorter than 90 days, you probably do not need this.
