Add docs for using OpenID Connect with the Octopus API #2009
Conversation
|
|
||
| Octopus supports using [OpenID Connect (OIDC)](https://openid.net/) to access the Octopus API without needing to provision API keys. | ||
|
|
||
| Some of the benefits of using OIDC include: |
There was a problem hiding this comment.
I'm wondering if we want some sort of preamble to "what is OIDC" including these benefits here.
There was a problem hiding this comment.
Yeah I agree, It would also be nice to link out to an authoritative site that deals with the topic so that you dont need to go into deep detail here and can defer to the expertise elsewhere.
|
The extension for file |
|
Just realised you didnt add that file. Didnt even know that was a thing, ignore my comment 🙉 |
@zentron Haha yep I didn't know it was a thing until I saw it and had to look it up. Apparently you can use jsx inside markdown, who knew 🤷. |
|
|
||
| Octopus supports using [OpenID Connect (OIDC)](https://openid.net/) to access the Octopus API without needing to provision API keys. | ||
|
|
||
| Some of the benefits of using OIDC include: |
There was a problem hiding this comment.
Yeah I agree, It would also be nice to link out to an authoritative site that deals with the topic so that you dont need to go into deep detail here and can defer to the expertise elsewhere.
|
|
||
| - API keys do not need to be provisioned and stored in external systems, reducing the risk of unauthorized access to the Octopus API from exposed keys. | ||
| - Access tokens granted by Octopus are short-lived, reducing the risk of unauthorized access to the Octopus API. | ||
| - API keys do not need to be rotated manually by administrators, reducing the risk of disruption when updating to newer keys in external systems. |
There was a problem hiding this comment.
Its worth adding a comment/section about how the permissions provided by the token generated are based on the permissions provided by the service account. This allows the user to configure fine-grained controls for their needs, supporting our recommended principle of least access. Something that helps provide a background of why this architecture was selected
There was a problem hiding this comment.
That's true, the same thing applies when using API keys though right (the permissions come from the service account)? So it's not necessarily a benefit of oidc as such, but yeah could still be worth mentioning, perhaps more in terms of the OIDC identity itself is granular via the specific subject string, so it promotes principle of least access from the external in (if that makes sense).
| 1. Click the Copy to clipboard to copy the `OctopusDeploy/login` step. | ||
| 2. Paste the `OctopusDeploy/login` step into your workflow job. | ||
| 3. Add `id-token: write` to the `permissions` on the workflow job. This is required to allow the `OctopusDeploy/login` action to request an OIDC token from GitHub to use. | ||
| 1. Depending on the other steps you have in your workflow, you may need to add additional permissions such as `contents: read`. |
There was a problem hiding this comment.
What are those other steps that would require me to set this permission? Is there somewhere we can just link to at GitHub?
There was a problem hiding this comment.
An example of other steps that would now require additional specific permissions would be actions/checkout which will require contents: read. I remember getting tripped up when I first started playing with oidc because of the way it works, by default you don't need to supply any permissions to checkout code, but as soon as you say you want to get the id token you do need to ask for permission to read contents because using the permissions property resets it back to nothing. It's a bit of a footgun.
I'd really like to get to a place with the getting started where someone can follow it and have their workflow work first time, so it felt important to note this in some way, I wonder if having it as a callout with more detail and a link like you suggested might be helpful.
|
|
||
| ## Getting started with other issuers | ||
|
|
||
| To get started using OIDC with other issuers use the below instructions. For more information see [Using OpenID Connect with Other Issuers](./other-issuers.md). |
There was a problem hiding this comment.
Why do we split the details for this on this page, then on the other issuers page?
Are we going to repeat the steps here on that page?
There was a problem hiding this comment.
The idea was that this was supposed to be a minimal "getting started" kind of guide, with further explanation on the specific "other issuers" page. You are right we would most likely repeat the steps in some fashion, but maybe as separate sections with more detail rather than just dot points. I do wonder whether it makes sense to have a getting started for other issuers given how manual it is likely to be for users and different per issuer. It might make more sense for GitHub Actions given its first class.
Other improvements from review
geofflamrock
changed the title
geofflamrock
changed the title
|
@geofflamrock & @zentron are you happy for this to be merged? |
@steve-fenton-octopus yep I think so, I'm planning to merge them in today, if we get any more feedback we can iterate further to improve. |
This PR adds docs on using OpenID Connect (OIDC) to connect to the Octopus API, with specifics for GitHub Actions vs other issuers.