Posted on Leave a comment

Understanding Authorization Policies in Universal Dashboard

This post discusses features available in Universal Dashboard

Authorization policies in Universal Dashboard allow you to control the content that particular users have access to. You can limit access to the entire dashboard, to pages themselves or even to individual controls. In this post we will go over how to use authorization policies to create secure dashboards.

The Basics

Authorization policies are tightly linked with authentication. After authentication takes place, the user has a series of claims associated with their session. These claims can be evaluated to determine whether a user has access to a particular resource.

Depending on how you authenticate to your dashboard, the claims the user has will be different. This means that it’s necessary to understand the claim system in order to effectively take advantage of authorization policies. In this post, we will use Azure Active Directory authentication as our example.

Configuring Azure Active Directory

To configure Universal Dashboard for Azure Active Directory authentication, we need to use the New-UDAuthenticationMethod cmdlet alongside the New-UDLoginPage cmdlet. You’ll need to get your ClientId, Instance URI, Domain and TenantId from the Azure portal. You’ll also need to configure an application registration within your directory. The process for that is covered in this document.

Once you’ve registered your application, you can now write the script for your dashboard. You’ll need to use the following script to do so.

$AuthenticationMethod = New-UDAuthenticationMethod -ClientId '1111e4b-45aa-43bb-beae-304028707777' -Instance https://login.microsoftonline.com -Domain ironmansoftware.onmicrosoft.com -TenantId '11111c97-4b76-4470-a736-8481d71111111'
$LoginPage = New-UDLoginPage -AuthenticationMethod $AuthenticationMethod 

You can now pass the $LoginPage variable to your dashboard and start it. Make sure to listen on the same port as the one you configured in AzureAD.

$Dashboard = New-UDDashboard -Title "Authorization" -Content {

} -LoginPage $LoginPage 
Start-UDDashboard -Port 10000 -Dashboard $Dashboard -AllowHttpForLogin

When visiting your dashboard, you should now see a login page with a “Sign in with Azure Active Directory” button.

Azure AD Login

Once you click the button, you will be forwarded to the Microsoft login page for your directory. Once you login, you will be forwarded back to Universal Dashboard. You should now see the home page.

Authorized Home Page

Configuring an Authorization Policy

To configure an authorization policy, you need to use the New-UDAuthorizationPolicy cmdlet. This cmdlet accepts a script block that will run to evaluate whether the current user has access to the resource they are trying to retrieve.

An authorization policy simply needs to return $true or $false. If the policy throws an error, it is considered $true so ensure that you wrap your code in a try\catch if you do not wish to see this behavior.

The most basic authorization policy is as follows.

$AuthorizationPolicy = New-UDAuthorizationPolicy -Name "Login" -Endpoint {
    $true
}

This authorization policy always returns true and and is named “Login”. You will use this name whenever you want to enforce the authorization policy.

You can now ensure your dashboard uses this authorization policy by passing it to New-UDLoginPage.

$LoginPage = New-UDLoginPage -AuthenticationMethod $AuthenticationMethod -AuthorizationPolicy $AuthorizationPolicy

Using the Authorization Policy

To use the authorization policy, you need to assign it to either a page or to take advantage of the Get-UDAuthorizationPolicy cmdlet. When you pass the name of the authorization policy to New-UDPage, it will ensure that only users that pass the authorization policy will have access to that page. When you invoke Get-UDAuthorizationPolicy from within your dashboard, you will get all the authorization policies that the user has passed.

To use it on a page, simply pass the name of the policy to the -AuthorizationPolicy parameter of New-UDPage. This parameter accepts an array of policies if you desire.

As you can see below, we have a page that has an authorization policy assigned and one that does not.

$Settings = New-UDPage -Name Settings -AuthorizationPolicy "Login" -Content {

}
$HomePage = New-UDPage -Name "Home" -Content {

}

$Dashboard = New-UDDashboard -Title "Authorization" -Pages @($HomePage, $Settings) -LoginPage $LoginPage 

When you login, you’ll notice that you have access to both pages. If you go back and change your authentication policy to return $false, you will no longer have access to the settings page. If you try to access the page directly by URL, it will return Page Not Found.

You can also use authorization policies to hide controls on your dashboard. To do this, you can use Get-UDAuthorizationPolicy and then check to see whether a particular policy is returned before returning a control. This needs to be done dynamically so it needs to be in an endpoint script block rather than content.

If I modify my home page to show two columns of controls, I can use Get-UDAuthorizationPolicy to check to see if I should return a control before showing it to the user.

$HomePage = New-UDPage -Name "Home" -Content {
    New-UDRow -Endpoint {
        New-UDColumn -Size 6 -Content {
            New-UDHeading -Text 'Super Public Info' -Size 1
        }
        New-UDColumn -Size 6 -Content {
            $Policy = Get-UDAuthorizationPolicy
             if ($AuthPolicy -contains 'Login') {
                New-UDHeading -Text 'Super Secret Info' -Size 1
            }  
        }
    }
}

If you run the dashboard now, you’ll see that the super secret info is not shown. If you again change your authorization policy back to return $true, you will see the super secret info. You can use this technique anywhere an Endpoint parameter is present.

Checking Claims

Authorization policies would be pretty useless if you didn’t actually check some information about the user. To do this, we take advantage of the claims provided by the authentication mechanism we are using. In this case, Azure Active Directory is returning a bunch of claim information to us. To access this information, we can adjust our authorization policy endpoint to accept a $User parameter. This variable is an instance of an IClaimsPrincipal class. You can use this variable to check whether a user has particular rights.

In our authorization policy, we can now use that variable and call methods such as HasClaim to validate whether a user has a particular claim.

$AuthorizationPolicy = New-UDAuthorizationPolicy -Name "Login" -Endpoint {
    param($User)
    $User.HasClaim("groups", "b69421c1-381f-41e9-9105-1ed85768cde1")
}

In my environment, the GUID listed is the Object ID of a group that the user is a part of.

Azure AD Group

HasClaim will return true if the user is part of that group. Now, when a user that logs into the dashboard is part of the Dashboard Users group, they will have access to the Settings page and the Super Secret Info control.

Debugging Claim Checks

One of the problems with claims is that they are cryptic and change per authentication mechanism. In order to accurately check claims you will likely want to evaluate the $User variable in the debugger to see what claims are present when a user logins in. To do this, we need to call Wait-Debugger in the New-UDAuthorizationPolicy endpoint.

 $AuthorizationPolicy = New-UDAuthorizationPolicy -Name "Login" -Endpoint {
    param($User)

    Wait-Debugger
    $User.HasClaim("groups", "e1b6e95e-6241-4a1a-886d-d5fc0f606f99")
}

When you go to login to your dashboard, you will now see only some of it load. Additionally, the console output will indicate that it has entered debug mode.

Debugging Authorization Policies

If you now type the $User variable and press enter, you will see the object is present in the runspace. You’ll be able to dump the claims that are currently set on the object. This will provide you insight into how to correctly check for the claims of the user.

[DBG]: PS C:\Users\adamr>> $User.Claims

Issuer         : https://sts.windows.net/3ee40c97-4b76-4470-a736-8481d7a2ed87/
OriginalIssuer : https://sts.windows.net/3ee40c97-4b76-4470-a736-8481d7a2ed87/
Properties     : {[http://schemas.xmlsoap.org/ws/2005/05/identity/claimproperties/ShortTypeName, amr]}
Subject        : System.Security.Claims.ClaimsIdentity
Type           : http://schemas.microsoft.com/claims/authnmethodsreferences
Value          : pwd
ValueType      : http://www.w3.org/2001/XMLSchema#string

Issuer         : https://sts.windows.net/3ee40c97-4b76-4470-a736-8481d7a2ed87/
OriginalIssuer : https://sts.windows.net/3ee40c97-4b76-4470-a736-8481d7a2ed87/
Properties     : {}
Subject        : System.Security.Claims.ClaimsIdentity
Type           : groups
Value          : b69421c1-381f-41e9-9105-1ed85768cde1
ValueType      : http://www.w3.org/2001/XMLSchema#string

Issuer         : https://sts.windows.net/3ee40c97-4b76-4470-a736-8481d7a2ed87/
OriginalIssuer : https://sts.windows.net/3ee40c97-4b76-4470-a736-8481d7a2ed87/
Properties     : {}
Subject        : System.Security.Claims.ClaimsIdentity
Type           : name
Value          : Adam Driscoll
ValueType      : http://www.w3.org/2001/XMLSchema#string

Conclusion

In this post we went through how to configure your dashboard to use authentication and authorization policies to validate user claims against Azure Active Directory. The same process holds true for configuration policies for other authentication methods. Check out the docs to learn more.