FpsGeneral

1.0.24281.2

Functions/PersonalAccessToken/Set-FpsAzDoPat.ps1

                                <#

.SYNOPSIS

    Requests a PAT token from the user and stores it in Windows Credential Manager.

.DESCRIPTION 

    This cmdlets assumes the PAT token is to access Azure DevOps.  

        User needs access to Azure DevOps. This scripts assumes the user needs read access for 'Packaging' and 'Build'. 

        This enables the user to download modules from a Azure DevOps Artifact feed or from Build artifacts through scripts. 

    However the functionality can be used more generic, it stores 'a' PAT token.

    To suppress the Azure DevOps related message use switch disableMessage.

.EXAMPLE 

    Set-FpsAzDoPat

.EXAMPLE 

    Set-FpsAzDoPat -CredentialName 'AnotherPAT' -DisableMessage

.EXAMPLE 

    Set-FpsAzDoPat -CredentialName 'AnotherPAT' -PersonalAccessToken 'ff34885a8624460a8555y03w1shth12wa2va11d' -DisableMessage

#>

function Set-FpsAzDoPat {

    [CmdletBinding()]

    param (

        [string] $CredentialName = 'PowershellPATAzureDevOps',

        [string] $PersonalAccessToken,

        [switch] $DisableMessage

    )

    # Import PowerShell module CredentialManager, required to store Azure DevOps PAT token

    Import-FpsModule -ModuleNames 'CredentialManager'

    if ($DisableMessage -eq $false){

        $msg = @()

        $msg += 'You need to provide a valid Personal Access Token (PAT) to access Azure DevOps through PowerShell.'

        $msg += 'If this is your first time setting a PAT for 4PS PowerShell Tools: '

        $msg += '  - Go to https://dev.azure.com/4psnl/_usersSettings/tokens'

        $msg += '  - Click on ''New Token''.'

        $msg += '  - Enter a name, for example: ''4PS Tools Powershell''.'

        $msg += '  - Set the Expiration date to one year from now.'

        $msg += '  - Under ''Build'' mark ''Read''.'

        $msg += '  - Under ''Packaging'' mark ''Read''.'

        $msg += '  - Press Save.'

        $msg += '  - The next screen shows the token. Copy this token to the clipboard.'

        $msg += '  - The script will ask for your token and stores it securely on your local machine.'

        $msg += ''

        $msg += 'If your previous PAT token is expired: '

        $msg += '  - Go to https://dev.azure.com/4psnl/_usersSettings/tokens'

        $msg += '  - Click on ''Active'' in the top right corner and select ''Expired''.'

        $msg += '  - Find and select your expired PAT.'

        $msg += '  - Click on Regenerate.'

        $msg += '  - The next screen shows the token. Copy this token to the clipboard.'

        $msg += '  - The script will ask for your token and stores it securely on your local machine.'

        $msg | Write-Host -ForegroundColor Green

    }

    # Request PAT from user if not set as parameter

    if([string]::IsNullOrEmpty($PersonalAccessToken)){

        $pat = Read-Host 'Please provide your Personal Access Token (PAT)' -AsSecureString

    } else {

        $pat = $PersonalAccessToken | ConvertTo-SecureString -AsPlainText -Force

    }

    # Store the token

    New-StoredCredential `

        -Target $CredentialName `

        -UserName 'PersonalAccessToken' `

        -SecurePassword $pat `

        -Persist LocalMachine `

        -ErrorAction Stop | Out-Null

}

Export-ModuleMember -Function Set-FpsAzDoPat