SINCE VERSION 7.0

What is a Secret?

A secret in PIPEFORCE is a piece of information you would like to share between services and systems but must stay highly confidential as much as possible.

Here are some examples of secrets:

• An API token to access an external service.

• A set of username and password.

• A key to encrypt and decrypt some data.

All of these secrets must be handled very carefully. Therefore it is not a good idea to place this kind of information in the source code of your pipeline scripts or services.

Instead, you should create a secret once in PIPEFORCE and refer to it by its unique name.

The secrets are automatically stored in encrypted format.

Only the backend component which is allowed to work with the secret can then load, decrypt and use it by this name. Users and other components are not able to see it.

Create a secret​

In PIPEFORCE you have two options, creating a secret:

• Using the command secret.put

• Using the web portal.

Format patterns​

There are different format patterns of secrets possible:

• bearer - A bearer token typically used in conjunction with JWT. Such a secret is typically placed in the header of an HTTP request. The format pattern for the secret is: Bearer: <Token>

• header - A secret with format pattern <HeaderName>: <HeaderValue> which will be typically placed in the header of an HTTP request of commands compatible with this secret format.

• secret-text - An arbitrary secret text to be used inside of components which are compatible with this format.

• username-password - A set of username and password in the pattern format <Username>:<Password>.

• oauth2-grant - since 9.5 A JSON which contains all information required to create an OAuth2 access token by calling the authorization endpoint given by x_url. The structure of the JSON is like this, whereas the required attributes depend on the grant type you're using (read the official OAuth2 documentation for this):

  { "grant_type": "client_credentials|password|...", "client_id": "...", "client_secret": "...",, "scope": "...", "username": "...", "password": "...", "x_tenant": "...", "x_url": "..." }

  Note: By default all entries of the JSON will be sent in the request body to the OAuth2 authorization server except the ones prefixed with x_. These prefixed entries are special ones depending on the context you’re using this secret.

Using a command​

In order to create a secret using the command secret.put, you can do so for example in the workbench:

Make sure you use the corresponding format pattern, as described above, in your secret value.

Using the web portal​

In order to create a secret using the web portal: After login select Secrets in the left menu.

Then click on Add Secret, select the format of your secret, give it a unique name, set the secret format and value, then click Add.

Open

Using a secret…

… in a pipeline​

Once a secret has been created, you can refer to it using its unique name inside a pipeline.

It depends on the command whether it supports secrets and in which form. Read the documentation of the command of interest.

Here is an example to refer to the mysecret secret in an HTTP call:

… in a microservice

You can pass secrets also to microservices with some security related limitations:

• Only secrets of type secret-text can be passed along to microservices.

• The secret name must be prefixed with the name of the microservice (lower or upper case or any combination of). For example if service name is myservice, then the secret must be named MYSERVICE_MYSECRET.

• Or the secret name must be prefixed with SHARED_. For example if service name is myservice, then the secret must be named SHARED_MYSECRET.

The secret will be provided as ENV variable inside the microservice and can be read from there by its name.

For more information see: Microservices .