Allow or deny custom clients in Office 365 sign on policy
Using the userAgent attribute
You can filter specific clients in an Office 365 app sign on rule to allow or deny them access to Office 365 resources. This filter is especially useful if you want to deny access to certain clients that you do not support or trust. Alternatively, you can use this filter to only allow clients you trust. It gives you a more granular control over the clients that get access to your Office 365 app.
Sign-on rules to filter custom clients are not migrated from Okta Classic to Okta OIE. If you are migrating your Office 365 app instance to Okta OIE, you will need to recreate these rules.
Best practices
Okta sign on policies evaluate information included in the User-Agent request header sent from the user’s browser. However, User-Agent can be spoofed by a malicious actor. To avoid this, Okta recommends the following practices:
- Allow only trusted clients when creating the sign on policies.
- Create one or more rules that specify the client type(s), device platform(s), and trust combinations that are allowed to access the app.
- Require Device Trust or MFA to access the app. See Devices and Multifactor authentication.
Start this procedure
In your Office 365 app:
- Go to the Sign On tab. Under User authentication > Authentication policy, click View policy details. (Alternatively, you can access this by going to Security > Authentication Policies > Microsoft Office 365 > Add Rule.)
- An App Rule window pops up.
- Go to the If section > And The following custom expression is true.
-
Enter a custom expression using Okta Expression Language to allow or deny a client. See good and bad examples below.
- Complete other sections as appropriate and click Save. See Office 365 sign-on rules options.
- Back in the Sign On Policy section, place this rule at an appropriate priority level. Okta evaluates each rule by priority and applies the first rule that matches.
- Repeat Steps 1-5 for each custom client for which you want to allow or deny access.
This rule now filters the specified clients, applies other conditions and actions defined in the rule, and then allows or denies access to Office 365.
Examples
Here are some examples of good and bad custom expressions:
String operations in Okta Expression Language are case sensitive. To write a condition that ignores case, convert the user agent value to upper or lower case before the comparison.
Good examples
| Expression | What it does |
|---|---|
| request.userAgent.contains("WinWord") | Filters a request for user agent containing WinWord. |
| request.userAgent.toLowerCase().contains("winword") | Converts a request to lower case and then filters for user agent containing winword. |
| request.userAgent.toUpperCase().contains("WINWORD") | Converts a request to upper case and then filters for user agent containing WINWORD. |
| request.userAgent.contains("WinWord") OR request.userAgent.contains("Windows-AzureAD-Authentication-Provider") | Filters a request for user agent containing WinWord or Windows-AzureAD-Authentication-Provider. |
| request.userAgent.contains("compatible;") AND request.userAgent.contains("MSIE 7") | Filters a request for user agent containing compatible and MSIE 7. |
Bad examples
| Expression | What it does |
|---|---|
| request.userAgent.contains("") | Matches all requests. |
| request.userAgent.contains() | Invalid expression. |