Security
Authentication and authorization for REST APIs.
Last updated
Authentication and authorization for REST APIs.
Last updated
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.
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
Once you have defined a secure endpoint, you will need to provide authentication and authorization to access the endpoint.
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.
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.
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.
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.
