Check Out Credentials via PowerShell

Granting permanent elevated privileges to your admins represents an open security vulnerability. You can avoid this by using vaulted admin credentials in EmpowerID so that usernames and passwords are stored in a secure, encrypted password vault. When your system admins require elevated privileges for use in a PowerShell script, the EmpowerID system retrieves the credentials and generates a PSCredential object for them to use.

In order to allow users to check out credentials via PowerShell, you need to do the following:

1. Create an OAuth client application in EmpowerID for PowerShell. This generates a Client ID and Secret that the user must input to the PowerShell script in order to execute it.

2. Edit and save the PowerShell script included in this article on a target machine. 

3. Execute the script to test credential retrieval.
   
   

Step 1 – Create an OAuth client application (one time setup)

1. On the navbar, expand Single Sign-On > SSO Connections, and select OAuth / OpenID Connect.

2. Select the OAuth Client Apps tab and then click the Add button above the grid.
   
   

   Open

   

    

3. Enter the following information in the OAuth Provider Application Details form:

   • Name – Name of the app

   • Display Name – Display name for the app

   • Description – Description of the app

   • Application Type – Native Application

   • Signing Certificate – Select the signing certificate for your environment. This certificate must have the private key in EmpowerID.
     
     

     Open

     

      

4. Click Save.
   
   After EmpowerID saves the app, you should be directed to the View One page for the app.
   
   

   
   
   

5. Copy the Client ID and API Key in the Connection Details section. You need these to authenticate to EmpowerID in PowerShell.
   
   

    

6. Expand the Client Secrets accordion and click the Add button on the grid header.
   
   

    

7. In the General dialog that appears, do the following:

   • Name – Name of the secret

   • Expires – Select one of the below options:

     • I year

     • 2 years

     • Never

   • Client Secret – Copy and save this value for use in the PowerShell script. 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 a PowerShell script to retrieve the credentials

1. In any text editor, 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?' #$EidPasswordPlain = [Runtime.InteropServices.Marshal]::PtrToStringAuto([Runtime.InteropServices.Marshal]::SecureStringToBSTR($EidPassword)) #$MasterPasswordPlain = [Runtime.InteropServices.Marshal]::PtrToStringAuto([Runtime.InteropServices.Marshal]::SecureStringToBSTR($MasterPassword)) #$Base64Credentials=[System.Convert]::ToBase64String([System.Text.Encoding]::UTF8.GetBytes($EidUsername+':'+[Runtime.InteropServices.Marshal]::PtrToStringAuto([Runtime.InteropServices.Marshal]::SecureStringToBSTR($EidPassword)))) #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) { #Write-Host $cred.ExternalCredentialGUID $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.
   
   

    

   If your PowerShell instance disappears instead of checking out the credentials, your server may not be set to allow you to execute scripts.

   See About Execution Policies in the Microsoft PowerShell documentation to learn how to change your execution policy.

    

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.