REST API Authentication

Universal Dashboard is now a part of PowerShell Universal. This documentation is for reference to the v2 version of Universal Dashboard and is no longer maintained. PowerShell Universal Documentation can be found here.

REST API Authentication

Updated: 3/3/2018 Required Version: 1.5.0

Not available in Community Edition.

JSON Web Tokens

REST API authentication takes advantage of JSON web tokens to provide a mechanism to authentication users and applications again a REST API. Tokens can be granted on the command line or through an endpoint and then provided as part of the Authorization header when making future requests.

Visit JWT.IO to learn more about JSON web tokens

Basic Authentication

To setup basic authentication, you can use New-UDAuthenticationMethod with Start-UDRestApi. Simply pass a new authentication method to the -AuthenticationMethod parameter of Start-UDRestApi.

$Method = New-UDAuthenticationMethod
Start-UDRestApi -AuthenticationMethod $Method ...

The REST API is now protected from requests that do not contain a valid Bearer token. To generate a token for the API, you can use Grant-UDJsonWebToken.

$Token = Grant-UDJsonWebToken -UserName 'Adam'

The token can then be used with Invoke-RestMethod or another HTTP tool as part of the headers.

Invoke-RestMethod -Headers @{ Authorization = "Bearer $Token" }

Configuration Authentication

New-UDAuthenticationMethod offers several configuration options that provide additional security when configuring the protection for a REST API. You will want to override the -SigningKey parameter. It defaults to default_signing_key. Changing this value ensures that the signing key is unique for your REST API.

$Method = New-UDAuthenticationMethod -SigningKey "SuperSecretKey"
Start-UDRestApi -AuthenticationMethod $Method ...

When changing the signing key, audience or issuer, make sure to specify the same value when using Grant-UDJsonWebToken

$Token = Grant-UDJsonWebToken -UserName 'Adam' -SigningKey "SuperSecretKey"

Enabling Authentication through the REST API

To enable authentication through the REST API, you can specify an endpoint based authentication method with New-UDAuthenticationMethod. When you specify the result of New-UDAuthenticationResult you can include a token that the user can then use for Bearer authentication for other REST API calls. The endpoint will receive a PSCredential object that you can then use to authenticate in whatever means is necessary.

$AuthMethods = @()
$AuthMethods += New-UDAuthenticationMethod -Endpoint {
#Perform authentication here
$Token = Grant-UDJsonWebToken -Identity $Credential.UserName -Issuer "IMS"
New-UDAuthenticationResult -Success -UserName $Credential.UserName -Token $Token
$AuthMethods += New-UDAuthenticationMethod -Issuer "IMS"
$Server = Start-UDRestApi -Port 10001 -Endpoint @(
New-UDEndpoint -Url "user/me" -Method "GET" -Endpoint {
@($User) | ConvertTo-Json
)-AuthenticationMethod $AuthMethods

From there, users can authenticate again /login to retrieve a token and then use it on subsequent requests.

$Token = Invoke-RestMethod -Uri http://localhost:10001/api/login -Method POST -Body @{ UserName = "Adam"; Password = "Test" }
$users = Invoke-RestMethod -Uri http://localhost:10001/api/user/me -Headers @{ Authorization = "Bearer $($Token.Token)" }

Configuring Tokens

Grant-UDJsonWebToken provides several configuration options for tokens. You can specify expiration as well as user names. Default expiration is 1 year. User names are available within UDEndpoints that by using the $User variable.

$Token = Grant-UDJsonWebToken -UserName 'Adam' -Expiry (Get-Date).AddDays(10)

Web tokens can include any set of information that you want to include with the user's token by specifying a hashtable and providing it to the -Payload parameter. You can then use the ConvertTo-UDJsonWebToken to convert a string representation of a JSON web token to an object.

PS F:\universal-dashboard-documentation> $Token = Grant-UDJsonWebToken -Identity 'Adam' -Payload @{Account = 'Billing'}
PS F:\universal-dashboard-documentation> ConvertTo-UDJsonWebToken -Token $Token
Actor :
Audiences : {UniversalDashboard}
Claims : { Adam,
de19e3e8-2be5-4ad6-a14c-b0988979773c, sub: UniversalDashboard, nbf: 1571843025…}
EncodedHeader : eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9
EncodedPayload : eyJodHRwOi8vc2NoZW1hcy54bWxzb2FwLm9yZy93cy8yMDA1LzA1L2lkZW50aXR5L2NsYWltcy9uYW1lIjoiQWRhbSIsImh0dHA6Ly9zY2hlbWFzLnhtbHNvYXAub3Jn
Header : {[alg, HS256], [typ, JWT]}
Id :
Issuer :
Payload : {[, Adam],
[, de19e3e8-2be5-4ad6-a14c-b0988979773c], [sub, UniversalDashboard],
[nbf, 1571843025]…}
InnerToken :
RawAuthenticationTag :
RawCiphertext :
RawData : eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJodHRwOi8vc2NoZW1hcy54bWxzb2FwLm9yZy93cy8yMDA1LzA1L2lkZW50aXR5L2NsYWltcy9uYW1lIjoiQWRhbSI
RawEncryptedKey :
RawInitializationVector :
RawHeader : eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9
RawPayload : eyJodHRwOi8vc2NoZW1hcy54bWxzb2FwLm9yZy93cy8yMDA1LzA1L2lkZW50aXR5L2NsYWltcy9uYW1lIjoiQWRhbSIsImh0dHA6Ly9zY2hlbWFzLnhtbHNvYXAub3Jn
RawSignature : Hfl8YPzLmYAxXpy2_mqiRMvjyHwSAr2ZZy6EspdEvg0
SecurityKey :
SignatureAlgorithm : HS256
SigningCredentials :
EncryptingCredentials :
SigningKey :
Subject : UniversalDashboard
ValidFrom : 10/23/2019 3:03:45 PM
ValidTo : 10/23/2020 3:03:45 PM
PS F:\universal-dashboard-documentation> $Object = ConvertTo-UDJsonWebToken -Token $Token
PS F:\universal-dashboard-documentation> $Object.Payload
Key Value
--- ----- Adam de19e3e8-2be5-4ad6-a14c-b0988979773c
sub UniversalDashboard
nbf 1571843025
exp 1603465425
aud UniversalDashboard
Account Billing