Small improvements to OIDC docs based on recent feedback (#2130)

src/pages/docs/octopus-rest-api/openid-connect/github-actions.md

@@ -37,6 +37,10 @@ The [`OctopusDeploy/login`](https://github.com/OctopusDeploy/login) action obtai
 
 The ID token that GitHub generates contains a subject (the `sub` property in the ID token), which is generated based on the details of the workflow that is being run. The subject of the OIDC identity in Octopus needs to match this subject exactly in order for the access token to be issued, the Octopus Portal will help you to generate this subject correctly.
 
+:::div{.hint}
+Currently there is no support for wildcards when filtering workflow runs, support for this may be available in a future version of Octopus.
+:::
+
 The details of the subject that GitHub Actions will generate follow specific rules including:
 
 - Whether a GitHub `environment` is being used within the workflow
@@ -88,7 +92,9 @@ To use the [`OctopusDeploy/login`](https://github.com/OctopusDeploy/login) actio
 jobs:
   octopus:
     permissions:
-      id-token: write
+      # Add any additional permissions your job requires here
+      id-token: write # This is required to obtain the ID token from GitHub Actions
+      contents: read # For example: this is required to check out code, remove if not needed
     steps: ...
 ```
 
@@ -146,7 +152,9 @@ jobs:
     runs-on: ubuntu-latest
     name: Create a release in Octopus
     permissions:
+      # Add any additional permissions your job requires here
       id-token: write # This is required to obtain the ID token from GitHub Actions
+      contents: read # For example: this is required to check out code, remove if not needed
     steps:
       - name: Login to Octopus
         uses: OctopusDeploy/login@v1

src/pages/docs/octopus-rest-api/openid-connect/index.md

@@ -10,6 +10,12 @@ hideInThisSection: true
 
 Octopus supports using [OpenID Connect (OIDC)](https://openid.net/) to access the Octopus API without needing to provision API keys.
 
+:::div{.hint}
+Using OIDC to access the Octopus API is used for machine-to-machine scenarios such as a automating release creation in CI servers.
+
+See [authentication providers](/docs/security/authentication) for information on configuring user authentication into Octopus Deploy.
+:::
+
 ## What is OpenID Connect and how is it used in Octopus?
 
 OpenID Connect is a set of identity specifications that build on OAuth 2.0 to allow software systems to connect to each other in a way that promotes security best practices.
@@ -88,7 +94,9 @@ jobs:
     runs-on: ubuntu-latest
     name: Create a release in Octopus
     permissions:
+      # Add any additional permissions your job requires here
       id-token: write # This is required to obtain the ID token from GitHub Actions
+      contents: read # For example: this is required to check out code, remove if not needed
     steps:
       - name: Login to Octopus
         uses: OctopusDeploy/login@v1

src/pages/docs/octopus-rest-api/openid-connect/other-issuers.md

@@ -28,6 +28,10 @@ The first step is to create an OIDC identity for your issuer to access the Octop
 6. Enter the subject of the identity. This must match exactly the subject that is provided in the OIDC token and is _case-sensitive_. The format of the subject will differ by issuer, please consult your OIDC issuers documentation.
 7. Click Save.
 
+:::div{.hint}
+Currently there is no support for wildcards when configuring the subject of an identity, support for this may be available in a future version of Octopus.
+:::
+
 :::div{.hint}
 Multiple OIDC identities can be added for a service account.
 :::