Security
Authentication and authorization for REST APIs.
This feature requires a license.
REST API authentication requires a Universal API license. Once enabled, you will be able to enforce authentication and authorization on your endpoints.
Defining Secure Endpoints
You can define secure endpoints in the UI by enabling authentication.
You can also define secure endpoints using the .universal/endpoints.ps1
file or the Management API using New-PSUEndpoint
.
When authentication is enabled, it will enforce the use of one of the configured authentication methods. APIs support the following methods.
JWT App Tokens
Windows Authentication
Cookie Authentication
Accessing Secure Endpoints
Once you have defined a secure endpoint, you will need to provide authentication and authorization to access the endpoint.
Authenticating with tokens
Note that if you are hosting in IIS and do not have Anonymous Authentication enabled, you will not be able to pass app tokens to the PowerShell Universal server.
To authenticate with tokens, first, you need generate a new app token for use. You can use the Grant-PSUAppToken
cmdlet to do so remotely or you can create an app token in the UI using the Settings Security AppTokens tab.
Click Grant App Token to create a new one.
Once you have created your app token, you can now use it to authenticate against the secure endpoint. To do so, pass the Authorization header along with the request.
Authenticating with Windows Authentication
To authenticate with Windows Authentication, you can use the -UseDefaultCredentials
parameter of Invoke-RestMethod
and Invoke-WebRequest
. This will perform negotiate authentication whether you are running inside IIS or a service.
Authenticating with Cookies
To authenticate with cookies, you will first need to call the login API to receive a valid cookie from the system. You can use Invoke-WebRequest
to do so. Pass the user name and password as the body. Specify the -SessionVariable
parameter to establish a session.
Once you have successfully authenticated, you can use your $mySession
variable to call secure endpoints.
Enforcing Roles
In addition to creating endpoints that require authentication, you can also enforce roles by define a role in the New-PSUEndpoint
cmdlet or by selecting one in the UI. If a role is selected, it's possess the role.
Windows and Cookie authentication will assign roles based on the Identity of the user and the role policies as they are applied.
JWT app tokens will use the role that was defined when they were generated.
Related Cmdlets
Last updated