New-PPRBACRoleAssignment

Module:

Microsoft.PowerPlatform.EnterprisePolicies Module

Creates a Power Platform role-based access control (RBAC) role assignment.

Syntax

TenantScope (Default)

New-PPRBACRoleAssignment
    -PrincipalObjectId <String>
    -PrincipalType <AuthorizationPrincipalType>
    -Role <String>
    -TenantId <String>
    [-ClientId <String>]
    [-Endpoint <PPEndpoint>]
    [-ForceAuth]
    [-RefreshRoles]
    [<CommonParameters>]

EnvironmentScope

New-PPRBACRoleAssignment
    -PrincipalObjectId <String>
    -PrincipalType <AuthorizationPrincipalType>
    -Role <String>
    -TenantId <String>
    -EnvironmentId <String>
    [-ClientId <String>]
    [-Endpoint <PPEndpoint>]
    [-ForceAuth]
    [-RefreshRoles]
    [<CommonParameters>]

EnvironmentGroupScope

New-PPRBACRoleAssignment
    -PrincipalObjectId <String>
    -PrincipalType <AuthorizationPrincipalType>
    -Role <String>
    -TenantId <String>
    -EnvironmentGroupId <String>
    [-ClientId <String>]
    [-Endpoint <PPEndpoint>]
    [-ForceAuth]
    [-RefreshRoles]
    [<CommonParameters>]

Description

This cmdlet creates a role assignment for a principal (user, group, or application) to grant permissions via Power Platform RBAC. The role can be scoped at the tenant, environment, or environment group level.

If -ClientId isn't specified, the cmdlet uses the cached ClientId from a previous call to New-PPAuthorizationApplication or any Power Platform RBAC cmdlet that was given -ClientId explicitly. When -ClientId is provided, it is stored in the cache for future use.

The Role parameter accepts the role definition name as returned by the Power Platform Authorization API, such as "Power Platform Reader". Use -RefreshRoles to update the cached list of available roles.

Examples

EXAMPLE 1

New-PPRBACRoleAssignment -ClientId "00000000-0000-0000-0000-000000000000" -PrincipalObjectId "00000000-0000-0000-0000-000000000001" -PrincipalType User -Role "Power Platform Reader" -TenantId "00000000-0000-0000-0000-000000000002"

Creates a tenant-scoped role assignment for a user with the "Power Platform Reader" role.

EXAMPLE 2

New-PPRBACRoleAssignment -ClientId "00000000-0000-0000-0000-000000000000" -PrincipalObjectId "00000000-0000-0000-0000-000000000001" -PrincipalType Group -Role "Power Platform Reader" -TenantId "00000000-0000-0000-0000-000000000002" -EnvironmentId "00000000-0000-0000-0000-000000000003"

Creates an environment-scoped role assignment for a group.

EXAMPLE 3

New-PPRBACRoleAssignment -ClientId "00000000-0000-0000-0000-000000000000" -PrincipalObjectId "00000000-0000-0000-0000-000000000001" -PrincipalType ApplicationUser -Role "Power Platform Reader" -TenantId "00000000-0000-0000-0000-000000000002" -EnvironmentGroupId "00000000-0000-0000-0000-000000000004"

Creates an environment group-scoped role assignment for an application.

EXAMPLE 4

New-PPRBACRoleAssignment -ClientId "00000000-0000-0000-0000-000000000000" -PrincipalObjectId "00000000-0000-0000-0000-000000000001" -PrincipalType User -Role "Power Platform Reader" -TenantId "00000000-0000-0000-0000-000000000002" -RefreshRoles

Creates a role assignment while forcing a refresh of the cached role definitions.

Parameters

-ClientId

The application (client) ID of the app registration

Parameter properties

Type:	String
Default value:	None
Supports wildcards:	False
DontShow:	False

Parameter sets

(All)

Position:	Named
Mandatory:	False
Value from pipeline:	False
Value from pipeline by property name:	False
Value from remaining arguments:	False

-Endpoint

The BAP endpoint to connect to

Parameter properties

Type:	PPEndpoint
Default value:	Prod
Accepted values:	unknown, tip1, tip2, prod, usgovhigh, dod, china
Supports wildcards:	False
DontShow:	False

Parameter sets

(All)

Position:	Named
Mandatory:	False
Value from pipeline:	False
Value from pipeline by property name:	False
Value from remaining arguments:	False

-EnvironmentGroupId

The environment group ID for environment group-scoped assignments

Parameter properties

Type:	String
Default value:	None
Supports wildcards:	False
DontShow:	False

Parameter sets

EnvironmentGroupScope

Position:	Named
Mandatory:	True
Value from pipeline:	False
Value from pipeline by property name:	False
Value from remaining arguments:	False

-EnvironmentId

The environment ID for environment-scoped assignments

Parameter properties

Type:	String
Default value:	None
Supports wildcards:	False
DontShow:	False

Parameter sets

EnvironmentScope

Position:	Named
Mandatory:	True
Value from pipeline:	False
Value from pipeline by property name:	False
Value from remaining arguments:	False

-ForceAuth

Force re-authentication instead of reusing existing session

Parameter properties

Type:	SwitchParameter
Default value:	False
Supports wildcards:	False
DontShow:	False

Parameter sets

(All)

Position:	Named
Mandatory:	False
Value from pipeline:	False
Value from pipeline by property name:	False
Value from remaining arguments:	False

-PrincipalObjectId

The object ID of the principal to assign the role to

Parameter properties

Type:	String
Default value:	None
Supports wildcards:	False
DontShow:	False

Parameter sets

(All)

Position:	Named
Mandatory:	True
Value from pipeline:	False
Value from pipeline by property name:	False
Value from remaining arguments:	False

-PrincipalType

The type of principal

Parameter properties

Type:	AuthorizationPrincipalType
Default value:	None
Accepted values:	User, Group, ApplicationUser
Supports wildcards:	False
DontShow:	False

Parameter sets

(All)

Position:	Named
Mandatory:	True
Value from pipeline:	False
Value from pipeline by property name:	False
Value from remaining arguments:	False

-RefreshRoles

Force re-fetch of role definitions from the API

Parameter properties

Type:	SwitchParameter
Default value:	False
Supports wildcards:	False
DontShow:	False

Parameter sets

(All)

Position:	Named
Mandatory:	False
Value from pipeline:	False
Value from pipeline by property name:	False
Value from remaining arguments:	False

-Role

The role definition name to assign (e.g., 'Power Platform Reader')

Parameter properties

Type:	String
Default value:	None
Supports wildcards:	False
DontShow:	False

Parameter sets

(All)

Position:	Named
Mandatory:	True
Value from pipeline:	False
Value from pipeline by property name:	False
Value from remaining arguments:	False

-TenantId

The Azure AD tenant ID

Parameter properties

Type:	String
Default value:	None
Supports wildcards:	False
DontShow:	False

Parameter sets

(All)

Position:	Named
Mandatory:	True
Value from pipeline:	False
Value from pipeline by property name:	False
Value from remaining arguments:	False

CommonParameters

This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.

Outputs

System.Management.Automation.PSCustomObject

Returns the created role assignment object from the API.