Headless login flow updates (#1811)

Updating Custom IDP overview to highlight that `--headless` login flow
works with custom IDPs (was not available until
[recently](chainguard-dev/customer-issues#1379 (comment)),
will land next week).

I also realized we didn't have the `--headless` option documented
anywhere else. For that matter, we don't have a simple, central "this is
how you can log in" explo anywhere either. I added one to the IAM
overview doc, not sure if there's a better place for it.

Temporarily leaving this as a draft PR b/c the feature won't land until
next week.

resolves chainguard-dev/internal#3908

---------

Signed-off-by: Mark Drake <[email protected]>

content/chainguard/administration/custom-idps/custom-idps/index.md

@@ -29,6 +29,25 @@ chainctl auth login --identity-provider=$IDP_ID
 
 You can retrieve all your identity provider's unique IDs by running `chainctl iam identity-providers list`.
 
+Note that you can also use the [`--headless` option](/chainguard/administration/iam-organizations/overview-of-chainguard-iam-model/#using-the-headless-login-flow) to log in with a custom IDP in an environment that doesn't have a browser installed, such as a container or a remote server. By including this option, `chainctl` will output a special URL. You can then navigate to the URL in another device's browser to log in with your custom IDP.
+
+To log in with a custom IDP using the `--headless` option, you would run a command like the following:
+
+```sh
+chainctl auth login --headless --identity-provider=$IDP_ID
+```
+
+Then you can use the URL in this command's output to complete the login flow from another device's browser.
+
+> **Note**: As of this writing (September 2024), using the headless login flow with a custom IDP is still an experimental feature. Please reach out to us through your customer success manager or the support portal to report any feedback. Also, until this feature becomes enabled by default, you must enable it yourself with the following command:
+
+```sh
+chainctl config set auth.device-flow chainguard
+```
+
+
+### Setting a default identity provider
+
 As an alternative to remembering identity provider IDs, you can set the default identity provider by editing the `chainctl` configuration file. You can do so with the following command.
 
 ```sh
@@ -52,7 +71,6 @@ chainctl config set default.identity-provider <your identity provider id here>
 
 Once set, the configured identity provider will be used automatically any time you run `chainctl auth login`.
 
-> **Note**: `chainctl auth login --headless` is not currently compatible with SSO authentication.
 
 ### Authenticate with `chainctl` using a Verified Organization
 

content/chainguard/administration/iam-organizations/overview-of-chainguard-iam-model.md

@@ -37,3 +37,28 @@ In order to create an invitation for a new user, you must choose a role for that
 
 You can also create assumable identities. These are typically used to allow automation tools like GitHub Actions or Amazon Lambda to connect to and manage Chainguard resources. Refer to our [guide on assumable identities](/chainguard/administration/iam-organizations/assumable-ids/) to learn more.
 
+
+## Logging in to the Chainguard Platform
+
+To authenticate into the Chainguard platform, run the following login command.
+
+```sh
+chainctl auth login
+```
+
+A web browser window will open to prompt you to log in via your chosen OIDC flow. Select the account which you wish to log in as, and you can then begin managing your Chainguard resources.
+
+### Using the headless login flow
+
+Note that you can also use `chainctl`'s `--headless` option to log in. This option allows you to log in to the Chainguard platform from a device that doesn't have a browser installed, such as a container or remote server.
+
+The headless login flow is when you invoke `chainctl auth login --headless` in the terminal. 
+
+```sh
+chainctl auth login --headless
+```
+
+By including this option, `chainctl` will output an eight-character code as well as a URL ([`https://auth.chainguard.dev/activate`](https://auth.chainguard.dev/activate)). You can then navigate to the URL on another device's browser and enter the code, and then you can complete the login process to Chainguard from that device.
+
+Be aware that the `--headless` login code will only be valid for 900 seconds. 
+