Skip to main content
Version: 10.9.x

Manage Providers

Providers can be generically defined as a means of storing information about external services. The Mia-Platform Console supports providers with 3 different capabilities:

  • Git Providers: allow users to manage repositories within their workspace;
  • Secret Managers: allow users to securely store API keys, passwords, certificates, and other sensitive data;
  • CI/CD (Continuous Integration and Continuous Delivery) Tools: allow users to automate one or more stages of the so-called CI/CD pipelines (which usually consist of commit, build, test, and deploy).

The following table shows the providers currently supported by the Console, grouped by capability:

CapabilityProviders
Git ProviderGitLab, GitHub, Bitbucket, Azure DevOps
Secret ManagerGitLab, Vault
CI/CD ToolGitLab (Git Runner), GitHub (GitHub Actions), Jenkins, Azure DevOps

Providers Overview​

Mia-Platform Console allows authorized users to manage providers. More specifically, a user can:

  • Add a new connection to a provider;
  • Edit the connection to a provider;
  • Set a default provider for a company.

To access these features, head to the Company Overview area of the Console by clicking the related button on the home page, next to your company name.

Go to Company Overview

By clicking on "Providers" you will be redirected to the related section, in which (assuming you already have some providers connected) you can see a table containing some information about the providers connected to the Console:

  • Name: provider name, assigned by the user while connecting the provider to the Console;
  • Capabilities: provider capabilities (Git Provider, Secret Manager, CI/CD Tool);
  • Service: external reference service on which the provider relies to provide its capabilities (e.g. Azure, GitHub, Jenkins).

You can filter data based on provider name or service through the search bar at the top of the table, while the bar next to it allows you to filter by one or more capabilities.

Providers overview

Connect a Provider​

You can connect a provider by clicking on the "Add provider connection" button, located in the page's top right corner. A modal will show up, and, through a few steps, you will be asked to enter some information related to the provider.

Step 1: Provider Services​

Add provider 1a Add provider 1b

In this step, you are required to choose the specific provider you want to use among the ones supported by the Console and, for the chosen provider, the capabilities you want to use it for ("Git Provider", "Secret Manager", "CI/CD Tool").

info

If the provider offers only one capability, clicking on it will lead directly to step 2 and the capability will be selected by default.

Step 2: Provider Details​

Add provider 2

In this step, you can insert some general details about your provider:

  • Provider name (required): a human-readable name for the provider;
  • API Base URL (required): the reference endpoint URL for calls to the provider APIs;
  • Base URL (required): the reference endpoint URL for the provider;
  • Description: a brief description of the provider.

Step 3: Credentials​

Add provider 3

In this step, you are required to insert information about the authentication method to the provider, so that the Console has the necessary permissions to perform all read/write operations on it:

  • Credentials type (required): the type of credentials used to authenticate requests to the provider. It can be one of "Token," "M2M," and "OAuth2".

Depending on the credentials type, the other information to be entered will be:

  • For credentials of the type "Token":
    • Access token (required): the token that allows the Console to authenticate against the APIs of the provider (temporary credentials).
  • For credentials of the type "M2M":
    • Token (required): the token that allows the Console to authenticate against the APIs of the provider (long-lived credentials);
    • Access token URL (required): the reference authorization endpoint URL that, to requests that include the authentication token, responds by generating temporary credentials.
  • For credentials of the type "OAuth2":
    • Access token URL (required): the reference OAuth2 authorization endpoint URL that, to requests that include client ID and client secret, responds by generating temporary credentials;
    • Client ID (required): OAuth2 public client identifier;
    • Client secret (required): OAuth2 secret, known only to the client and the authorization server.
info

All credentials data are stored in an encrypted MongoDB collection. For more information about MongoDB encryption, take a look at the dedicated documentation page.

caution

Credentials entered at this stage, for security reasons, will never again be shown to the user, who will be able to replace them with new ones but not visualize them again.

Supported credential types​

Depending on the provider selected in step 1, the types of credentials supported will change. The following table shows the credential types supported by each provider:

Credentials TypeProviders
TokenGitLab, GitHub, Bitbucket, Azure DevOps, Vault, Jenkins
M2MVault
OAuth2Jenkins
Assign the right scope to your credentials

Make sure, when generating credentials on the respective provider sites, to assign them a scope so that they have the necessary permissions for all read and write operations performed through the Console.

For example, for the "Token" credentials type, the access token should have scope "api" in the case of GitLab, admin scopes for GitHub, "Project admin" and "Repository admin" in the case of Bitbucket, "Full access" for Azure DevOps.

Step 4: Advanced​

Add provider 4a Add provider 4b

In this step, you can enter some optional advanced information through two expandable forms:

Certificate Authority​

If you have set up verification of a CA for the connection to your provider, here you can enter it through the homonymous field:

  • Certificate authority: base64 decoded CA certificate for the TLS connection with the provider.

Proxy​

If the Console needs to use a proxy to forward calls to the provider, here you can enter the information needed for the connection:

  • URL: the URL used to connect to the proxy, which indicates where the proxy is exposed;
  • Username: the username used in connection requests to the proxy for basic authentication;
  • Password: the password used in connection requests to the proxy for basic authentication. This property will be safely encrypted.

By clicking on "Add provider", the connection to the provider will be set, and it will appear as a new entry in the table.

View Provider Information​

By clicking on the arrow button located in the rightmost column of a provider entry in the table, a new page will show up, displaying information about the specific provider through 3 cards:

  • Details: this card shows the information inserted by the user in step 2 of connecting the provider to the Console (and, in addition, the specific provider and selected capabilities), and allows to modify this information through the "Edit" button in the top right corner, as further explained below.

Provider details

  • Credentials: this card shows the credentials type chosen by the user in step 3 of connecting the provider to the Console, and allows to replace the credentials information through the "Change credentials" button in the top right corner, as further explained below.

Provider credentials

  • Advanced: this card shows the optional information inserted by the user in step 4 of connecting the provider to the Console through 2 tabs - "Certificate Authority" and "Proxy" - and allows to modify (or eventually add) this information through the "Edit" button in the top right corner, as further explained below.

Provider advanced certificate Provider advanced proxy

In case a base64 CA certificate has been entered, clicking on the "View certificate" button allows the user to visualize the certificate in both human-readable and plain versions in a two-tabs modal.

The "Expanded view" tab displays the human-readable version of the certificate, while the "Text view" tab shows its plain version and a copy button in the modal footer allows the user to quickly copy the plain base64 CA certificate.

Edit a Provider​

As mentioned in the previous section, through the button in the top right corner of the Details, Credentials, and Advanced cards, it is possible to modify the information inserted by the user while connecting the provider to the Console.

A click on the button will open a modal very similar to the one seen when connecting the provider, but only specific to the information you wish to edit.

info

In the Details card, the modal will allow you also to change the capabilities used by the provider, selected in step 1.

In the image below for example, the user clicked the "Edit" button on the "Details" card, opening a modal for editing the information entered during steps 1 and 2 of provider creation. By clicking on "Edit provider", the information about the provider will be updated.

Edit provider details

Set a Default Provider​

Once you create a provider connection, you will be able to set it as the default provider for a specific capability of that company.

By using the dedicated cards at the top of the providers' section, you will be able to select one of the providers implementing that specific capability.

As soon as the default provider has been set for a certain capability, the card will show the corresponding chosen provider. If no provider has been set, a "Set default capability" button will appear instead.

Default Providers

Setting a default provider for a company allows you to make that provider handle a specific capability for any project that will be created within the company.

In this way, you will not need to manually specify a provider for your projects.

info

Default Providers are automatically associated with newly created projects inside the company.

caution

Please make sure to have the right permissions to set or modify the default providers of a company.

Only Company Owners will be able to access this feature.

Edit a Default Provider​

You can change the default provider connection for a specific capability by clicking the edit button located in the upper right corner of the default providers' cards.

A modal will appear allowing you to select one of the providers implementing that specific capability: Default Providers

Once you edit the default provider, you will be able to see the card with the new provider set.

Associate a Provider to a Project​

If you haven't specified a default provider on a certain capability, or you wish to overwrite the default provider configuration, you will need to manually associate the provider with the projects you want to use it for within that company.

To do this, you can use the CMS: navigate through the Projects section, select the desired project, and change the providerId field value in the Repository object.

Associate provider to project CMS

Provider APIs​

For versions prior to 10.8, the above information is not valid, as providers were managed directly through APIs. Therefore, for the sake of backward compatibility, we report in this section the APIs used to create and modify providers, along with examples of request bodies:

  • POST - /api/backend/tenants/{tenantId}/providers: used to create a new provider;
  • PATCH - /api/backend/tenants/{tenantId}/providers/{providerId}: used to edit an existing provider.
info

These APIs are protected and can be used only if you belong to the group access_token_manager.

POST​

To create a new provider, you need to call the respective API as follows:

curl --location --request POST 'https://console-url/api/backend/tenants/my-example-company/providers' \
--header 'Cookie: sid={{CHANGE_ME_WITH_YOUR_SID}}' \
--header 'Content-Type: application/json' \
--data-raw '{"credentials":{"type":"token","content":{"accessToken":"my-super-super-super-secret-token"}},"id":"gitlab-id","label":"My GitLab Label","type":"gitlab","urls":{"apiBase":"https://gitlab-test.com/api","base":"https://gitlab-test.com"}}'

The body schema of the request should adhere to the following data model:

"body": {
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "providerId": { "type": "string" },
    "label": { "type": "string" },
    "description": { "type": "string" },
    "type": { "type": "string" },
    "capabilities": {
      "description": "Field introduced in v10.8 of the Console",
      "type": "array",
      "items": {
        "type": "string",
        "enum": ["git-provider", "secret-manager", "ci-cd-tool"],
      }
    },
    "urls": {
      "type": "object",
      "properties": {
        "base": { "type": "string" },
        "apiBase": { "type": "string" }
      },
      "required": ["base", "apiBase"]
    },
    "base64CA": { "type": "string" },
    "proxy": {
      "type": "object",
      "properties": {
        "url": { "type": "string" },
        "username": { "type": "string" },
        "password": { "type": "string" }
      },
      "required": ["url"]
    },
    "credentials": {
      "oneOf": [
        {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "type": {
              "type": "string",
              "const": "token"
            },
            "expirationDate": {
              "description": "Field introduced in v10.8 of the Console",
              "type": "string",
              "format": "date-time"
            },
            "content": {
              "type": "object",
              "additionalProperties": false,
              "properties": {
                "accessToken": { "type": "string" }
              },
              "required": ["accessToken"]
            }
          },
          "required": ["type", "content"]
        },
        {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "type": {
              "type": "string",
              "const": "userPass"
            },
            "expirationDate": {
              "description": "Field introduced in v10.8 of the Console",
              "type": "string",
              "format": "date-time"
            },
            "content": {
              "type": "object",
              "additionalProperties": false,
              "properties": {
                "userName": { "type": "string" },
                "password": { "type": "string" }  
              },
              "required": ["userName", "password"]
            }
          },
          "required": ["type", "content"]
        },
        {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "type": {
              "type": "string",
              "const": "m2m"
            },
            "expirationDate": {
              "description": "Field introduced in v10.8 of the Console",
              "type": "string",
              "format": "date-time"
            },
            "content": {
              "type": "object",
              "additionalProperties": false,
              "properties": {
                "accessTokenURL": { "type": "string" },
                "token": { "type": "string" }
              },
              "required": ["accessTokenURL", "token"]
            }
          },
          "required": ["type", "content"]
        },
        {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "type": {
              "type": "string",
              "const": "client_credentials"
            },
            "expirationDate": {
              "description": "Field introduced in v10.8 of the Console",
              "type": "string",
              "format": "date-time"
            },
            "content": {
              "type": "object",
              "additionalProperties": false,
              "properties": {
                "accessTokenURL": { "type": "string" },
                "clientId": { "type": "string" },
                "clientSecret": { "type": "string" }
              },
              "required": ["accessTokenURL", "clientId", "clientSecret"]
            }
          },
          "required": ["type", "content"]
        }
      ]
    },
    "required": ["providerId", "type", "urls"]
  }
}
Supported credential types

As discussed here, different types of providers support different types of credentials. The following table shows the credential types supported by each provider, referring to the data model shown above:

Credentials TypeProviders
tokengitlab, github, bitbucket, azure-devops, vault, jenkins
m2mvault
client_credentialsjenkins
Data model update

The fields capabilities and expirationDate (within credentials) have been introduced starting from version 10.8 of the Console.

Examples of request bodies specific to each provider type are shown below. In the examples, the capabilities and expirationDate fields are omitted, since it is assumed that calls to this API are made by users with a Console version lower than 10.8.

{
  "id": "my-github-provider",
  "label": "Mia-Platform GitHub",
  "type": "github",
  "urls": {
    "apiBase": "https://api.github.com",
    "base": "https://github.com"
  },
  "credentials": {
    "type": "token",
    "content": {
      "accessToken": "my-super-super-super-secret-token"
    }
  }
}

PATCH​

To edit an existing provider, you need to call the respective API as follows:

curl --location --request PATCH 'https://console-url/api/backend/tenants/my-example-company/providers/gitlab-id' \
--header 'Cookie: sid={{CHANGE_ME_WITH_YOUR_SID}}' \
--header 'Content-Type: application/json' \
--data-raw '{"credentials":{"type":"token","content":{"accessToken":"my-new-super-super-super-secret-token"}}'

The request of this endpoint is identical to the previous one, except that the providerId must be entered inside the endpoint params and not in the request body.