Token Role Functions

CHANGELOG.md

@@ -3,6 +3,11 @@
 
 ## Unreleased
 
+### 1.7.1
+* Organizes some token-related functions into sub-folders (accessors, authentication, and roles).
+* Adds support for interacting with token roles: creating, reading, updating, listing and deleting token roles.
+* Adds `SupportsShouldProcess` to `New-` and `Update-` token role functions.
+
 ### 1.6.0
 * Adds support for functions that query Vault API endpoints that utilize the LIST method.
   * Adds Show-VaultTokenAccessor, a command that lists all active token accessors.

psVaultUtils/Public/Tokens/New-VaultToken.ps1

@@ -168,13 +168,15 @@ function New-VaultToken {
         [Parameter(
             Position = 7
         )]
+        [ValidateScript({ $_ -match "^\d+$|^\d+[smh]$" })]
         [Alias('TTL')]
         [String] $TimeToLive,
 
         #Specifies that a token will have a max TimeToLive set on it. A token with a configured Max TimeToLive cannot be renewed past the specified value.
         [Parameter(
             Position = 8
         )]
+        [ValidateScript({ $_ -match "^\d+$|^\d+[smh]$" })]
         [Alias('ExplicitMaxTTL')]
         [String] $ExplicitMaxTimeToLive,
 
@@ -196,6 +198,7 @@ function New-VaultToken {
         [Parameter(
             Position = 11
         )]
+        [ValidateScript({ $_ -match "^\d+$|^\d+[smh]$" })]
         [String] $Period,
 
         #Specifies that the created token should be an orphan (not be the child of a parent token).

psVaultUtils/Public/Tokens/Roles/Get-VaultTokenRole.ps1

@@ -0,0 +1,92 @@
+function Get-VaultTokenRole {
+<#
+.Synopsis
+    Retrieves information about a specified token role.
+
+.DESCRIPTION
+    Get-VaultTokenRole retrieves information about a token role, given the role name.
+
+.EXAMPLE
+    PS> Get-VaultTokenRole -RoleName 'log-rotate' -OutputType Json
+    {
+        "request_id":  "0b88b863-d4bb-bb5e-6c0f-317d73d86cf7",
+        "lease_id":  "",
+        "renewable":  false,
+        "lease_duration":  0,
+        "data":  {
+                    "allowed_policies":  [
+                                            "log-rotation"
+                                        ],
+                    "disallowed_policies":  [
+
+                                            ],
+                    "explicit_max_ttl":  0,
+                    "name":  "log-rotate",
+                    "orphan":  false,
+                    "path_suffix":  "",
+                    "period":  86400,
+                    "renewable":  true,
+                    "token_type":  "default-service"
+                },
+        "wrap_info":  null,
+        "warnings":  null,
+        "auth":  null
+    }
+
+#>
+    [CmdletBinding()]
+    param(
+        #Specifies the role whose configuration should be retrieved.
+        [Parameter(
+            Position = 0
+        )]
+        [String] $RoleName,
+
+        #Specifies how output information should be displayed in the console. Available options are JSON or PSObject.
+        [Parameter(
+            Position = 1
+        )]
+        [ValidateSet('Json','PSObject','Hashtable')]
+        [String] $OutputType = 'PSObject',
+
+        #Specifies whether or not just the token roles should be displayed in the console.
+        [Parameter(
+            Position = 2
+        )]
+        [Switch] $JustData
+    )
+
+    begin {
+        Test-VaultSessionVariable -CheckFor 'Address','Token'
+    }
+
+    process {
+        $uri = $global:VAULT_ADDR
+
+        $irmParams = @{
+            Uri    = "$uri/v1/auth/token/roles/$RoleName"
+            Header = @{ "X-Vault-Token" = $global:VAULT_TOKEN }
+            Method = 'Get'
+        }
+
+        try {
+            $result = Invoke-RestMethod @irmParams
+        }
+        catch {
+            throw
+        }
+
+        $formatParams = @{
+            InputObject = $result
+            DataType    = 'data'
+            JustData    = $JustData.IsPresent
+            OutputType  = $OutputType
+        }
+
+        Format-VaultOutput @formatParams
+    }
+
+    end {
+
+    }
+}

psVaultUtils/Public/Tokens/Roles/New-VaultTokenRole.ps1

@@ -0,0 +1,208 @@
+function New-VaultTokenRole {
+<#
+.Synopsis
+    Creates a new token role.    
+
+.DESCRIPTION
+    New-VaultTokenRole creates a new token role given a specified role name.
+
+    Roles enforce specific behavior when creating tokens that allow token functionality that is otherwise not available or would require sudo/root privileges to access. 
+    Role parameters, when set, override any provided options to the create endpoints.
+
+    The role name is also included in the token path, allowing all tokens created against a role to be revoked using the /sys/leases/revoke-prefix endpoint.
+
+.EXAMPLE
+    PS> New-VaultTokenRole -RoleName 'nomad' -AllowedPolicies "dev" -Renewable:$true -AllowedEntityAliases "web-entity-alias","app-entity-*" -BoundCIDRs "127.0.0.1/32","128.252.0.0/16"
+
+    This command does not produce any output.
+#>
+    [CmdletBinding(
+        SupportsShouldProcess = $true,
+        ConfirmImpact = 'Medium'  
+    )]
+    param(
+        #Specifies the name of the token role being created.
+        [Parameter(
+            Mandatory = $true,
+            Position = 0
+        )]
+        [String] $RoleName,
+
+        #Specifies an array of policies that a token assigned to this role is allowed to use.
+        [Parameter(
+            Position = 1
+        )]
+        [String[]] $AllowedPolicies,
+
+        #Specifies an array of policies that a token assigned to this role is not allowed to use. 
+        [Parameter(
+            Position = 2
+        )]
+        [String] $DisallowedPolicies,
+
+        #Specifies whether a token assigned to the role should be an orphan or not Orphaned tokens do not have a parent token.
+        [Parameter(
+            Position = 3
+        )]
+        [Switch] $Orphan,
+
+        #Specifies whether a token assigned to the role should be renewable or not.
+        [Parameter(
+            Position = 4
+        )]
+        [Bool] $Renewable = $true,
+
+        #Specifies that tokens created with this role will be given a defined path suffix in addition to the role name.
+        [Parameter(
+            Position = 5
+        )]
+        [String] $PathSuffix,
+
+        #Specifies a String or Json list of allowed entity alises.
+        [Parameter(
+            Position = 6
+        )]
+        [String[]] $AllowedEntityAliases,
+
+        #Specifies a list of CIDR blocks (IP addresses which can authenticate successfully).
+        [Parameter(
+            Position = 7
+        )]
+        [String[]] $BoundCIDRs,
+
+        #Specifies an explicit max TTL for tokens assigned to this role.
+        [Parameter(
+            Position = 8
+        )]
+        [ValidateScript({ $_ -match "^\d+$|^\d+[smh]$" })]
+        [Alias('ExplicitMaxTTL')]
+        [String] $ExplicitMaxTimeToLive,
+
+        #Specifies that tokens assigned to this role should not get the 'Default' policy.
+        [Parameter(
+            Position = 9
+        )]
+        [Switch] $NoDefaultPolicy,
+
+        #Specifies the number of uses a token assigned to this role should have.
+        [Parameter(
+            Position = 10
+        )]
+        [Alias('NumUses')]
+        [Int] $NumberOfUses = 0,
+
+        #Specifies a period of time set on the token role.
+        [Parameter(
+            Position = 11
+        )]
+        [ValidateScript({ $_ -match "^\d+$|^\d+[smh]$" })]
+        [String] $Period,
+
+        #Specifies the type of token that should be created.
+        [Parameter(
+            Position = 12
+        )]
+        [ValidateSet('Default','Service','Batch')]
+        [String] $TokenType
+    )
+
+    begin {
+        Test-VaultSessionVariable -CheckFor 'Address','Token'
+    }
+
+    process {
+        if (Get-VaultTokenRole -RoleName $RoleName -ErrorAction 'SilentlyContinue') {
+            Write-Error "The specified token role already exists. To modify a token role, use Update-VaultTokenRole."
+            return
+        }
+
+        $uri = $global:VAULT_ADDR
+
+        #region Build the Payload
+
+        $psobjPayload = @{}
+
+        $psObjPayload += @{ role_name = $RoleName }
+
+        if ($AllowedPolicies) {
+            $psobjPayload += @{ allowed_policies = @($AllowedPolicies) }
+        }
+
+        if ($DisallowedPolicies) {
+            $psobjPayload += @{ disallowed_policies = @($DisallowedPolicies) }
+        }
+
+        if ($Orphan) {
+            $psobjPayload += @{ orphan = $true }
+        }
+        else {
+            $psobjPayload += @{ orphan = $false }
+        }
+
+        if ($Renewable) {
+            $psobjPayload += @{ renewable = $true }
+        }
+        else {
+            $psobjPayload += @{ renewable = $false }
+        }
+
+        if ($PathSuffix) {
+            $psobjPayload += @{ path_suffix = $PathSuffix }
+        }
+
+        if ($AllowedEntityAliases) {
+            $psobjPayload += @{ allowed_entity_aliases = @($AllowedEntityAliases) }
+        }
+
+        if ($BoundCIDRs) {
+            $psobjPayload += @{ token_bound_cidrs = @($BoundCIDRs) }
+        }
+
+        if ($ExplicitMaxTimeToLive) {
+            $psobjPayload += @{ token_explicit_max_ttl = $ExplicitMaxTimeToLive }
+        }
+
+        if ($NoDefaultPolicy) {
+            $psobjPayload += @{ token_no_default_policy = $true }
+        }
+        else {
+            $psobjPayload += @{ token_no_default_policy = $false }
+        }
+
+        if ($NumberOfUses) {
+            $psobjPayload += @{ token_num_uses = $NumberOfUses }
+        }
+
+        if ($Period) {
+            $psobjPayload += @{ token_period = $Period }
+        }
+
+        if ($TokenType) {
+            $psobjPayload += @{ token_type = $TokenType }
+        }
+
+        #endregion
+
+        $jsonPayload = $([pscustomobject] $psobjPayload) | ConvertTo-Json #-Compress
+
+        $irmParams = @{
+            Uri    = "$uri/v1/auth/token/roles/$RoleName"
+            Header = @{ "X-Vault-Token" = $global:VAULT_TOKEN }
+            Method = 'Post'
+            Body   = $jsonPayload
+        }
+
+        if ($PSCmdlet.ShouldProcess("$RoleName",'Create Vault token role')) {
+            try {
+                Invoke-RestMethod @irmParams
+            }
+            catch {
+                throw
+            }
+        }
+    }
+
+    end {
+
+    }
+}