diff --git a/dictionary-octopus.txt b/dictionary-octopus.txt index d96764e609..f7d3147723 100644 --- a/dictionary-octopus.txt +++ b/dictionary-octopus.txt @@ -32,6 +32,8 @@ octopusvariable Octostache OIDC onlylogs +passout +pkcs reprioritize reprovisioned reprovisioning @@ -39,6 +41,7 @@ Runbook runbook runbooks Schannel +signingkeys sthumb swaggerui systemprofile diff --git a/src/pages/docs/deployments/azure/ase/index.md b/src/pages/docs/deployments/azure/ase/index.md index 8a2eddd9df..bd7c0e7fe1 100644 --- a/src/pages/docs/deployments/azure/ase/index.md +++ b/src/pages/docs/deployments/azure/ase/index.md @@ -26,11 +26,11 @@ Given that you can't access the app, or its management endpoint (Kudu), from the Contained in the publish profile is the URI of the deployment endpoint (Kudu) for the web app. This is the critical piece here. -For an external ASE that URI will be publicly accessible (e.g. https://yourapp.scm.aseName.p.azurewebsites.net). +For an external ASE that URI will be publicly accessible (e.g. https://your-app.scm.aseName.p.azurewebsites.net). -For an internal ASE the URI will not be publicly accessible, it will be something like https://yourapp.scm.yourdomain This is where the deployments will fail, they will be able to see all of the other Urls required but when they get to step 6 Octopus won't be able to resolve the address for the URI. +For an internal ASE the URI will not be publicly accessible, it will be something like `https://your-app.scm.your-domain` This is where the deployments will fail, they will be able to see all of the other Urls required but when they get to step 6 Octopus won't be able to resolve the address for the URI. -To fix that you need 2 things to happen. First, the network the Octopus Server is on has to be connected to the ASE's VNet, e.g. using ExpressRoute or a VPN. Second, the Octopus Server needs to be able to resolve `yourapp.scm.yourdomain` to the Internal Load Balancer IP address of your Azure ILB (found in the **IP addresses** for the ASE in the Azure portal), e.g. through DNS configuration. +To fix that you need 2 things to happen. First, the network the Octopus Server is on has to be connected to the ASE's VNet, e.g. using ExpressRoute or a VPN. Second, the Octopus Server needs to be able to resolve `your-app.scm.your-domain` to the Internal Load Balancer IP address of your Azure ILB (found in the **IP addresses** for the ASE in the Azure portal), e.g. through DNS configuration. Exactly how to do those 2 things will depend on your organization, what infrastructure you might already have in place and is beyond the scope of this guide. @@ -42,7 +42,7 @@ Usually when you create a web app in Azure its name must be unique. This isn't t This is the reason why you see a resource group and a web app name when using binding on the Octopus Web App step, we need the resource group to differentiate web apps with the same name. When you aren't using binding the drop down list is doing this too behind the scenes. -This is also why using a [principal of least privilege on a Service Principal](/docs/infrastructure/accounts/azure/#note_on_lease_privilege) is a little complicated. +This is also why using a [principal of least privilege on a Service Principal](/docs/infrastructure/accounts/azure/#note_on_least_privilege) is a little complicated. ## Learn more diff --git a/src/pages/docs/infrastructure/accounts/azure/index.md b/src/pages/docs/infrastructure/accounts/azure/index.md index 576697c7ab..3bb700a592 100644 --- a/src/pages/docs/infrastructure/accounts/azure/index.md +++ b/src/pages/docs/infrastructure/accounts/azure/index.md @@ -11,7 +11,7 @@ You can deploy software to the Azure cloud by adding your Azure subscription to Before you can deploy software to Azure, you need to add your Azure subscription to Octopus Deploy. -## Azure account authentication method {#CreatinganAzureAccount-AuthenticationMethod} +## Azure account authentication method {#CreatingAnAzureAccount-AuthenticationMethod} When you add an Azure account to Octopus, there are two ways to authenticate with Azure in Octopus. These represent the different interfaces in Azure, and the interface you need will dictate which authentication method you use. @@ -20,37 +20,66 @@ When you add an Azure account to Octopus, there are two ways to authenticate wit You can read about the differences in [this document](https://azure.microsoft.com/en-us/documentation/articles/resource-manager-deployment-model/). +Azure Service Principal accounts are for use with the **Azure Resource Management (ARM) API** only. Configuring your Octopus Server to authenticate with the service principal you create in Azure Active Directory will let you configure finely grained authorization for your Octopus Server. + :::div{.warning} Management Certificates are used to authenticate with Service Management APIs, those are being deprecated by Microsoft. See our [blog post](https://octopus.com/blog/azure-management-certs) for more details. Instructions remain only for legacy purposes. Please migrate to service principals as soon as possible. ::: ## Creating an Azure Service Principal account {#azure-service-principal} -Azure Service Principal accounts are for use with the **Azure Resource Management (ARM) API** only. Configuring your Octopus Server to authenticate with the service principal you create in Azure Active Directory will let you configure finely grained authorization for your Octopus Server. +Before creating an Octopus Azure Service Principal account, you will need an Azure App Registration. If you do not currently have an Azure App Registration follow the [App Registration](https://oc.to/create-azure-app-registration) guide, or create it with a [script](#create-app-registration-via-script). -1. Create an Azure Active Directory registered application (or application registration) and service principal (via the [Azure Portal](#create-service-principal-account-in-azure) or with [PowerShell](#create-service-principal-account-with-powershell)). -2. Allow Octopus to authenticate with Azure using a Service Principal. +After creating the App Registration, make a note of the following: -### Create an Azure Service Principal with the Azure Portal {#create-service-principal-account-in-azure} - -This step shows you how to create a Service Principal with the Azure Portal, if you would rather use PowerShell to create the Service Principal, see [Create an Azure Service Principal With PowerShell](#create-service-principal-account-with-powershell). +- **Subscription ID** +- **Tenant ID** +- **Application ID** -[Getting Started - Azure Account](https://www.youtube.com/watch?v=QDwDi17Dkfs) +There are two supported types of credentials to allow your Octopus instance to authenticate with an Azure Service Principal: Client Secrets and Federated Credentials. -1. In the Azure Portal, navigate to **Azure Active Directory ➜ Properties** and copy the value from the **Tenant ID** field, this is your **Tenant ID**. -1. Next you need your **Application ID**. - - If you have created an AAD registered application, navigate to **Azure Active Directory ➜ App Registrations**, click **View all applications**, select the app and copy the **Application ID**. Please note, the Azure UI defaults to **Owned Applications** tab. Click the **All Applications** tab to view all app registrations. - - If you haven't created a registered app, navigate to **Azure Active Directory ➜ App Registrations**, click on **New registration** and add the details for your app, and click **Save**. Make note of the **Application ID**. -3. Generate a one-time password by navigating to **Certificates & Secrets ➜ Certificates & Secrets**. Add a new **secret**, enter a description, and click **Save**. Make note of the displayed application password for use in Octopus. If you don't want to accept the default one year expiry for the password, you can change the expiry date. +### Create a client secret credential for an Azure Service Principal -You now have the following: +To manually create a client secret follow the [Add a client secret](https://oc.to/create-azure-credentials) section in the Azure AD documentation, or create it with a [script](#create-a-client-secret-via-script). -- **Tenant ID** -- **Application ID** -- **Application Password/secret** +Following this process you will be given the client secret, make a note of this as you cannot retrieve it afterward. Next, you need to configure your [resource permissions](#resource-permissions). +### Create a federated credential for an Azure Service Principal + +#### Octopus Server configuration +:::div{.info} +If you are using Octopus Cloud, you will not need to do anything to expose the instance to the public internet, this is already configured for you. +::: + +To use federated credentials, your Octopus instance will need to have two anonymous URLs exposed to the public internet. + +- `https://server-host/.well-known/openid-configuration` +- `https://server-host/.well-known/jwks` + +These must be exposed with anonymous access on HTTPS. Without this, the OpenID Connect protocol will not be able to complete the authentication flow. + +The hostname of the URL that these two endpoints are available on must either be configured under **Configuration->Nodes->Server Uri** or set as the first ListenPrefix in the server configuration. + +#### Azure Service Principal configuration + +To manually create a Federated Credential follow the [Add a federated credential](https://oc.to/create-azure-credentials) section in the Azure AD documentation, or create it with a [script](#create-federated-credential-via-script). + +The federated credential will need the **Issuer** value set to the publicly accessible Octopus Server URI configured in the previous step, this value must also not have a trailing slash (/), for example `https://samples.octopus.app`. + +Please read [OpenID Connect Subject Identifier](/docs/infrastructure/accounts/openid-connect) on how to customize the **Subject** value. + +The **Audience** value can be left at the default, or set to a custom value if needed. + +#### Azure Tool support for OpenID Connect + +To support OpenID Connect authentication, you will need to ensure it is supported in the versions of the tooling: + +- az CLI requires 2.30+ +- az PowerShell modules requires 7.0+ +- AzureRM terraform provider required 3.22+ + ## Resource permissions {#resource-permissions} The final step is to ensure your registered app has permission to work with your Azure resources. @@ -76,25 +105,39 @@ Next, if you want to get even more granular you can constrain the service princi The reason behind this has to do with the way Octopus queries for the web app resources in Azure. In order to handle scenarios where [ASEs](/docs/deployments/azure/ase/#resource_groups) are being used, Octopus first queries the resource groups and then queries for the web apps within each resource group. When the service principal is assigned **Contributor** on a resource group it seems to implicitly get **Reader** on the subscription, but this doesn't seem to be the case when **Contributor** is assigned directly to a web app, so you have to assign **Reader** explicitly. -### Create an Service Principal with PowerShell {#create-service-principal-account-with-powershell} +### Create an Azure App Registration via script {#create-app-registration-via-script} -This step shows you how to create a Service Principal with the PowerShell script below, if you would rather use the Azure Portal to create the Service Principal, see [Create an Azure Service Principal With the Azure Portal](#create-service-principal-account-in-azure). +This step shows you how to script the creation of an Azure Active Directory App Registration :::div{.hint} During the script, you will be prompted to authenticate with Azure. The authenticated user must have administrator permissions in the Active Directory in which the Service Principal is being created. ::: +
+Az CLI + +```bash +# this script will create a new Azure AD App Registration + +subscription='' # Replace with the name or id of your subscription +appName='' # Replace with your app registration name + +az login +az account set --subscription $subscription +az ad app create --display-name "$appName" -o table --query "{Id:id,Name:displayName,ClientId:appId}" +az account show --query "{Name:name,SubscriptionId:id,TenantId:tenantId}" -o table +``` +
+
Az PowerShell ```powershell -# This script will create a new service principal for you to use in Octopus Deploy using the Az PowerShell modules. This will work with both PowerShell and PowerShell Core. +# this script will create a new Azure AD App Registration $AzureTenantId = "2a681dca-3230-4e01-abcb-b1fd225c0982" # Replace with your Tenant Id $AzureSubscriptionName = "YOUR SUBSCRIPTION NAME" # Replace with your subscription name $AzureApplicationName = "YOUR APPLICATION NAME" # Replace with your application name -$AzurePasswordEndDays = "365" # Update to change the expiration date of the password -$AzurePassword = "$(New-Guid)$(New-Guid)" -replace "-", "" # Replace this if you want to have a known password if (Get-Module -Name Az -ListAvailable) { @@ -112,82 +155,204 @@ Import-Module -Name Az Write-Host "Logging into Azure" Connect-AzAccount -Tenant $AzureTenantId -Subscription $AzureSubscriptionName -Write-Host "Auto-generating new password" -$securePassword = ConvertTo-SecureString $AzurePassword -AsPlainText -Force - -$endDate = (Get-Date).AddDays($AzurePasswordEndDays) - $azureSubscription = Get-AzSubscription -SubscriptionName $AzureSubscriptionName $ExistingApplication = Get-AzADApplication -DisplayName "$AzureApplicationName" if ($null -eq $ExistingApplication) { Write-Host "The Azure Active Directory Application does not exist, creating Azure Active Directory application" - $azureAdApplication = New-AzADApplication -DisplayName "$AzureApplicationName" -HomePage "http://octopus.com" -IdentifierUris "http://octopus.com/$($AzureApplicationName)" -Password $securePassword -EndDate $endDate + $azureAdApplication = New-AzADApplication -DisplayName "$AzureApplicationName" - Write-Host "Creating Azure Active Directory service principal" - $servicePrincipal = New-AzADServicePrincipal -ApplicationId $azureAdApplication.ApplicationId - - Write-Host "Azure Service Principal successfully created" - $AzureApplicationId = $azureAdApplication.ApplicationId + Write-Host "Azure App Registration successfully created" + $AzureApplication = $azureAdApplication } else { - Write-Host "The azure service principal $AzureApplicationName already exists, creating a new password for Octopus Deploy to use." - New-AzADAppCredential -DisplayName "$AzureApplicationName" -Password $securePassword -EndDate $endDate - Write-Host "Azure Service Principal successfully password successfully created." - $AzureApplicationId = $ExistingApplication.ApplicationId + Write-Host "The Azure service principal $AzureApplicationName already exists" + $AzureApplication = $ExistingApplication } Write-Host "Important information to know when registering this subscription with Octopus Deploy:" Write-Host " 1) The Azure Tenant Id is: $AzureTenantId" Write-Host " 2) The Azure Subscription Id: $($azureSubscription.SubscriptionId)" -Write-Host " 3) The Azure Application Id: $AzureApplicationId" -Write-Host " 4) The new password is: $AzurePassword - this is the only time you'll see this password, please store it in a safe location." -``` +Write-Host " 3) The Azure Application Id: $(AzureApplication.AppId)" +```
+ +### Create a Service Principal Client Secret with PowerShell {#create-a-client-secret-via-script} + +This step shows you how to create a Service Principal Client Secret with the script below. + +:::div{.hint} +During the script, you will be prompted to authenticate with Azure. The authenticated user must have administrator permissions in the Active Directory in which the Service Principal is being created. +::: + +
-AzureRM PowerShell +Az CLI + +```bash +# This script will create a new client secret for you to use in Octopus Deploy using the Az CLI. +subscription='' # Replace with the name or id of your subscription +appId='' # Replace id of your application registration +expiryYears=1 + +az login +az account set --subscription $subscription +az ad app credential reset --append --id $appId --years $expiryYears +``` + +
+Az PowerShell ```powershell -# Obviously, replace the following with your own values -Write-Host "This script requires Azure PowerShell 1.0 or greater which can be downloaded here: https://azure.microsoft.com/en-us/documentation/articles/powershell-install-configure/" -$subscriptionId = "cd21dc34-73dc-4c7d-bd86-041284e0bc45" -$tenantId = "2a681dca-3230-4e01-abcb-b1fd225c0982" -$password = "correct horse battery staple" - -# Login to your Azure Subscription -Login-AzureRMAccount -Set-AzureRMContext -SubscriptionId $subscriptionId -TenantId $tenantId - -# Create an Octopus Deploy Application in Active Directory -Write-Output "Creating AAD application..." -$securePassword = ConvertTo-SecureString $password -AsPlainText -Force -$azureAdApplication = New-AzureRmADApplication -DisplayName "Octopus Deploy" -HomePage "http://octopus.com" -IdentifierUris "http://octopus.com" -Password $securePassword -$azureAdApplication | Format-Table +# This script will create a new client secret for you to use in Octopus Deploy using the Az PowerShell modules. This will work with both PowerShell and PowerShell Core. -# Create the Service Principal -Write-Output "Creating AAD service principal..." -$servicePrincipal = New-AzureRmADServicePrincipal -ApplicationId $azureAdApplication.ApplicationId -$servicePrincipal | Format-Table +$AzureTenantId = "2a681dca-3230-4e01-abcb-b1fd225c0982" # Replace with your Tenant Id +$AzureSubscriptionName = "YOUR SUBSCRIPTION NAME" # Replace with your subscription name +$AzureApplicationName = "YOUR APPLICATION NAME" # Replace with your application name +$AzurePasswordEndDays = "365" # Update to change the expiration date of the password + +if (Get-Module -Name Az -ListAvailable) +{ + Write-Host "Azure Az Module found." +} +else +{ + Write-Host "Azure Az Modules not found. Installing the Azure Az PowerShell Modules. You might be prompted that PSGallery is untrusted. If you select Yes your screen might freeze for a second while the modules download process is started." + Install-Module -Name Az -AllowClobber -Scope CurrentUser +} -# Sleep, to Ensure the Service Principal is Actually Created -Write-Output "Sleeping for 10s to give the service principal a chance to finish creating..." -Start-Sleep -s 10 +Write-Host "Loading the Azure Az Module. This may cause the screen to freeze while loading the module." +Import-Module -Name Az -# Assign the Service Principal the Contributor Role to the Subscription. -# Roles can be Granted at the Resource Group Level if Desired. -Write-Output "Assigning the Contributor role to the service principal..." -New-AzureRmRoleAssignment -RoleDefinitionName Contributor -ServicePrincipalName $azureAdApplication.ApplicationId +Write-Host "Logging into Azure" +Connect-AzAccount -Tenant $AzureTenantId -Subscription $AzureSubscriptionName -# The Application ID (aka Client ID) will be Required When Creating the Account in Octopus Deploy -Write-Output "Client ID: $($azureAdApplication.ApplicationId)" +$endDate = (Get-Date).AddDays($AzurePasswordEndDays) + +$azureSubscription = Get-AzSubscription -SubscriptionName $AzureSubscriptionName +$ExistingApplication = Get-AzADApplication -DisplayName "$AzureApplicationName" + +if ($null -eq $ExistingApplication) { + Write-host "Unable to find application with name '$AzureApplicationName'" +} else { + Write-Host "The Azure service principal $AzureApplicationName already exists, creating a new password for Octopus Deploy to use." + $credential = New-Object Microsoft.Azure.PowerShell.Cmdlets.Resources.MSGraph.Models.ApiV10.MicrosoftGraphPasswordCredential + $credential.EndDateTime = $endDate + $credential.DisplayName = "$AzureApplicationName" + $newCredential = New-AzADAppCredential -PasswordCredentials @($credential) -ApplicationId $ExistingApplication.AppId + Write-Host "Azure Service Principal successfully password successfully created." + + Write-Host "Important information to know when registering this subscription with Octopus Deploy:" + Write-Host " 1) The Azure Tenant Id is: $AzureTenantId" + Write-Host " 2) The Azure Subscription Id: $($azureSubscription.SubscriptionId)" + Write-Host " 3) The Azure Application Id: $($ExistingApplication.AppId)" + Write-Host " 4) The new password is: $($newCredential.SecretText) - this is the only time you'll see this password, please store it in a safe location." +} ```
-The values required for the script above are: +- **Subscription ID**: The ID of the Azure subscription the account will interact with. +- **Password**: A secret value created by you. Make sure you record it, as you will need to enter it into Octopus Deploy. +- **Tenant ID**: The ID of the Active Directory tenant. You can find this in the Azure Portal by navigating to **Azure Active Directory ➜ Properties** in the **Tenant ID** field. + +The Service Principal will default to expiring in 1 year from the time of creation. + +You can specify the expiry date by adding the *-EndDate* parameter to the *New-AzureRmADApplication* command: + +```powershell +-EndDate (new-object System.DateTime 2018, 12, 31) +``` + +Now, you can [add the Service Principal Account in Octopus](#add-service-principal-account). Consider reading our [note on least privilege first](#note_on_least_privilege). + + +### Create a Service Principal Client Secret with PowerShell {#create-a-client-secret-via-script} + +This step shows you how to create a Service Principal Client Secret with the script below. + +:::div{.hint} +During the script, you will be prompted to authenticate with Azure. The authenticated user must have administrator permissions in the Active Directory in which the Service Principal is being created. +::: + + +
+Az CLI + +```bash +# This script will create a new federated credential for you to use in Octopus Deploy using the Az CLI. +subscription='' # Replace with the name or id of your subscription +appId='' # Replace id of your application registration + +credential='{ + "name": "Testing", + "issuer": "https://oidc-client-test.testoctopus.app", + "subject": "space:default:project:something", + "description": "Testing", + "audiences": [ + "api://AzureADTokenExchange" + ] +}' + +az login +az account set --subscription "$subscription" +az ad app federated-credential create --id $appId --parameters "$credential" +``` + +
+Az PowerShell + +```powershell +# This script will create a new client secret for you to use in Octopus Deploy using the Az PowerShell modules. This will work with both PowerShell and PowerShell Core. + +$AzureTenantId = "2a681dca-3230-4e01-abcb-b1fd225c0982" # Replace with your Tenant Id +$AzureSubscriptionName = "YOUR SUBSCRIPTION NAME" # Replace with your subscription name +$AzureApplicationName = "YOUR APPLICATION NAME" # Replace with your application name +$AzurePasswordEndDays = "365" # Update to change the expiration date of the password + +if (Get-Module -Name Az -ListAvailable) +{ + Write-Host "Azure Az Module found." +} +else +{ + Write-Host "Azure Az Modules not found. Installing the Azure Az PowerShell Modules. You might be prompted that PSGallery is untrusted. If you select Yes your screen might freeze for a second while the modules download process is started." + Install-Module -Name Az -AllowClobber -Scope CurrentUser +} + +Write-Host "Loading the Azure Az Module. This may cause the screen to freeze while loading the module." +Import-Module -Name Az + +Write-Host "Logging into Azure" +Connect-AzAccount -Tenant $AzureTenantId -Subscription $AzureSubscriptionName + +$endDate = (Get-Date).AddDays($AzurePasswordEndDays) + +$azureSubscription = Get-AzSubscription -SubscriptionName $AzureSubscriptionName +$ExistingApplication = Get-AzADApplication -DisplayName "$AzureApplicationName" + +if ($null -eq $ExistingApplication) { + Write-host "Unable to find application with name '$AzureApplicationName'" +} else { + Write-Host "The Azure service principal $AzureApplicationName already exists, creating a new password for Octopus Deploy to use." + $credential = New-Object Microsoft.Azure.PowerShell.Cmdlets.Resources.MSGraph.Models.ApiV10.MicrosoftGraphPasswordCredential + $credential.EndDateTime = $endDate + $credential.DisplayName = "$AzureApplicationName" + $newCredential = New-AzADAppCredential -PasswordCredentials @($credential) -ApplicationId $ExistingApplication.AppId + Write-Host "Azure Service Principal successfully password successfully created." + + Write-Host "Important information to know when registering this subscription with Octopus Deploy:" + Write-Host " 1) The Azure Tenant Id is: $AzureTenantId" + Write-Host " 2) The Azure Subscription Id: $($azureSubscription.SubscriptionId)" + Write-Host " 3) The Azure Application Id: $($ExistingApplication.AppId)" + Write-Host " 4) The new password is: $($newCredential.SecretText) - this is the only time you'll see this password, please store it in a safe location." +} +``` + +
- **Subscription ID**: The ID of the Azure subscription the account will interact with. - **Password**: A secret value created by you. Make sure you record it, as you will need to enter it into Octopus Deploy. @@ -201,12 +366,16 @@ You can specify the expiry date by adding the *-EndDate* parameter to the *New-A -EndDate (new-object System.DateTime 2018, 12, 31) ``` -Now, you can [add the Service Principal Account in Octopus](#add-service-principal-account). Consider reading our [note on least privilege first](#note_on_lease_privilege). +Now, you can [add the Service Principal Account in Octopus](#add-service-principal-account). Consider reading our [note on least privilege first](#note_on_least_privilege). + + + ## Add the Service Principal account in Octopus {#add-service-principal-account} Now that you have the following values, you can add your account to Octopus: +- Subscription ID - Application ID - Tenant ID - Application Password/Key @@ -221,7 +390,7 @@ Now that you have the following values, you can add your account to Octopus: Click **SAVE AND TEST** to confirm the account can interact with Azure. Octopus will then attempt to use the account credentials to access the Azure Resource Management (ARM) API and list the Resource Groups in that subscription. You may need to include the appropriate IP Addresses for the Azure Data Center you are targeting in any firewall allow list. See [deploying to Azure via a Firewall](/docs/deployments/azure) for more details. :::div{.hint} -A newly created Service Principal may take several minutes before the credential test passes. If you have double checked your credential values, wait 15 minutes and try again. +A newly created Service Principal may take several minutes before the credential test passes. If you have double-checked your credential values, wait 15 minutes and try again. ::: ## Creating an Azure Management Certificate account {#azure-management-certificate} @@ -234,7 +403,7 @@ The Azure Service Management APIs are being deprecated by Microsoft. See [this To create an Azure Management Certificate account as part of adding an [Azure subscription](#adding-azure-subscription), select Management Certificate as the Authentication Method. -### Step 1: Management Certificate {#CreatinganAzureManagementCertificateAccount-Step2-ManagementCertificate} +### Step 1: Management Certificate {#CreatingAnAzureManagementCertificateAccount-Step2-ManagementCertificate} When using **Management Certificate**, Octopus authenticates with Azure using an X.509 certificate. You can either upload an existing certificate (`.pfx`), or leave the field blank and Octopus will generate a certificate. Keep in mind that since Octopus securely stores the certificate internally, there is no need to upload a password protected `.pfx` file. If you would like to use one that is password protected, you will need to first remove the password. This can be done with the following commands. @@ -252,7 +421,7 @@ Uploaded certificates can be viewed on the 'Management Certificates' tab of the The certificate will be named **Octopus Deploy -``{Your Account Name}**. -### Step 2: Save and Test {#CreatinganAzureManagementCertificateAccount-Step3-SaveandTest} +### Step 2: Save and Test {#CreatingAnAzureManagementCertificateAccount-Step3-SaveAndTest} Click **Save and Test**, and Octopus will attempt to use the account credentials to access the Azure Service Management (ASM) API and list the Hosted Services in that subscription. You may need to include the appropriate IP Addresses for the Azure Data Center you are targeting in any firewall allow list. See [deploying to Azure via a Firewall](/docs/deployments/azure) for more details. diff --git a/src/pages/docs/infrastructure/accounts/openid-connect.md b/src/pages/docs/infrastructure/accounts/openid-connect.md new file mode 100644 index 0000000000..3bdf5a1db9 --- /dev/null +++ b/src/pages/docs/infrastructure/accounts/openid-connect.md @@ -0,0 +1,91 @@ +--- +layout: src/layouts/Default.astro +pubDate: 2023-22-09 +modDate: 2023-22-09 +title: OpenID Connect +description: How to customize the Subject Claim for OpenID Connect authentication +navOrder: 70 +--- + +## Configuration + +:::div{.info} +If you are using Octopus Cloud, you will not need to do anything to expose the instance to the public internet, this is already configured for you. +::: + +To use federated credentials, your Octopus instance will need to have two anonymous URLs exposed to the public internet. + +- `https://server-host/.well-known/openid-configuration` +- `https://server-host/.well-known/jwks` + +These must be exposed with anonymous access on HTTPS. Without this, the OpenID Connect protocol will not be able to complete the authentication flow. + +The hostname of the URL that these two endpoints are available on must either be configured under **Configuration->Nodes->Server Uri** or set as the first ListenPrefix in the server configuration. + +## Authenticating using OpenID Connect with third party services and tools + +If you have a third-party service or tool that supports OpenID Connect, you can add any OIDC account variable into your projects variable set and use the `[account name].OpenIDConnect.Jwt` variable to get access to the request token that can be used for authenticating. + +## Subject Keys + +When using OpenID Connect to authenticate to with external services, the Subject claim can have its contents customized. + +This allows you to grant resource access at a fine or coarse grained level in your Cloud host, depending on your requirements. + +The subject can be modified for the three different uses within Octopus: + +- [Deployments and Runbooks](#deployments-and-runbooks) +- [Health Checks](#health-checks) +- [Account Test](#account-test) + +### Subject key parts + +- Only the requested keys for a **Subject** claim will be include in the generated **Subject** claim +- Any resource types include in the **Subject** claim will use the slug value for the resource. The slug value is generated from the name of the resource when it was created, it can be edited on the edit page of resource type. +- The **Subject** claim parts will always be in the following order + - **Space** + - **Project** + - **Runbook** + - **Tenant** + - **Environment** + - **Target** + - **Account** + - **Type** + + +### Deployments and Runbooks {#deployments-and-runbooks} + +The **Subject** claim for a deployment or a runbook supports the following parts: + +- **Space** slug +- **Project** slug +- **Runbook** slug +- **Tenant** slug +- **Environment** slug +- **Account** slug +- **Type** + +The default format for a deployment and runbook is `space:[space-slug]:project:[project-slug]:tenant:[tenant-slug]:environment:[environment-slug]`. + +The value for the type is either `deployment` or `runbook`. + +When changing the **Subject** claim format for a deployment and runbook, the runbook value will not be included (if specified) when running a deployment. + +For example, in the **Default** space, you have a project called **Deploy Web App**, and a runbook called **Restart**. If you set the **Subject** claim format to `space`, `project`, `runbook` and `type`, when running a deployment the **Subject** claim will be `space:default:project:deploy-web-app:type:deployment` and for the run of the runbook the **Subject** claim would be `space:default:project:deploy-web-app:runbook:restart:type:runbook`. +This is using the default generated slug values for the space, project and runbook. + +## Health Checks {#health-checks} + +The Health Check **Subject** claim supports the **Space** slug, the **Target** slug and the **Type** + +The default format for a health check is `space:[space-slug]:target:[target-slug]`. + +The value for the type is `health`. + + +## Account Test {#account-test} + +The Account Test **Subject** claim supports the **Space** slug, the **Account** slug and the **Type** + +The default format for an account test is `space:[space-slug]:account:[account-slug]`. + diff --git a/src/pages/docs/infrastructure/signing-keys/index.md b/src/pages/docs/infrastructure/signing-keys/index.md new file mode 100644 index 0000000000..660a86e0f4 --- /dev/null +++ b/src/pages/docs/infrastructure/signing-keys/index.md @@ -0,0 +1,25 @@ +--- +layout: src/layouts/Default.astro +pubDate: 2023-11-01 +modDate: 2023-11-01 +title: Signing Keys +description: Signing keys used for OpenID Connect authentication +navOrder: 40 +hideInThisSection: true +--- + +Octopus uses a Signing Key to sign the generated authorization request tokens used in the authentication flow for OpenID Connect. The public signing key is used by the resource server to validate the token supplied by Octopus. + +The signing keys by default have a 90-day expiry and will be rotated when they expire. + +:::div{.warning} +Since OpenID Connect authentication is still an EAP feature, there is no User Interface to manage or view the Signing Keys. + +The following API endpoints can be used to manage the Signing Keys: + +List all keys: `GET` `/api/signingkeys/v1` + +Rotate the active key: `POST` `/api/signingkeys/rotate/v1` + +Revoke a signing key: `POST` `/api/signingkeys/{id}/revoke/v1` +::: \ No newline at end of file