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).
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 just one article from Microsoft on tokens lifespan and refreshing:
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 send 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.
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 attempt 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, 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.
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 are 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.
