Using Vaulted Credentials in PowerShell

Granting permanent elevated privileges to administrators creates a critical security risk. EmpowerID addresses this by enabling secure, time-bound access to vaulted admin credentials. Admins can programmatically retrieve credentials for use in PowerShell scripts via EmpowerID’s secure password vault and OAuth integration. The retrieved credentials are returned as a PSCredential object for temporary use.

📝Prerequisites

Before retrieving credentials in a PowerShell session, you must create a Shared Credential object for those credentials in EmpowerID. Once the credential is created, users will need to input the GUID of the credential in the PowerShell session.
For more information, see Onboard Credentials.

Step 1 – Register an OAuth Client Application (One-Time Setup)

1. In the EmpowerID Web UI, navigate to:
   Single Sign-On > SSO Connections > OAuth / OpenID Connect

2. Select the OAuth Client Apps tab and click Add.
   

3. Complete the form with the following details:

   • Name – A unique name for the app
   • Display Name – The app’s display name
   • Description – Description of the app’s purpose
   • Application Type – Native Application
   • Signing Certificate – Select the required signing certificate (must include private key in EmpowerID)

   

4. Click Save. You are redirected to the View One page for the app.
   

5. In the Connection Details section, copy the:

   • Client ID
   • API Key

   

6. Expand the Client Secrets accordion and click Add.
   

7. In the dialog, enter:

   • Name – Name of the secret
   • Expires – Choose from:
     • 1 year
     • 2 years
     • Never
   • Client Secret – Copy and store this value securely

⚠️Security Notice

Be sure to save the Client Secret value before you closing the dialog as you will not be able to retrieve it afterwards.

Step 2 – Create the PowerShell Script to Retrieve Credentials

1. Open any text editor and paste the following script:

##Configuration
$ClientID = 'xxx'
$ClientSecret = 'xxx'
$APIKey = 'xxx'
$RedirectURL = 'https://sso.empoweriam.com/WebIdPForms/OAuth/V2'
$TokenURL = 'https://sso.empoweriam.com/oauth/v2/token'
$CheckoutURL ='https://sso.empoweriam.com/api/services/v1/password/checkoutcredential'
$GetCredentialURL = 'https://sso.empoweriam.com/api/services/v1/password/getexternalcredential'
$SearchURL = 'https://sso.empoweriam.com/api/webui/v1/ExternalCredentialView/GetAllSearch'
$Debug = $TRUE
 
##Null check function
function IsNull($objectToCheck) {
    if ($objectToCheck -eq $null) {
        return $true
    }
    if ($objectToCheck -is [String] -and $objectToCheck -eq [String]::Empty) {
        return $true
    }
    if ($objectToCheck -is [DBNull] -or $objectToCheck -is [System.Management.Automation.Language.NullString]) {
        return $true
    }
    return $false
}
 
##Input from user
$EidUsername = Read-Host 'What is your EmpowerID username?'
$EidPassword = Read-Host 'What is your EmpowerID password?' -AsSecureString
$MasterPassword = Read-Host 'What is your master password?' -AsSecureString
$CredentialGuid = $NULL #Read-Host 'GUID of the credential?'
 
#get OAuth token
Write-Host "Getting OAUTH token...."
$AccessTokenheaders = New-Object "System.Collections.Generic.Dictionary[[String],[String]]"
$AccessTokenheaders.Add("Content-Type", 'application/x-www-form-urlencoded')
$AccessTokenheaders.Add("Authorization", 'Basic '+[System.Convert]::ToBase64String([System.Text.Encoding]::UTF8.GetBytes($EidUsername+':'+[Runtime.InteropServices.Marshal]::PtrToStringAuto([Runtime.InteropServices.Marshal]::SecureStringToBSTR($EidPassword)))))
$AccessTokenheaders.Add("X-EmpowerID-API-Key", $APIKey)
$AccessTokenBody = @{
    client_id = $ClientID
    client_secret = $ClientSecret
    grant_type = "password"
    redirect_uri = $RedirectURL
}
$AccessTokenResponse = Invoke-RestMethod $TokenURL  -Method Post -Body $AccessTokenBody -Headers $AccessTokenheaders
if($Debug){
Write-Host ($AccessTokenResponse | Format-Table | Out-String)
}
if (IsNull($AccessTokenResponse.access_token)) {
    throw $AccessTokenResponse.error_description
}
 
#Search
$CredentialDictionary = New-Object "System.Collections.Generic.Dictionary[[String],[Object]]"
$NeedSearch = Read-Host "Do you have the guid of the credential, yes/no?"
if($NeedSearch -eq "yes")
{
    $CredentialGuid = Read-Host 'GUID of the credential?'
}
if($NeedSearch -eq "no")
{
    $SearchHeaders = New-Object "System.Collections.Generic.Dictionary[[String],[String]]"
    $SearchHeaders.Add("Content-Type", 'application/json')
    $SearchHeaders.Add("Authorization", 'Bearer '+$AccessTokenResponse.access_token)
    $SearchHeaders.Add("X-EmpowerID-API-Key", $APIKey)
    $SearchText = Read-Host 'Enter the text to search'
 
    while($CredentialGuid -eq $NULL )
    {
        $SearchBody = "{ 'TypeName':'ExternalCredentialView', 'MethodName': 'GetByCurrentPersonID', 'Parameters': { 'IsPSMPolicy' : false, 'ExternalCredentialPolicyID' : null, 'ResourceTags': null, 'ColumnsToSearch': '', 'TextToSearch': '$SearchText' }}"
         
        $SearchResponse = Invoke-RestMethod $SearchURL  -Method Post -Body $SearchBody -Headers $SearchHeaders
        if($SearchResponse.Data -eq $NULL -Or $SearchResponse.Data.Count -eq 0 )
        {
            $SearchText = Read-Host 'Your search did not return any results. Enter new text to search'
            continue
        }
        else
        {
            Write-Host ($SearchResponse.Data | Select-Object -Property ExternalCredentialID,FriendlyName,Name,Description | Format-Table | Out-String)
            $Selected = Read-Host "Did you find the credential you need? yes/no"
            if($Selected -eq "yes")
            {
                $ExternalCredentialID = Read-Host 'Enter the ID of the Credential you want to get'
                Foreach ($cred in $SearchResponse.Data)
                {
                    if($cred.ExternalCredentialID -eq $ExternalCredentialID)
                    {
                        $CredentialGuid = $cred.ExternalCredentialGUID
                        break
                    }
                }
                 
                if($CredentialGuid -eq $NULL)
                {
                    $SearchText = Read-Host 'The ID you entered did not match any of the entries! Please  enter new text to search'
                }
            }
            else
            {
                $SearchText = Read-Host 'Enter new text to search'
                continue
            }
        }
    }
}
 
#Check out credentials
Write-Host "Checking out credentials......"
try{
    $CheckoutHeaders = New-Object "System.Collections.Generic.Dictionary[[String],[String]]"
    $CheckoutHeaders.Add("Content-Type", 'application/json')
    $CheckoutHeaders.Add("Authorization", 'Bearer '+$AccessTokenResponse.access_token)
    $CheckoutHeaders.Add("X-EmpowerID-API-Key", $APIKey)
    $datetime = Get-Date           
    $CheckoutBody="{ credential: '"+$CredentialGuid+"', datestart: '" + $datetime.ToUniversalTime() + "', durationinminutes: 10, justification: 'PowerShell'  } "
    $CheckoutResponse = Invoke-RestMethod $CheckoutURL  -Method Post -Body $CheckoutBody -Headers $CheckoutHeaders
    if($Debug){
        Write-Host ($CheckoutResponse | Format-Table | Out-String)
    }
 
    if ($CheckoutResponse.Result -eq "WentForApproval") {
        Write-host "The checkout procedure went for approval"
        throw "The checkout procedure went for approval"
    }
}
catch{
    throw $_.Exception.Response.StatusCode
}
 
try{
    #Get Credentials
    Write-Host "Getting Credentials"
    $GetCredentialsHeaders = New-Object "System.Collections.Generic.Dictionary[[String],[String]]"
    $GetCredentialsHeaders.Add("Content-Type", 'application/json')
    $GetCredentialsHeaders.Add("Authorization", 'Bearer '+$AccessTokenResponse.access_token)
    $GetCredentialsHeaders.Add("X-EmpowerID-API-Key", $APIKey)
    $GetCredentialsBody="{'credential':'"+$CredentialGUID+"','password' : '"+[Runtime.InteropServices.Marshal]::PtrToStringAuto([Runtime.InteropServices.Marshal]::SecureStringToBSTR($MasterPassword))+"'}"
 
    $GetCredentialsBody
 
    $GetCredentialsResponse = Invoke-RestMethod $GetCredentialURL -Method Post -Body $GetCredentialsBody -Headers $GetCredentialsHeaders
    if($Debug){
        Write-Host ($GetCredentialsResponse | Format-Table | Out-String)
    }
    $secpasswd = ConvertTo-SecureString $GetCredentialsResponse.Password -AsPlainText -Force
    $global:CredentialsfromAPI = new-object -typename System.Management.Automation.PSCredential -argumentlist $GetCredentialsResponse.UserName,$secpasswd
    Write-Host "Credentials from the API call are saved in a PSCredential object CredentialsfromAPI"
}
catch
{
    throw $_.Exception.Response.StatusCode
}
 
$CredentialsfromAPI

2. Replace the following values in the script:

   • $ClientID – replace the xxx with the GUID value from the Client ID (Key) of your OAuth application
   • $ClientSecret – replace the xxx with the GUID value from the Client Secret of your OAuth application
   • $APIKey – replace the xxx with the GUID value from the API Key of your OAuth application
   • $RedirectURL – replace sso.empoweriam.com with the FQDN of your server
   • $TokenURL – replace sso.empoweriam.com with the FQDN of your server
   • $CheckoutURL – replace sso.empoweriam.com with the FQDN of your server
   • $GetCredentialURL – replace sso.empoweriam.com with the FQDN of your server
   • $SearchURL – replace sso.empoweriam.com with the FQDN of your server

3. Save the file as GetCredentials.ps1.

Step 3 – Run the PowerShell script

1. In File Explorer, right-click the saved file and select Run with PowerShell.

2. PowerShell opens and prompts you for several values. Answer each and press Enter. The script retrieves the OAuth token.

3. Once the token is retrieved, you are asked whether you have the GUID of the credential. If you respond yes, you must provide the GUID, otherwise, you are prompted to search for the credential. Here we respond yes.

4. Enter the GUID of the Shared Credential and press ENTER. PowerShell proceeds to check out the credentials.

   ⚠️Security Notice

   Be sure to save the Client Secret value before closing the dialog as you will not be able to retrieve it afterwards.

5. In EmpowerID, you can verify that the credentials are checked out by navigating to Privileged Access > Shared Credentials and selecting the Checked-Out Credentials tab.

Output

After the script runs successfully, the credentials are returned and stored in a PowerShell PSCredential object:

$global:CredentialsfromAPI

You can now use this object to authenticate PowerShell commands or remote sessions. For example:

Invoke-Command -ComputerName server01 -Credential $global:CredentialsfromAPI -ScriptBlock { Get-Process }

This credential object includes:

• The vaulted username and password retrieved securely from EmpowerID
• A secure token for temporary, just-in-time privileged use

⚠️Security Tip

The PSCredential object is stored in a global variable for the current session. For security purposes, clear the variable after use if it is no longer needed.