> For the complete documentation index, see [llms.txt](https://docs.devolutions.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.devolutions.net/powershell-universal/api/security.md). # Security Secure PowerShell Universal REST API endpoints with token, Windows, and cookie authentication, then enforce role-based authorization for each request. 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 will endpoint authentication and authorization under the Security tab of an endpoint's properties. You can also define secure endpoints using the `.universal/endpoints.ps1` file or the Management API using `New-PSUEndpoint`. ```powershell New-PSUEndpoint -Url '/endpoint' -Method 'GET' -Endpoint { "Hello, world!" } -Authentication ``` 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 * Basic 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 {% hint style="warning" %} 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. {% endhint %} 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 grant a token to the currently signed-in user under **User menu > User Settings > Tokens**. 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. ```powershell Invoke-RestMethod http://localhost:5000/auth -Headers @{ Authorization = "******" } ``` #### Custom Authorization Header PowerShell Universal provides a custom authorization header to support scenarios with reverse proxies that may require their own Authorization header. If the `X-PSU-Authorization` header is specified, PSU will ignore the `Authorization` header and use this header instead. ``` Invoke-RestMethod http://localhost:5000/auth -Headers @{ Authorization = "******" 'X-PSU-Authorization' = '******' } ``` ### Authenticating with Windows Authentication To authenticate with [Windows Authentication](/powershell-universal/security/enterprise-security/windows-sso.md#windows-authentication-in-iis), 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. ```powershell Invoke-RestMethod http://localhost:5000/auth -UseDefaultCredentials ``` ### 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. ```powershell Invoke-WebRequest http://localhost:5000/api/v1/signin -Body (@{ UserName = "Admin" Password = "Any" } | ConvertTo-Json) -ContentType 'application/json' -SessionVariable mySession -Method POST ``` Once you have successfully authenticated, you can use your `$mySession` variable to call secure endpoints. ```powershell Invoke-WebRequest http://localhost:5000/auth -WebSession $mySession ``` ## 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. ## Execution Roles By using the Execution Roles property, you can set what roles are assigned as the API endpoint is executing. By default, the endpoint will execute based on the roles of the caller. In some scenarios, for example when using Secrets with Roles, you may want to provide additional roles that the caller may not posses. Execution Roles do not require that the API authentication be enabled. ## API * [New-PSUEndpoint](/powershell-universal/powershell-commands/new-psuendpoint.md) * [Get-PSUEndpoint](/powershell-universal/powershell-commands/get-psuendpoint.md) * [Remove-PSUEndpoint](/powershell-universal/powershell-commands/remove-psuendpoint.md) * [New-PSUApiResponse](/powershell-universal/powershell-commands/new-psuapiresponse.md) * [Set-PSUSetting](/powershell-universal/powershell-commands/set-psusetting.md) ### See also * [Devolutions Academy – Creating a variable endpoint](https://academy.devolutions.net/student/activity/3466016-creating-a-variable-endpoint) * [Devolutions Academy – Creating a query string endpoint](https://academy.devolutions.net/student/activity/3466018-creating-a-query-string-endpoint) * [Devolutions Academy – Creating an endpoint that accepts a body](https://academy.devolutions.net/student/activity/3466020-creating-an-endpoint-that-accepts-a-body) * [Devolutions Academy – Different route methods](https://academy.devolutions.net/student/activity/3466022-different-route-methods) * [Devolutions Academy – Authentication](https://academy.devolutions.net/student/path/3465905/activity/5612255) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.devolutions.net/powershell-universal/api/security.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.