Update third-party OAuth authentication docs

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")
 

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")
 

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")