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

GitHub が OpenID Connect (OIDC) を使用する方法の基本的な概念とそのアーキテクチャと利点については、「OpenID Connect」を参照してください。
先に進む前に、アクセストークンが予測可能な方法でのみ割り当てられるようにセキュリティ戦略を計画する必要があります。クラウドプロバイダーがアクセストークンを発行する方法を制御するには、少なくとも 1 つの条件を定義し、信頼できないリポジトリがクラウドリソースにアクセストークンを要求できないようにする必要があります。詳しくは、「OpenID Connect」をご覧ください。
GHE.com に関するこのガイドに従っている場合は、次のドキュメントの特定の値を置き換える必要があることを理解してください。「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.

メモ

環境がワークフローまたは OIDC ポリシーで使われる場合は、セキュリティを強化するために環境に保護規則を追加することをお勧めします。たとえば、環境のデプロイ規則を構成して、環境にデプロイできるブランチとタグを制限したり、環境シークレットにアクセスしたりできます。詳しくは、「デプロイに環境の使用」をご覧ください。

Adding permissions settings

GitHub の OIDC プロバイダーが実行ごとに JSON Web Token を作成できるよう、ジョブまたはワークフローの実行には id-token: write を含む permissions の設定が必要です。

メモ

ワークフローのアクセス許可で id-token: write を設定しても、リソースへの変更または書き込みを行うアクセス許可はワークフローに付与されません。そうではなく、ワークフローは、アクションまたはステップのための OIDC トークンを要求 (フェッチ) して使用 (設定) することのみが許可されます。その後、このトークンは、有効期間の短いアクセストークンを使って外部サービスで認証を行うために使われます。

必要なアクセス許可、構成例、高度なシナリオについて詳しくは、「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

# このワークフローはGitHubによって認定されていないアクションを使用します。
# それらはサードパーティによって提供され、
# 別個の利用規約、プライバシーポリシー、
# ドキュメントを参照してください。

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

# このワークフローはGitHubによって認定されていないアクションを使用します。
# それらはサードパーティによって提供され、
# 別個の利用規約、プライバシーポリシー、
# ドキュメントを参照してください。

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

この記事の内容