featureRolloutPolicy resource type

Namespace: microsoft.graph

Caution

The featureRolloutPolicy API moved from /directory/featureRolloutPolicies to /policies/featureRolloutPolicies on March 5, 2021. The previous /directory/featureRolloutPolicies endpoint stopped returning returning data after June 30, 2021.

Important

APIs under the /beta version in Microsoft Graph are subject to change. Use of these APIs in production applications is not supported. To determine whether an API is available in v1.0, use the Version selector.

Represents a feature rollout policy associated with a directory object. Creating a feature rollout policy helps tenant administrators to pilot features of Microsoft Entra ID with a specific group before enabling features for entire organization. This minimizes the impact and helps administrators to test and rollout authentication related features gradually.

The following are limitations of feature rollout:

  • Each feature supports a maximum of 10 groups.
  • The appliesTo field only supports groups.
  • Dynamic groups and nested groups aren't supported.

For more information about staged rollout, see How to configure staged rollout in Microsoft Entra ID.

Methods

Method Return Type Description
List featureRolloutPolicy Retrieve a list of featureRolloutPolicy objects.
Get featureRolloutPolicy Retrieve the properties and relationships of featurerolloutpolicy object.
Create featureRolloutPolicy Create a new featureRolloutPolicy object.
Update featureRolloutPolicy Update the properties of featurerolloutpolicy object.
Delete None Delete a featureRolloutPolicy object.
Create applies to directoryObject Assign a directoryObject to feature rollout.
Delete applies to None Remove a directoryObject from feature rollout.

Properties

Property Type Description
description String A description for this feature rollout policy.
displayName String The display name for this feature rollout policy.
feature stagedFeatureName Possible values are: passthroughAuthentication, seamlessSso, passwordHashSync, emailAsAlternateId, unknownFutureValue, certificateBasedAuthentication. You must use the Prefer: include-unknown-enum-members request header to get the following value or values in this evolvable enum: certificateBasedAuthentication. For more information about the prerequisites for the enabled features, see Prerequisites for enabled features.
id String Read-only.
isAppliedToOrganization Boolean Indicates whether this feature rollout policy should be applied to the entire organization.
isEnabled Boolean Indicates whether the feature rollout is enabled.

Prerequisites for enabled features

The following are prerequisites for each of the features that are currently supported for rollout using this rollout policy.

Passthrough Authentication

  • Identify a server running Windows Server 2012 R2 or later where you want the PassthroughAuthentication Agent to run. Ensure that the server is domain-joined, can authenticate selected users with Active Directory, and can communicate with Microsoft Entra ID on outbound ports / URLs.
  • Download & install the Microsoft Entra Connect Authentication Agent on the server.
  • To enable high availability, install additional Authentication Agents on other servers as described here.
  • Ensure that you've configured your Smart Lockout settings appropriately. This is to ensure that your users' on-premises Active Directory accounts don't get locked out by bad actors.

SeamlessSso

PasswordHashSync

  • Enable PasswordHashSync from the "Optional features" page in Microsoft Entra Connect.

EmailAsAlternateId

  • Associate alternate email with user accounts.

Relationships

Relationship Type Description
appliesTo directoryObject collection Nullable. Specifies a list of directoryObject resources that feature is enabled for.

JSON representation

The following JSON representation shows the resource type.

{
  "description": "String",
  "displayName": "String",
  "feature": "string",
  "id": "String (identifier)",
  "isAppliedToOrganization": false,
  "isEnabled": true
}