Credential Types

Credentials come in many flavors. Each type of credential has a different set of data fields and is supported by different step modules.

Not all step modules require credentials. Some step modules have optional credentials, and some support multiple types of credentials.

Generic Secret

The generic credential type allows storing arbitrary text secrets as credentials.

Generic credential data has this structure:

{
    "text": "my secret text"
}

Username and Password

Username and password credentials can be used in step modules that required a username and password to authenticate.

A common example is HTTP Basic Authentication, which is used in the HTTP and Git Repository step modules.

Username and password credential data has this structure:

{
    "username": "somebody",
    "password": "abc123"
}

Bearer Token

A bearer token can be used in any step module using a bearer token to authenticate.

This type is supported by the HTTP and kubectl step modules.

Bearer token credential data has this structure:

{
    "token": "<token value here>"
}

Microsoft Azure: Service Principal

Microsoft Azure uses a service principal account in Azure Active Directory for API access control. To grant Sophos Factory access to your Azure subscription, you must create an Active Directory app registration:

1. Retrieve your subscription ID and Active Directory domain from the Subscriptions blade.

2. Create a new App Registration from the Azure Active Directory blade in the Azure portal. Retrieve the application’s Application ID.

3. Assign the application one or more Role Assignments at the scope of your choice (i.e. Subscription, Resource Group, etc), under the Access Control (IAM) sub-blade.

4. Add a key to the app registration from the Settings sub-blade.

For more detailed instructions, read the official documentation from Microsoft.

Azure service principal credential data has this structure:

{
    "subscription_id": "<subscription id>",
    "domain": "<active directory domain>",
    "tenant_id": "<active directory tenant id>",
    "client_id": "<application client id>",
    "client_key": "<application client secret key>"
}

Amazon Web Services: IAM Access Key

Access to AWS APIs is governed by IAM. To grant Sophos Factory access to your AWS account, you must create an IAM user:

1. Create an IAM User from the IAM page in the AWS portal.

2. Grant the user permissions on the cloud account from the Permissions tab on the user page.

3. Create an Access Key for the user by navigating to the Security credentials tab on the user page.

4. Record the Access key ID and Secret access key.

For more detailed instructions, read the official documentation from Amazon.

AWS IAM Access Key credential data has this structure:

{
    "access_key": "<iam access key id>",
    "secret_key": "<iam secret access key>"
}

Google Cloud Platform: Service Account (JSON)

Google Cloud Platform controls access to projects using Service Accounts. To grant Sophos Factory access to your GCP project, create a service account:

1. Add a new service account from the IAM & admin page in the GCP portal.

2. When creating the service account, you will be able to grant permissions by assigning a role.

3. Download and save the JSON file, which contains all values needed by Sophos Factory.

For more detailed instructions, read the official documentation from Google.

GCP service account credential data has this structure:

{
    "json": "<service account json>"
}

SSH Private Key

The SSH key credential type is used to store RSA private keys for use with SSH. This credential is supported by the Ansible Playbook and Git Repository step modules, among others.

SSH private key credential data has this structure:

{
    "private_key": "<pem private key>"
}

Generate a SSH Key Pair

In order to ensure the key will work correctly with the version of OpenSSH installed on the agent container, the key should be a PEM-encoded RSA private key, which looks like this:

-----BEGIN RSA PRIVATE KEY-----
MIIEowIBAAKCAQEAmgLwwZAs+ab7BK2t4eEoTVGE3I0hwQxBjuLy31zeFkSbAVEJ
adRB49gn1i/Zm0I/Yh788sdm8Z/z6jw6MbQzd8QAP5lIY3r7ct4gwJA86Zv7MUay
... more lines here ...
5VPP0Uq5sN/h1s2aXyO+GtQA321/eqCIl0tLIz6R1EwGEgpcj1Ks6c+4HDdEbgrE
JceCYdc9F2Io2XmwZle61UFNNVEWk41PfYhQEKyfxlefgU8ICGbr
-----END RSA PRIVATE KEY-----

The key should not have a passphrase.

Here is an example ssh-keygen command to generate a suitable key:

ssh-keygen -t rsa -m PEM -b 2048 -q -N "" -f ./id_rsa -C 'my_key'

Note that this may not work on all operating systems. Consult the documentation for your version of ssh-keygen.

Suitable private keys can also be generated by PuTTYgen on Windows by exporting using the Conversions → Export OpenSSH key menu option.

Vault AppRole

The Vault AppRole credential is used with HashiCorp Vault to retrieve an access token. See here for more information about AppRole authentication.

Vault AppRole credential data has this structure:

{
    "role_id": "<role id>",
    "secret_id": "<secret id>"
}