diff --git a/docs/security/authentication/azure-ad-authentication.md b/docs/security/authentication/azure-ad-authentication.md index 7238afd6ff..2a4a9fffdd 100644 --- a/docs/security/authentication/azure-ad-authentication.md +++ b/docs/security/authentication/azure-ad-authentication.md @@ -51,6 +51,10 @@ Take care when you add this URL. They are **case-sensitive** and can be sensitiv #### Enable ID Tokens and configure +:::hint +Support for OAuth code flow with PKCE was introduced in **Octopus 2022.2.4498**. This step is not required for any newer versions of Octopus. We instead suggest following the instructions for generating a client secret below. +::: + 1. Within your new App registration in AzureAD navigate to Authentication. 2. Ensure the ID Tokens box is enabled: @@ -152,34 +156,44 @@ If you only have one role it will be automatically assigned. If you have **multi ## Configure Octopus Server -### Get the client ID and Issuer +There are three values you need from the Azure AD configuration to complete the Octopus configuration: the **Client ID**, **Client Secret** and **Issuer**. -There are two values you need from the Azure AD configuration to complete the Octopus configuration: the **Client ID** and **Issuer**. +### Get the Client ID and Issuer -#### Using the Azure portal - -In the Azure portal, you can see the **Application (client) ID** and **Directory (tenant) ID** on your App's Overview page. +In the Azure portal, you can see the **Application (client) ID** and **Directory (tenant) ID** on your App's Overview page. ![Getting the App registration](images/aad-get-app-registration-id.png "width=500") -### Setting the client ID and Issuer in Octopus Deploy +### Generate the Client secret + +In the Azure portal, navigate to the **Certificates & secrets** page and click **New client secret** to generate a new client secret for the App registration. + +![Generating a client secret](images/aad-client-secret.png "width=500") + +### Setting the Client ID, Client secret and Issuer in Octopus Deploy + +:::hint +Support for OAuth code flow with PKCE was introduced in **Octopus 2022.2.4498**. If you are using a version older than this, the client secret setting is not required. +::: :::success Your **Client ID** should be a GUID. This is the **Application (client) ID** in the Azure App Registration Portal. +Your **Client secret** should be a long string value. This is the **Value** of a client secret in the Azure App Registration Portal. + Your **Issuer** should be a URL like `https://login.microsoftonline.com/GUID` where the GUID is a particular GUID identifying your Azure Active Directory tenant. This is the **Directory (tenant) ID** in the Azure App Registration Portal. ::: When you have those values, run the following from a command prompt in the folder where you installed Octopus Server: ```powershell -Octopus.Server.exe configure --azureADIsEnabled=true --azureADIssuer=Issuer --azureADClientId=ClientID +Octopus.Server.exe configure --azureADIsEnabled=true --azureADIssuer=Issuer --azureADClientId=ClientID --azureADClientSecret=ClientSecret #Eg: -# Octopus.Server.exe configure --azureADIsEnabled=true --azureADIssuer=https://login.microsoftonline.com/12341234-xxxx-xxxx-xxxx-xxxxxxxxxxxx --azureADClientId=43214321-xxxx-xxxx-xxxx-xxxxxxxxxxxx +# Octopus.Server.exe configure --azureADIsEnabled=true --azureADIssuer=https://login.microsoftonline.com/12341234-xxxx-xxxx-xxxx-xxxxxxxxxxxx --azureADClientId=43214321-xxxx-xxxx-xxxx-xxxxxxxxxxxx --azureADClientSecret=bCeXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX ``` -Alternatively, these settings can be defined through the user interface by selecting **{{Configuration,Settings,Azure AD}}** and populating the fields **Issuer**, **ClientId**, and **IsEnabled**. +Alternatively, these settings can be defined through the user interface by selecting **{{Configuration,Settings,Azure AD}}** and populating the fields **Issuer**, **ClientId**, **ClientSecret**, and **IsEnabled**. ![Settings](images/aad-azure-ad-settings.png "width=500") diff --git a/docs/security/authentication/googleapps-authentication.md b/docs/security/authentication/googleapps-authentication.md index 9610f56b56..fa7f7643ef 100644 --- a/docs/security/authentication/googleapps-authentication.md +++ b/docs/security/authentication/googleapps-authentication.md @@ -15,7 +15,7 @@ To configure an app within GoogleApps, you must have a Developer account at [htt Once you have an account, log in to [https://console.developers.google.com](https://console.developers.google.com) and the following actions: 1. Create a project for Octopus (this might take a minute or so) and then within that project -2. Select **{{API Manager,Credentials menu}}**. +2. Select **{{APIs & Services,Credentials menu}}**. 3. Set the **OAuth consent screen** information. In the **Application Logo** box, upload a logo to make it easy to identify the application. You can download the Octopus logo [here](https://octopus.com/images/company/Logo-Blue_140px_rgb.png "width=500"). 4. Add the Top Level Domain of your Octopus instance to the **Authorized domains** list. If you are setting Google Apps up for **Hosted Octopus** this will be `octopus.app` or `octopus.com`. 5. Select the Credentials tab and Create a new **OAuth client ID** for a **Web app**. @@ -31,15 +31,19 @@ Octopus integrates with [Let's Encrypt](/docs/security/exposing-octopus/lets-enc ## Configure Octopus Server {#GoogleAppsauthentication-ConfiguringOctopusDeployServer} -You can configure the GoogleApps settings from the command line. You will need the **Client ID** from the Credentials tab and your **hosted domain name**. +You can configure the GoogleApps settings from the command line. You will need the **Client ID** and **Client secret** from the Credentials tab and your **hosted domain name**. + +:::hint +Support for OAuth code flow with PKCE was introduced in **Octopus 2022.2.4498**. If you are using a version older than this, the client secret setting is not required. +::: Once you have those values, run the following from a command prompt in the folder where you installed Octopus Server: ```powershell -Octopus.Server.exe configure --googleAppsIsEnabled=true --googleAppsClientId=ClientID --googleAppsHostedDomain=yourdomain.com +Octopus.Server.exe configure --googleAppsIsEnabled=true --googleAppsClientId=ClientID --googleAppsClientSecret=ClientSecret --googleAppsHostedDomain=yourdomain.com ``` -Alternatively these settings can be defined through the user interface by selecting **{{Configuration,Settings,GoogleApps}}** and populating the fields `Hosted Domain`, `Client Id` and `Is Enabled`. +Alternatively these settings can be defined through the user interface by selecting **{{Configuration,Settings,GoogleApps}}** and populating the fields `Is Enabled`, `Hosted Domain`, `Client ID` and `Client Secret`. ![Settings](images/google.png "width=500") diff --git a/docs/security/authentication/images/aad-client-secret.png b/docs/security/authentication/images/aad-client-secret.png new file mode 100644 index 0000000000..6ac964315f Binary files /dev/null and b/docs/security/authentication/images/aad-client-secret.png differ diff --git a/docs/security/authentication/images/google.png b/docs/security/authentication/images/google.png index 7d5d53e056..2b954d1c4c 100644 Binary files a/docs/security/authentication/images/google.png and b/docs/security/authentication/images/google.png differ diff --git a/docs/security/authentication/okta-authentication.md b/docs/security/authentication/okta-authentication.md index 89547a6fcc..a6dc48ea20 100644 --- a/docs/security/authentication/okta-authentication.md +++ b/docs/security/authentication/okta-authentication.md @@ -22,22 +22,18 @@ You must first have an account at [Okta](https://www.okta.com/). You can sign up Once you have an account, log in to the Okta admin portal. :::hint -After signing up to Okta you will receive your own url to access the Okta portal. For a developer account, it will look something similar to: `https://dev-xxxxxx-admin.oktapreview.com`. +After signing up to Okta you will receive your own url to access the Okta portal. For a developer account, it will look something similar to: `https://dev-xxxxxx-admin.okta.com`. ::: -1. Select the Applications tab and click the **Add Application** button. +1. Select the Applications tab and click the **Create App Integration** button. ![](okta/okta-add-app.png "width=500") -2. Click the **Create New App** button. - - ![](okta/okta-create-new-app.png "width=500") - -3. Choose **Web** for the **Platform** and **OpenID Connect** for the **Sign on method** and click the **Create** button. +2. Choose **Web** for the **OIDC - OpenID Connect** for the **Sign-in method** and **Web Application** for the **Application type** and click the **Next** button. ![](okta/okta-new-app-integration.png "width=400") -4. Enter an **Application Name** like Octopus Deploy and for the **Login redirect URIs** enter `https://octopus.example.com/api/users/authenticatedToken/Okta` replacing `https://octopus.example.com` with the public url of your Octopus Server, and click the **Save** button. +3. Enter an **App integration name** like Octopus Deploy and for the **Sign-in redirect URIs** enter `https://octopus.example.com/api/users/authenticatedToken/Okta` replacing `https://octopus.example.com` with the public URL of your Octopus Server, remove any default **Sign-out redirect URIs** and click the **Save** button. ![](okta/okta-create-openid-integration.png "width=500") @@ -48,23 +44,19 @@ After signing up to Okta you will receive your own url to access the Okta portal Octopus integrates with [Let's Encrypt](/docs/security/exposing-octopus/lets-encrypt-integration.md) making it easier to setup SSL on your Octopus Server. ::: -5. Under the **General Settings** for the app you have just created, ensure that **Implicit (Hybrid)** and **Allow ID Token with implicit grant type** are both checked, under the **Allowed grant types**. Click the **Save** button to continue. - - ![](okta/okta-general-settings.png "width=500") - If you want to allow users to log in directly from Okta then change the **Login initiated by** to _Either Okta or App_, set **Login flow** to _Redirect to app to initiate login_, and set the **Initiate login URI** to `https://octopus.example.com/#/users/sign-in`. ![](okta/okta-initiatelogin.png "width=500") +:::warning +Support for OAuth code flow with PKCE was introduced in **Octopus 2022.2.4498**. If you are using a version older than this you will need to also select the **Implicit (hybrid)** grant type. +::: + ### OpenID Connect settings {#Oktaauthentication-OpenIDConnectSettings} There are two values you will need from the Okta configuration to complete the Octopus configuration: the **Client ID** and **Issuer**. (The Client ID is also referred to as Audience.) -First, use Okta's _Classic UI_ by selecting it in the upper right hand menu - -![Okta Classic UI](okta/okta-classic-ui.png "width=500") - -Now select the **Sign On** tab and scroll down to the **OpenID Connect ID Token** section. Take note of the **Issuer** and **Audience** as you will need both these values to configure your Octopus Server. +Select the **Sign On** tab and scroll down to the **OpenID Connect ID Token** section. Take note of the **Issuer** and **Audience** as you will need both these values to configure your Octopus Server. ![](okta/okta-openid-token.png "width=500") @@ -97,29 +89,32 @@ Next you will need to assign your app to people or groups within your Okta direc ![](okta/okta-assign-app.png "width=500") -2. To assign the app to all users, you can simply assign the default **Everyone** group to the app, and click **Done**. - - ![](okta/okta-assign-to-groups.png "width=500") +2. The app may be assigned to **Everyone** by default. If not, to assign the app to all users, you can simply assign the default **Everyone** group to the app, and click **Done**. ## Configure Octopus Server {#Oktaauthentication-ConfiguringOctopusDeployServer} -You will need the **Client ID** (aka **Audience**) and **Issuer** obtained from the Okta portal as described above. +You will need the **Client ID** (aka **Audience**), **Client secret** and **Issuer** obtained from the Okta portal as described above. + +:::hint +Support for OAuth code flow with PKCE was introduced in **Octopus 2022.2.4498**. If you are using a version older than this, the client secret setting is not required. +::: :::success Your **Client ID** should be a string value like `0a4bxxxxxxxxxxxx9yc3`. +Your **Client secret** should be a string value like `uJxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxSS`. Your **Issuer** should be a URL like `https://dev-xxxxxx.oktapreview.com`. ::: Once you have those values, run the following from a command prompt in the folder where you installed Octopus Server: ```powershell -Octopus.Server.exe configure --OktaIsEnabled=true --OktaIssuer=Issuer --OktaClientId=ClientID +Octopus.Server.exe configure --OktaIsEnabled=true --OktaIssuer=Issuer --OktaClientId=ClientID --OktaClientSecret=ClientSecret #Eg: -# Octopus.Server.exe configure --OktaIsEnabled=true --OktaIssuer=https://dev-xxxxxx.oktapreview.com --OktaClientId=0a4bxxxxxxxxxxxx9yc3 +# Octopus.Server.exe configure --OktaIsEnabled=true --OktaIssuer=https://dev-xxxxxx.oktapreview.com --OktaClientId=0a4bxxxxxxxxxxxx9yc3 --OktaClientSecret=uJxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxSS ``` -Alternatively these settings can be defined through the user interface by selecting **{{Configuration,Settings,Okta}}** and populating the fields `Issuer`, `ClientId` and `IsEnabled`. +Alternatively these settings can be defined through the user interface by selecting **{{Configuration,Settings,Okta}}** and populating the fields `Issuer`, `ClientId`, `ClientSecret` and `IsEnabled`. ![Settings](okta/okta-settings.png "width=500") diff --git a/docs/security/authentication/okta/okta-add-app.png b/docs/security/authentication/okta/okta-add-app.png index 4ac2275f0a..049150501e 100644 Binary files a/docs/security/authentication/okta/okta-add-app.png and b/docs/security/authentication/okta/okta-add-app.png differ diff --git a/docs/security/authentication/okta/okta-assign-app.png b/docs/security/authentication/okta/okta-assign-app.png index b4869ee3a7..b406f4d4f3 100644 Binary files a/docs/security/authentication/okta/okta-assign-app.png and b/docs/security/authentication/okta/okta-assign-app.png differ diff --git a/docs/security/authentication/okta/okta-create-new-app.png b/docs/security/authentication/okta/okta-create-new-app.png deleted file mode 100644 index f13d97cdb5..0000000000 Binary files a/docs/security/authentication/okta/okta-create-new-app.png and /dev/null differ diff --git a/docs/security/authentication/okta/okta-create-openid-integration.png b/docs/security/authentication/okta/okta-create-openid-integration.png index 6b5a180cda..8f650dc748 100644 Binary files a/docs/security/authentication/okta/okta-create-openid-integration.png and b/docs/security/authentication/okta/okta-create-openid-integration.png differ diff --git a/docs/security/authentication/okta/okta-groups-claimtype.png b/docs/security/authentication/okta/okta-groups-claimtype.png index 5e568aaf16..1c0040ad24 100644 Binary files a/docs/security/authentication/okta/okta-groups-claimtype.png and b/docs/security/authentication/okta/okta-groups-claimtype.png differ diff --git a/docs/security/authentication/okta/okta-initiatelogin.png b/docs/security/authentication/okta/okta-initiatelogin.png index eeba6a8231..621cae1328 100644 Binary files a/docs/security/authentication/okta/okta-initiatelogin.png and b/docs/security/authentication/okta/okta-initiatelogin.png differ diff --git a/docs/security/authentication/okta/okta-new-app-integration.png b/docs/security/authentication/okta/okta-new-app-integration.png index 654c33d08a..800f1b069f 100644 Binary files a/docs/security/authentication/okta/okta-new-app-integration.png and b/docs/security/authentication/okta/okta-new-app-integration.png differ diff --git a/docs/security/authentication/okta/okta-openid-token.png b/docs/security/authentication/okta/okta-openid-token.png index 1899894147..dd3062296b 100644 Binary files a/docs/security/authentication/okta/okta-openid-token.png and b/docs/security/authentication/okta/okta-openid-token.png differ diff --git a/docs/security/authentication/okta/okta-settings.png b/docs/security/authentication/okta/okta-settings.png index db2d1f09fc..a17b3e68a1 100644 Binary files a/docs/security/authentication/okta/okta-settings.png and b/docs/security/authentication/okta/okta-settings.png differ