Configuring OpenID Connect in Octopus Deploy

Overview

OpenID Connect (OIDC) allows your GitHub Actions workflows to authenticate with Octopus Deploy to push packages, create releases or trigger deployments without storing Octopus Deploy passwords or API keys as long-lived GitHub secrets.

This guide provides an overview of how to configure Octopus Deploy to trust GitHub's OIDC as a federated identity, and includes a workflow example for the octopusdeploy/login action that uses tokens to authenticate to your Octopus Deploy instance.

Prerequisites

Para conocer los conceptos básicos de cómo GitHub usa OpenID Connect (OIDC) y su arquitectura y ventajas, consulta OpenID Connect.
Antes de proceder, debes planear tu estrategia de seguridad para garantizar que los tokens de acceso solo se asignen de forma predecible. Para controlar la forma en que el proveedor de servicios en la nube emite tokens de acceso, tendrá que definir al menos una condición, para que los repositorios no confiables no puedan solicitar tokens de acceso para los recursos en la nube. Para más información, consulta OpenID Connect.
Si sigues esta guía en GHE.com, comprende que debes sustituir determinados valores en la siguiente documentación. Consulta OpenID Connect.

Adding the identity provider to Octopus Deploy

To use OIDC with Octopus Deploy, first establish a trust relationship between GitHub Actions and your Octopus Deploy instance. For more information about this process, see Using OpenID Connect with the Octopus API in the Octopus Deploy documentation.

Sign in to your Octopus Deploy instance.
Create or open the Service Account that will be granted access via the token request.
Configure a new OIDC Identity, defining the relevant subject that the GitHub Actions workflow token request will be validated against.

Updating your GitHub Actions workflow

To update your workflows for OIDC, you will need to make two changes to your YAML:

Add permissions settings for the token.
Use the OctopusDeploy/login action to exchange the OIDC token (JWT) for a cloud access token.

Nota:

Cuando los entornos se usan en flujos de trabajo o en directivas de OIDC, se recomienda agregar reglas de protección al entorno para mayor seguridad. Por ejemplo, puedes configurar reglas de implementación en un entorno para restringir qué ramas y etiquetas se pueden implementar en el entorno o acceder a secretos del entorno. Para más información, consulta Administrar entornos para la implementación.

Adding permissions settings

La ejecución de trabajo o flujo de trabajo requiere una configuración de permissions con id-token: write para permitir que el proveedor OIDC de GitHub pueda crear un token web JSON para cada ejecución.

Nota:

La configuración de id-token: write de los permisos del flujo de trabajo no concede al flujo de trabajo permiso para modificar o escribir en ningún recurso. En su lugar, solo permite al flujo de trabajo solicitar (capturar) y usar (establecer) un token OIDC para una acción o paso. A continuación, este token se usa para autenticarse con servicios externos mediante un token de acceso de corta duración.

Para obtener información detallada sobre los permisos necesarios, ejemplos de configuración y escenarios avanzados, consulta Referencia de OpenID Connect.

Requesting the access token

The OctopusDeploy/login action receives a JWT from the GitHub OIDC provider, and then requests an access token from your Octopus Server instance. For more information, see the OctopusDeploy/login documentation.

The following example exchanges an OIDC ID token with your Octopus Deploy instance to receive an access token, which can then be used to access your Octopus Deploy resources. Be sure to replace the server and service_account_id details appropriately for your scenario.

YAML

# Este flujo de trabajo usa acciones que no GitHub no certifica.
# Estas las proporcionan entidades terceras y las gobiernan
# condiciones de servicio, políticas de privacidad y documentación de soporte
# en línea.

jobs:
  create_release_in_octopus:
    runs-on: ubuntu-latest
    name: Create a release in Octopus
    permissions:
      # You might need to add other permissions here like `contents: read` depending on what else your job needs to do
      id-token: write # This is required to obtain an ID token from GitHub Actions for the job
    steps:
      - name: Login to Octopus
        uses: OctopusDeploy/login@34b6dcc1e86fa373c14e6a28c5507d221e4de629 #v1.0.2
        with:
          server: https://my.octopus.app
          service_account_id: 5be4ac10-2679-4041-a8b0-7b05b445e19e

      - name: Create a release in Octopus
        uses: OctopusDeploy/create-release-action@fe13cc69c1c037cb7bb085981b152f5e35257e1f #v3.2.2
        with:
          space: Default
          project: My Octopus Project

# Este flujo de trabajo usa acciones que no GitHub no certifica.
# Estas las proporcionan entidades terceras y las gobiernan
# condiciones de servicio, políticas de privacidad y documentación de soporte
# en línea.

jobs:
  create_release_in_octopus:
    runs-on: ubuntu-latest
    name: Create a release in Octopus
    permissions:
      # You might need to add other permissions here like `contents: read` depending on what else your job needs to do
      id-token: write # This is required to obtain an ID token from GitHub Actions for the job
    steps:
      - name: Login to Octopus
        uses: OctopusDeploy/login@34b6dcc1e86fa373c14e6a28c5507d221e4de629 #v1.0.2
        with:
          server: https://my.octopus.app
          service_account_id: 5be4ac10-2679-4041-a8b0-7b05b445e19e

      - name: Create a release in Octopus
        uses: OctopusDeploy/create-release-action@fe13cc69c1c037cb7bb085981b152f5e35257e1f #v3.2.2
        with:
          space: Default
          project: My Octopus Project

En este artículo