This KB article will cover ALL products where Microsoft MSAL/Graph tokens can be used. The primary demonstration will be done using Report Runner Batch SMTP (Send Mail) settings, but there are some additional screenshots for both Report Runner Batch Sharepoint settings, Report Runner Viewer SMTP settings, and Report Runner Event Server Mail Rules (which are configured in Report Runner Batch).
This KB article will show you lots of screenshots with step-by-step examples, but the basic process is the same:
One issue to be aware of is tokens are NOT forever. They must be refreshed. Company policies (YOUR company policies, not ours) can affect the lifespan of a token. Your company can also revoke a token (sometimes administrators are unaware of what a token is used for). All of that to say, we simply provide for you a way to create and refresh tokens (refreshing is automatic, in the background, and you will generally not notice it -- we do log it each time in the log files, though). If a refresh ever fails, the reason is also written to the log files, so check there first when troubleshooting.
We are NOT in control of anything else. Make sure YOU understand your company's token policies and make sure your company administrators are aware of what Report Runner is and why you are creating tokens (otherwise when a token becomes invalidated and is not refreshed, your batches will fail). Here is Microsoft's official article on token lifespan, expiration, and revocation:
https://learn.microsoft.com/en-us/entra/identity-platform/refresh-tokens
With that in mind, here's the step-by-step process for creating and using tokens. This first example will show creating an SMTP (send mail) token for Report Runner Batch.
---
Under Global Options, Settings, Mail tab, you'll configure token usage for Report Runner Batch (click Token (OAuth) and Create/Get Token):
This will open the OAuth Token Utility application. This "mini" application (executable) is used for ALL token processing in Report Runner. It is used to create tokens, and it is also used to refresh tokens in the background.
When creating a token, you will select the token type. For "SMTP" it's Send Mail. Microsoft Graph logic is based more on the task vs the protocol. In fact, when Report Runner uses it to send mail for you now, it sends the mail to Microsoft, who then re-sends the mail to the destination. Previously the mail was sent directly to the recipient server.
Select the token type, note the token file name, and click Authorize. The token file name includes the Windows ID used to create it. This is important, because for any jobs/batches that use this token, you must schedule with the SAME Windows ID.
Also on this window is a row of Prompt options: Consent (default), Select Account, No Prompt, and Force Login. These control what Microsoft shows you in the browser when you click Authorize. (Prompt options appear in Token Utility version 2030.4.8.1000 and later. If you do not see them, update Report Runner.)
Here's two "FYI" URLs from Microsoft on these prompt options (we purposely ignore/don't support/use Never and Create):
Leave this set to Consent (default) unless you have a problem. With Consent, Microsoft always shows the permissions approval screen so you can review and approve access. This is the standard option and works for most companies. You can hover your mouse over each option for a short description, and the option you choose is remembered for next time.
If token creation fails, the Token Utility analyzes the error and may show a RECOMMENDATION in the log output suggesting a different Prompt option. Follow the recommendation and click Authorize again. The common situations:
Also note: you have 10 minutes to complete the sign-in in the browser. If you take longer, or close the browser without finishing, the utility reports a timeout -- just click Authorize and try again.
Rarely, you may see a message that "Another process is currently working with this token" -- this just means an automatic background refresh was running at that exact moment. Wait a few seconds and click Authorize again.
When you Authorize, a browser will open, and you'll need to choose which account to use (if you have multiple accounts).
After you select your account, it will show the Approval interface. This is where you review the permissions requested and Accept (Known Keep LLC is the creator of Report Runner).
Note, you do NOT (and should NOT) check "Consent on behalf of your organization". That attempts to approve it for multiple accounts. Most end users do NOT have permission to do that anyway. If you get an error of any type trying to Accept these permissions, return to the Token Utility and check the log output -- for common errors it will show a RECOMMENDATION suggesting a different Prompt option to try. Try that first. If the recommendation does not resolve it, you may not have authority to create tokens, and you will need to speak with your internal Microsoft Administrator. We are unable to help with permission issues related to this.
If the token is successfully created, you will be redirected to this screen...
If it is not successful, you will see this screen...
And when you return to the token utility, you should see a good status and Creation Successful message. Again, note the name of your token file. You will need to browse and select it back in your Batch mail settings.
Note: in some cases you may see a yellow "Warning" status instead of green. This means the token WAS created and works right now, but something needs attention -- the message in the log output will say exactly what (for example, a file permission problem that will prevent automatic background refreshing). Fix what the message describes and re-test, or send us the log output.
Click Choose JSON Token File and Select it from Browse Window. Also make sure the Mail Account is set to the same mail account you used when you created the token.
Next, we are going to test the new token by clicking Send Test Mail.
Enter the email address you want to send the test email to.
You will get either a success message (and you can find the email in your Inbox or Junk/SPAM folder)...
Or you will get an error message stating what's wrong...
That concludes the token creation process for Send Mail.
---
Now a REMINDER to schedule using the SAME Windows ID to schedule your batches with that you used to create the token with. If you used REPORTRUNNER\USER1 to create the token, you need to use REPORTRUNNER\USER1 to schedule the batch.
---
As we stated previously, the process for token creation is basically the same for all products. When prompted for the token type, you'll select Send Mail, Send + Receive Mail, or Sharepoint. Note how the file name changes to identify the token.
For Report Runner Event Server Mail Rules, you would use Send + Receive Mail.
The permissions for Report Runner Event Server look slightly different:
Or for Sharepoint, it would look like this...
And these are the permissions for Sharepoint:
---
Report Runner Viewer also allows for token usage, and you'll use the same type of Send Mail token as you used in Report Runner Batch mail settings. The window for Viewer has a lot of the same characteristics as Batch, but the batch-related settings are gone.
---
Let's look at Sharepoint token creation, usage, and testing (and the interactive utility for Sharepoint).
Once you have your Sharepoint token created, you'll want to Test your token.
If you get an error, you'll see this pop-up message:
When you press OK, you'll see this pop-up message (click Yes to open the Sharepoint Utility):
This will start a separate application you can use to interactively test your settings one-at-a-time.
Enter/review your Sharepoint settings and Authenticate.
If successful, you'll see a good status and some additional information like your core/base libraries:
From there you can enter which core library/folder to use (in the example above we used Documents), and then you can list files, list folders, and list folders recursively. With our example, we listed folders within the Documents folder:
When you're done listing and testing, click Close, and Report Runner Batch will offer to fill in the settings you used last in the Sharepoint Utility:
With correct settings, when you re-test you should see this message:
---
Lastly, we're going to do a quick review of the Report Runner Event Server Mail Rules configuration using a token. Just like the other settings, you'll choose Token/OAuth and choose the token you created.
---
That's it. Should you have any additional questions, just let us know.
