Allow or deny custom clients in Office 365 sign-on policy

Use 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 don't support or trust. Alternatively, you can use this filter to only allow clients you trust. It gives you more granular control over the clients that get access to your Office 365 app.

Note

Sign-on policy rules to filter custom clients aren't migrated from Classic Engine to Okta Identity Engine. If you're migrating your Office 365 app instance to Okta Identity Engine, you need to recreate these rules. See Office 365 Custom User Agent.

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:

  1. Go to the Sign On tab. Under User authenticationAuthentication policy, click View policy details. (Alternatively, you can access this by going to SecurityAuthentication PoliciesMicrosoft Office 365Add Rule.)
  2. In the App Rule window, go to the If section of And The following custom expression is true.

  3. Enter a custom expression using Okta Expression Language to allow or deny a client. See Examples.

  4. Complete other sections as appropriate and click Save. See Office 365 sign-on rules options.
  5. 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.
  6. 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:

Note

String operations in Okta Expression Language are case-sensitive. To write a condition that ignores the case, convert the user agent value to the upper or lower case before the comparison.

Good examples

Expression What it does
request.userAgent.contains("WinWord") Filters a request for a user agent containing WinWord.
request.userAgent.toLowerCase().contains("winword") Converts a request to lowercase and then filters for the user agent containing winword.
request.userAgent.toUpperCase().contains("WINWORD") Converts a request to uppercase and then filters for user agent containing WINWORD.
request.userAgent.contains("WinWord") OR request.userAgent.contains("Windows-AzureAD-Authentication-Provider") Filters a request for a 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.

Related topics