Scope
Users running PowerShell Universal v5 or later that are attempting to call cmdlets that interact with PowerShell Universal management APIs.
Problem
Various errors from PowerShell Universal cmdlets referring to gRPC.
Root Cause
The use of gRPC, along with authorization changes, in v5 may require additional configuration.
gRPC
gRPC is an interprocess communication framework for high performance remote procedure calls. It runs natively on HTTP2 and takes advantage of features of the protocol, like trailing headers. Some web server configurations, such as insecure HTTP servers, do not support HTTP2. In these configurations, gRPC-Web can be used to send messages using HTTP REST endpoints and JSON to support the limitations of HTTP 1.1.
gRPC is the communication method for all RPC calls within PowerShell Universal. This includes both internal communications as well as the use of the Universal module. This allows for a single service layer within the application and avoids the need to define both gRPC services and HTTP endpoints.
The PowerShell Universal module will attempt to run in different modes depending on the server it is connecting to. To determine the connection type, it will try the following:
1. If HTTP or Windows Authentication, use gRPC-Web
2. If HTTPS, attempt to use gRPC
3. If gRPC fails, attempt to use gRPC-Web
4. If gRPC-Web fails, provide grpc-status trailing header and attempt gRPC-Web again
5. If gRPC-Web fails again, throw an exception
Once a successful gRPC connection has been made, the module will continue to use that method without trying the above connection steps for the life of the process.
Authorization
PowerShell Universal provides a new authorization system based on privileges. All roles are granted privileges. Built in roles have privileges defined that correspond to the feature group and access that is provided to them. By default, the PowerShell Universal cmdlets are subject to these privileges, even when running within PowerShell Universal.
Common Issues
gRPC Unauthorized
An authorized error is the result of the authorization system rejecting the request. This is because the current user does not have access to the resource of the request was not authorized at all. When using scheduled scripts, there is no user context so an unauthorized error will always happen when no app token is specified and the system is running in Strict security model. While the error may include gRPC in the message, it is unrelated to gRPC itself and actually related to the authorization system within PowerShell Universal.
Specify An App Token
One way to avoid this issue is to provide an app token to the cmdlet you are calling. This will ensure that the cmdlet has access of the app token. When calling cmdlets within the admin console or within apps, will result in the current privileges of the executing user will use be used. For example, if an Operator user is using an app and clicks a button that calls Invoke-PSUScript, it will use the context of that user. If the user doens't have access to the script, they will receive an unauthorized error. If an app token is specified, it will use the context of the app token.
Change to Permissive Security Model
By default, PowerShell Universal runs in the Secure security model for the management API. This enforces all cmdlet calls that happen within PSU will use the context of the current user access.
Changing to the Permissive security model reverts to PowerShell Universal v4 behavior where cmdlet calls within the PSU environment do not have authorization privileges enforced. External calls to the PowerShell Universal system are always subject to authentication and authorization.
gRPC Certificate Error
While not directly a gRPC issue, the error message may contain gRPC within the exception. This issue is the result of the use of untrusted or self-signed certificates on the server. PowerShell Universal cmdlets will throw an exception if the certificate is considered invalid.
-TrustCertificate Parameter
All Universal cmdlets have a -TrustCertificate parameter that can be defined to bypass this error.
TrustCertificate AppSettings.Json Property
Invalid URI
When call cmdlets within PowerShell Universal, an Invalid URI error may be thrown. This is typically the case when PowerShell Universal is running behind a load balancer, reverse proxy or the API URL is incorrect in appsettings.json.
Update API URL in appsettings.json