Overview

This guide explains how to assign credentials to analytics in your companies. Credentials will be used by the analytics to access a third part API (Object storage, IOT API, REST API...)

Pre-requisite

Before assigning credentials to an analytic, ensure:

• Analytics Creation: The analytic or custom analytic must be created and activated within your company.
• Credential Creation: The required credentials must be created for your company.
• Role Permissions: You must have the necessary roles that allow configuration of analytic. credentials.

Credential Management for Analytic

• At the company level, we define both analytics and the needed credentials.
• If an analytic requires credentials, they are included in its definition as credential parameters. Then we can assign the required credentials to its credential parameters.
• Credentials can be assigned to a specific version of an analytic or a range of versions.

Listing current credentials for analytic

To list the credentials associated with an analytic, use the following CLI command:

alteia analytics credentials list --company <shortnamecompany>

Example Output :

Analytics1 <shortnamecompany/analyticname>
├── Versions with configurable credentials:
│   └── 1.0.0
│       └── S3Parameter*: credential for S3
│   └── 2.0.0
│       └── S3Parameter*: credential for S3
│       └── AzureParameter*: credential for Azure Blob
└── Version ranges with configured credentials:
   ├── 1.0
   │   └── S3Parameter: 🔑 Credential S3

This command will display two sections:

Versions with Configurable Credentials: 

This section lists the analytic definitions that require credentials, as specified in their definition. It shows the versions of each analytic that have defined credential parameters, making it clear which versions need credentials for execution.

• Analytic Versions: Lists the specific versions (e.g., 1.0.0, 2.0.0) of each analytic that have credentials defined in their configuration.
• Credential Parameters: Shows the credential parameters (e.g., paramcred1, paramcred2) required by each version, indicating the types of credentials needed for the analytic (e.g., S3, Azure, etc.)

In the example above, 1.0.0 requires S3Parameterfor S3 access, while 2.0.0 requires both S3Parameter(for S3) and AzureParameter(for Azure Blob Storage).

Version Ranges with Configured Credentials: 

This section lists the configured credentials for specific version or version range. It shows which credentials have been assigned to a particular version or group of versions (e.g., a range like 1.x). This is useful for applying the same credentials across multiple versions, providing more flexibility for managing credentials across versions.

• Version Ranges: Shows the version or version range (e.g., 1.0, 2.x) that have configured credentials.
• Assigned Credentials: Lists the credentials that have been associated with the version or version range.

In the example above, the version range 1.0 (which includes versions like 1.0.0, 1.1.0, etc.) has S3Parameterconfigured, and the credential used is Credential S3

Assigning Credentials to an Analytic Version:

To assign credentials to a specific analytic version or version range

1- Run the following command:

alteia analytics credentials assign --company "<company_shortname>" -n <analytic_name> -v <version_range>

2- The system will prompt you to configure the credentials for the selected version(s).

3- Select the appropriate credential for each parameter

Configure the credentials that will be used when ordering the analytic <shortnamecompany/analyticname> for versions matching '2.*'

Credential definitions for analytic '<shortnamecompany/analyticname>@2.0.0' (last matching version)
┏━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━━━┓
┃ Name          ┃ Display Name                  ┃ Description       ┃ Required ┃ Current value ┃
┡━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━━━┩
│ S3Parameter   │ credential for S3             │ credential for S3 │ Yes      │ -             │
└───────────────┴───────────────────────────────┴───────────────────┴──────────┴───────────────┘
│ AzureParameter│ credential for for Azure Blob │ Azure blob Cred   │ Yes      │ -             │
└───────────────┴───────────────────────────────┴───────────────────┴──────────┴───────────────┘

? Select the credentials to use for 'S3Parameter'  (Use arrow keys)
  CLI4_docker-registry(type:docker)
❯ Credential S3 (type:object-storage)
  azure-blob-2024 (type:object-storage)
  gcp_extraction

  View schema
  ⏩ Skip
  Exit

4-To view credential schema details, select "View schema" option

The credential S3Parameter is required and will need to fulfill the following JSON schema:
{
 "type": "object",
 "properties": {
   "type": {
     "type": "string"
   }
 },
 "additionalProperties": false
}

5-Upon successful assignment, the system will confirm with a success message 

Successfully assigned credentials S3Parameter for analytic '<shortnamecompany/analyticname>' in versions matching '2.*'

Unassigning Credentials:

To unassign credentials from an analytic version or version range:

1- Run the unassignment command

 alteia analytics credentials unassign --company "<company_shortname>" -n <analytic_name> -v <version_range>
 

2- Select the credentials you want to unassign using the toggle options

Remove some credentials used when ordering the analytic '<shortnamecompany/analyticname>' for versions matching '2.*'

? Select the credentials to unassign from the analytic  (<up>, <down> to move, <space> to select, <a> to toggle, <i> to invert)
  ╭ using  credforanalytics
 ❯○ S3Parameter

3- The system will confirm successful unassignment 

Successfully unassigned credentials paramcred1 for analytic '<shortnamecompany/analyticname>' in versions matching '2.*'

Launching the analytic

When launching the analytic, the system checks for a configuration.

If a configuration exists for a specific version (e.g., 1.0.0) and a version range (e.g., 1.0) is later created, the analytic will be launched with the configuration for the closest matching version (in this case, 1.0.0). 

The version range configuration (1.0) will not replace the configuration for the specific version (1.0.0).

Summary:

• Assigning Credentials: Use the alteia analytics credentials assign command.
• Unassigning Credentials: Use the alteia analytics credentials unassign command.
• Credential Assignment Scope: Can be assigned to specific versions or version ranges of an analytic.
• Explicit assignments (specific version) always win over wildcard rules.
• Wildcard rules apply only to versions without a direct assignment.