[HOW TO] Use an OAuth2 application and PowerShell to programmatically get the contents of a secret

[HOW TO] Use an OAuth2 application and PowerShell to programmatically get the contents of a secret

By Centrify Contributor I ‎05-24-2018 07:52 AM

Centrify Infrastructure Services (Privilege Access Service) has the ability to store secrets. These secrets can be free-form text or files (currently up to 5mb in size). 

 

There will be use cases where the contents of these secrets need to be programmatically accessed EG from inside an application or as part of orchestration/DevOps processes. 

 

By leveraging Centrify's OAuth2 authorization framework, this article will describe how to configure an OAuth2 app that enables a PowerShell script to obtain the contents of a text-based secret from the Centrify platform.

 

However, it does not stop there. Using this methodology (Oauth2 apps & scopes) and the example script as a base, any programmatic call to the Centrify Identity Platform required for automation may be achieved. Including writing objects such as systems, shared accounts, secrets ETC. Pretty much everything that can be done via the portal can be automated/configured programmatically. 

 

Whilst this example is in PowerShell any compliant code can leverage this methodology (Java, C#, Go ETC). For example, I have Python code to run SQL queries against the Centrify Identity Platform from LINUX, but that's for another post Smiley Happy

 

For more detail on the Centrify Identity Platform API's see https://developer.centrify.com

Bed Time reading on OAuth2 : https://tools.ietf.org/html/rfc6749

 

Create the OAuth2 application and service account

 

As an administrative user, log in to the admin portal for your Centrify Infrastructure Services Tenant 

Example: https://lph.my.centrify.com/manage 

 

Select Apps -> Click Add Web Apps

 

stg1.jpg

 

 

 

 

 

 

 

Select the Custom Tab -> Click OAuth2 Client -> Add

 

stg2.jpg

Click Yes to add the application

stg3.jpg

 

Close the Add Web Apps Pop Up

 

Configure the application - Stage 1

 

Enter a suitable application ID and description - Make a note of the application ID, this is needed later.

 

stg4.jpg

 

Select General Usage 

 

  1. Under the client ID Type select the Confidential and Must be OAuth Client buttons
  2. Enter your tenant URL in the Issuer field

 

stg5.jpg

 

Select Tokens 

 

  1. Ensure the token type is JwtRS256 (JIT)
  2. Select Client Creds
  3. Ensure that Auth Code, Implicit and Resource Owner are not selected
  4. Set the Token Lifetime to be short (EG 5 mins)
  5. Ensure Issue refresh tokens is not checked

 

stg6.jpg

 

Select Scope

 

  1. Ensure User must confirm authorization request is not selected
  2. Under Scope definitions, Click Add

 

stg7.jpg

 

  1. Enter a suitable scope name and description - Make a note of the scope name, this is needed later.
  2. Click Add to define the API endpoints permitted under the scope

stg8.jpg

 

  1. Add RedRock/query
  2. Add ServerManage/RetrieveDataVaultItemContents
  3. Click Save

stg9.jpg

 Save the application definition

 

stg10.jpg

 

Configure the application service account - Stage 2

 

  1. Click General usage
  2. Create a Centrify directory user service account by selecting Click here to create one

 

stg11.jpg

 

Define an associated Centrify Identity Platform Service Account 

 

  1. Enter a suitable login name 
  2. Choose an appropriate suffix for the service account 
  3. Make a note of the login name and suffix,  this is needed later.
  4. Enter an email address, this is mandatory but is not used (at present)
  5. Enter a suitable display name
  6. Generate a password for the service account and copy/store it temporarily (or save it as a secret)  - this is needed later.
  7. Ensure Is Oauth confidential client (preview) is checked
  8. Note that Password never expires is greyed out - this is mandatory for the associated Oauth2 service account
  9. Click Create User

 

stg12.jpg 

Create a Role for the API Service Account

 

stg20.jpg

 

stg21.jpg

 

Add the API Service Account to the Role

 

stg22.jpg

 

Save the Role

 

Search for your OAuth2 app and click on it

 

stg23.jpg

 

Add the Role to your application

 

stg24.jpg

 

Save the application config

 

Create a test secret - Stage 3

 

1. From the Admin portal, select Infrastructure -> Secrets

2. Click Add Text 

 

stg13.jpg

 

  1. Enter a Name, a Description and a Secret. Make a note of the Name, this will be needed later
  2. Click Save 

stg14.jpg

 

Click on the newly created Secret

 

stg15.jpg

 

Under permissions, Click Add

 

stg16.jpg

 

  1. In the search box, enter the name of the Service account you created in Stage 2
  2. Select the service account from the list
  3. Click Add
  4. Permit the service account to retrieve the secret
  5. Save the permissions setting

stg18.jpg

 

Running the PowerShell script 

 

Base64 encode the service account and password

 

The OAuth2 Application authorizes the RESTapi to call endpoints using the Scope definition. This is done by issuing a bearer token that is subsequently used during further REST calls. In order to obtain the bearer token, the code must first present a base64 encoded user/password string to the Centrify Identity Platform

 

Using the Service account, suffix and password noted in stage 2, generate the base64 encoded string. This can be done in PowerShell using the following command:

 

$bytes = [System.Text.Encoding]::UTF8.GetBytes("YOUR-SERVICE-ACCOUNT@YOUR-SUFFIX:YOUR-PASSWORD");$base64 = [Convert]::ToBase64String($bytes);Write-Host($base64)

Example:

 

PS C:\Users\kevsmith> $bytes = [System.Text.Encoding]::UTF8.GetBytes("dummyuser@lph:notarealpassword");$base64 = [Convert]::ToBase64String($bytes);Write-Host($base64)

ZHVtbXl1c2VyQGxwaDpub3RhcmVhbHBhc3N3b3Jk

 

Download the attached cgetsecret.txt file and save it somewhere suitable as cgetsecret.ps1  NOTE The file extension change

 

Startup PowerShell as a regular user and ensure you are in the directory where you saved the script

 

Now you have the base64 encoded string, you can use the script to pull the test secret using the OAuth2 APP. The script requires the following parameters

 

cgetsecret.ps1 

[-tenant] <string> 
[-app] <string> 
[-scope] <string> 
[-credentials] <string> 
[-secret] <string>
[-diags] <optional>

 

Using your base64 encoded credentials, your application, your scope and your test secret as noted during the stages above, try a test pull of your secret. If you secret has spaces in the name surround them with quotes. EG 'My Secret'

 

Use the -diags switch to get verbose output

 

Example:

 

PS C:\Users\kevsmith> .\cgetsecret.ps1 -tenant lph.my.centrify.com -credentials xxxxx -app OAuth2CIPS -scope CIPSscope -secret cipsecret

a-test-secret

 

Troubleshooting

 

ERROR: failed to get OAuth2 token The remote server returned an error: (500) Internal Server Error.

There is an issue with your base64 credentials string or OAuth2 application definition. Check the application name and scope parameter. Double check the configuration of your application in the tenant

 

ERROR: unsupported secret type [file]

 Only text-based secrets can be obtained  by cgetsecret

 

ERROR: You are not authorized to perform this operation. Please contact your IT helpdesk.

The associated service account for the application does not have retrieve permissions for the secret

Showing results for 
Search instead for 
Do you mean 
Labels

Community Control Panel