Document the faas-cli Device Authorization flow for SSO

docs/openfaas-pro/sso/cli.md

@@ -12,7 +12,47 @@ You'll need to start off by installing the faas-cli and the pro plugin. See: [CL
 
 Now you can log into the gateway using one of the defined JwtIssuers for your installation. If you have not defined a JwtIssuer yet, then see the overview post here: [Walkthrough of Identity and Access Management (IAM) for OpenFaaS](https://www.openfaas.com/blog/walkthrough-iam-for-openfaas/).
 
-If your IDP supports Proof Key for Code Exchange PKCE, then you can use the OAuth code flow:
+The faas-cli supports several OAuth 2.0 authorization flows for obtaining a token from your IdP:
+
+* `device_code` - Device authorization flow. Intended for authenticating a CLI on headless or remote systems.
+* `code` - Authorization code flow with PKCE. Interactive login that opens a browser on the machine running the CLI.
+* `client_credentials` - Non-interactive, server-to-server authentication using a client ID and secret.
+* `implicit` / `implicit-id` - Legacy implicit flows, kept for compatibility with older IdPs.
+
+Select which flow to use by passing its name to the `--grant` flag of the `faas-cli pro auth` command.
+
+#### Device authorization grant
+
+The device authorization flow lets you authenticate without a browser on the machine running the CLI. It prints a verification URL and a one-time code that you open from a browser on any other device to complete the login. This makes it well suited to headless or remote machines, such as a server accessed over SSH.
+
+```bash
+faas-cli pro auth \
+  --grant device_code \
+  --client-id CLIENT_ID \
+  --authority https://oidc.example.com \
+  --gateway https://gateway.example.com
+```
+
+Open the printed verification URL in a browser on any device, enter the code, and complete the login with your IdP. Once you have authorized the request, the JWT is exchanged for an OpenFaaS access token, and the CLI is ready to use.
+
+If the machine running the CLI has a browser available, it will be opened on the verification page for you automatically. To disable this and only print the URL and code, add `--launch-browser=false`:
+
+```bash
+faas-cli pro auth \
+  --grant device_code \
+  --client-id CLIENT_ID \
+  --authority https://oidc.example.com \
+  --gateway https://gateway.example.com \
+  --launch-browser=false
+```
+
+!!! note "Your IdP must support the device authorization flow"
+
+    The device authorization flow can only be used when your Identity Provider supports it. See the [SSO overview](/openfaas-pro/sso/overview/) for the supported providers and flows. If your provider does not support it, use the OAuth code flow described below instead.
+
+#### Authorization code flow with PKCE
+
+With the authorization code flow with Proof Key for Code Exchange (PKCE), the CLI opens a browser to sign in and starts a local server to receive the token on the callback URL `http://127.0.0.1:31111/oauth/callback`. This URL needs to be registered as a valid redirect URI on your IdP client.
 
 ```bash
 faas-cli pro auth \
@@ -21,15 +61,11 @@ faas-cli pro auth \
  --gateway https://gateway.example.com
 ```
 
-A browser will open and you can log in using your IDP.
-
-Following on from that, a JWT will be exchanged for an OpenFaaS access token, and the CLI will be ready to use.
-
-Whenever you want to log in again, you can use the `faas-cli pro auth` command, and you will not need to add the `--client-id` flag or `--authority` flag again, since they will be saved for you.
+After receiving the token from your IdP, the CLI exchanges it for an OpenFaaS access token and is ready to use.
 
 ### Log in to refresh your SSO token
 
-If you have already logged in, then you can refresh your token using the `faas-cli pro auth` command:
+If you have already logged in, then you can refresh your token using the `faas-cli pro auth` command.  Your settings are saved after the first login, so you will not need to provide all of the flags again.
 
 ```bash
 faas-cli pro auth \

docs/openfaas-pro/sso/google.md

@@ -12,16 +12,28 @@ This guide will cover how to configure Google as an identity provider for OpenFa
 
 3. Obtain OAuth 2.0 credentials
 
-    You will need to obtain a client ID and client secret for OpenFaaS. Create new OAuth Client ID credentials under *APIs & Services -> Credential*.
+    There are two possible client credentials setups:
+
+    - A single *Web application* client shared by both the dashboard and the CLI, using the [Implicit Id flow](#implicit-id-flow) for the CLI.
+    - One *Web application* client for the dashboard and a separate *TVs and Limited Input devices* client for the [Device Authorization flow](#device-authorization-flow) with the CLI.
+
+    Create new OAuth Client ID credentials under *APIs & Services -> Credential* for each application type you need.
 
     ![Google API console OAuth 2.0 credentials](/images/oidc-configuration/google/google-create-credentials.png)
 
-4. Add the callback URL for the CLI and dashboard to the list of valid redirect URIs.
+    When creating the credentials you are asked to select an application type:
 
-    Add `http://127.0.0.1:31111/oauth/callback` for the CLI. If you are deploying the OpenFaaS dashboard, add the redirect URI for your dashboard e.g `https://dashboard.openfaas.example.com/auth/callback`.
+    ![Google API console select application type](/images/oidc-configuration/google/google-application-type.png)
 
-    ![Google API console add redirect URIs](/images/oidc-configuration/google/google-redirect-uris.png)
+    Each client has its own client ID and secret. All client IDs will need to be added to the `aud` field of the JwtIssuer in step 5.
+
+4. Add the callback URLs to the list of valid redirect URIs on the **Web application** client.
 
+    - For the dashboard, add the redirect URI for your dashboard e.g `https://dashboard.openfaas.example.com/auth/callback`.
+    - For the CLI, add `http://127.0.0.1:31111/oauth/callback` if you intend to use the [Implicit Id flow](#implicit-id-flow).
+
+    ![Google API console add redirect URIs](/images/oidc-configuration/google/google-redirect-uris.png)
+
 5. Register Google as a JwtIssuer with OpenFaaS
 
     Create a JwtIssuer object in the `openfaas` namespace to register Google as a trusted issuer for OpenFaaS IAM.
@@ -37,26 +49,49 @@ This guide will cover how to configure Google as an identity provider for OpenFa
     spec:
       iss: https://accounts.google.com
       aud:
+        # Dashboard - client id of the Web application credentials
         - 156723843784956-dkebg39ro687we10ad39756kflrtpzsan.apps.googleusercontent.com
+        # CLI - client id of the TVs and Limited Input devices credentials (Device Authorization flow)
+        - 156723843784956-zsan39ro687we10ad39756kflrtpzdkebg.apps.googleusercontent.com
     tokenExpiry: 12h
     ```
 
     The `iss` field needs to have the value `https://accounts.google.com`.
 
-    The `aud` field contains a set of accepted audiences. For Google this is the client id that was generated in step 3.
-    The client ID and secret can always be accessed from *Credentials* in *APIs & Services* in the [Google API console](https://console.cloud.google.com/projectselector2/apis/credentials?supportedpurview=project).
+    The `aud` field contains a set of accepted audiences. For Google these are the client ids of the credentials that were created in step 3. Add the client id of the **Web application** credentials and, if you are using the CLI Device Authorization flow, the client id of the **TVs and Limited Input devices** credentials.
+
+    The client IDs and secrets can always be accessed from *Credentials* in *APIs & Services* in the [Google API console](https://console.cloud.google.com/projectselector2/apis/credentials?supportedpurview=project).
 
     The `tokenExpiry` field can be used to set the expiry time of the OpenFaaS access token.
 
 
-!!! note "SSO with the faas-cli"
+## Login with the faas-cli
+
+Google does not support the Authorization Code flow with Proof Key for Code Exchange (PKCE), so to login with the faas-cli you can use either the Device Authorization flow or the Implicit Id flow.
+
+See [SSO with the faas-cli](/openfaas-pro/sso/cli/) for how to install the CLI and a full reference of the available login flags and flows.
+
+### Device Authorization flow
+
+Use this flow if you opted for a separate client for the CLI. It uses the dedicated *TVs and Limited Input devices* client created in [step 3](#configure-google) and requires the client id and client secret.
+
+```sh
+faas-cli pro auth \
+  --grant device_code \
+  --authority https://accounts.google.com \
+  --client-id CLIENT_ID \
+  --client-secret CLIENT_SECRET
+```
+
+### Implicit Id flow
+
+Use this flow if you opted for a single client shared by the dashboard and the CLI. It uses the *Web application* client created in [step 3](#configure-google).
 
-    Google does not support the Authorization Code flow with Proof Key of Code Exchange (PKCE).
-    To login with the faas-cli use the Implicit Id flow. 
+The CLI opens a browser to sign in and starts a local server to receive the token on the callback URL `http://127.0.0.1:31111/oauth/callback`. This URL needs to be added to the list of valid redirect URIs on this client (see [step 4](#configure-google)).
 
-    ```sh
-    faas-cli pro auth \
-      --grant implicit-id \
-      --authority https://accounts.google.com \
-      --client-id CLIENT_ID
-    ```
+```sh
+faas-cli pro auth \
+  --grant implicit-id \
+  --authority https://accounts.google.com \
+  --client-id CLIENT_ID
+```

docs/openfaas-pro/sso/keycloak.md

@@ -6,14 +6,20 @@ This guide will cover how to configure [Keycloak](https://www.keycloak.org/) as
 
     ![Keycloak client general settings](/images/oidc-configuration/keycloak/keycloak-general-settings.png)
 
-2. Enable the **Standard Flow** (Authorization Code Flow) for the client.
+2. Configure the authentication flows for the client.
+
+    Enable the **Standard Flow** (Authorization Code Flow) for the client.
 
     ![Keycloak client authentication flow settings](/images/oidc-configuration/keycloak/keycloak-auth-flow.png)
 
+    To allow logging in with the CLI using the Device Authorization flow, also enable the **OAuth 2.0 Device Authorization Grant** option.
+
 3. Add the callback URLs for the CLI and dashboard to the list of valid redirect URIs.
 
     Add `http://127.0.0.1:31111/oauth/callback` for the CLI. If you are deploying the OpenFaaS dashboard, add the redirect URI for your dashboard e.g `https://dashboard.openfaas.example.com/auth/callback`.
 
+    The CLI callback URL is not required if you only intend to use the Device Authorization flow for the CLI.
+
     ![Keycloak client allowed redirect url settings](/images/oidc-configuration/keycloak/keycloak-callback.png)
 
 4. Register your Keycloak provider with OpenFaaS
@@ -42,3 +48,34 @@ This guide will cover how to configure [Keycloak](https://www.keycloak.org/) as
 
     The `tokenExpiry` field can be used to set the expiry time of the OpenFaaS access token.
 
+## Login with the faas-cli
+
+To login with the faas-cli you can use either the Device Authorization flow or the Authorization Code flow.
+
+See [SSO with the faas-cli](/openfaas-pro/sso/cli/) for how to install the CLI and a full reference of the available login flags and flows.
+
+### Device Authorization flow
+
+Use this flow to log in from a remote or headless machine where no local browser is available. It requires the **OAuth 2.0 Device Authorization Grant** option to be enabled on the client.
+
+```sh
+faas-cli pro auth \
+  --grant device_code \
+  --authority https://keycloak.example.com/realms/openfaas \
+  --client-id CLIENT_ID
+```
+
+The CLI prints a verification URL and a one-time code. Open the URL in a browser on any device, enter the code and complete the login with Keycloak.
+
+### Authorization Code flow
+
+This flow is an alternative to the Device Authorization flow. It requires the **Standard Flow** to be enabled on the client (see [step 2](#configure-keycloak)).
+
+The CLI opens a browser to sign in and starts a local server to receive the token on the callback URL `http://127.0.0.1:31111/oauth/callback`, so this URL needs to be added to the list of valid redirect URIs on the client (see [step 3](#configure-keycloak)).
+
+```sh
+faas-cli pro auth \
+  --authority https://keycloak.example.com/realms/openfaas \
+  --client-id CLIENT_ID
+```
+

docs/openfaas-pro/sso/overview.md

@@ -15,22 +15,23 @@ To configure your identity provider:
 
     Authentication flows supported by the OpenFaaS CLI:
 
-    - Authorization Code flow with Proof Key of Code Exchange (PKCE) - (recommended)
+    - Authorization Code flow with Proof Key for Code Exchange (PKCE) - (recommended)
+    - Device Authorization Grant
     - Implicit flow
     - Client Credentials flow
 
     Authentication flows supported by the OpenFaaS dashboard:
 
     - Authorization Code Flow
-    - Authorization Code Flow with Proof Key of Code Exchange (PKCE)
+    - Authorization Code Flow with Proof Key for Code Exchange (PKCE)
 
-    For the CLI we recommend the Authorization Code flow with PKCE. One of the other flows can be used if your provider does not support PKCE.
+    For the CLI we recommend the Authorization Code flow with PKCE or the Device Authorization Grant if your provider supports it. One of the other flows can be used if your provider does not support PKCE.
 
 3. Configure allowed callback URLs.
 
     The dashboard uses the callback path: `/auth/callback`. If you are deploying the dashboard allow callbacks on your dashboards public URL, e.g. `https://dashboard.openfaas.example.com/auth/callback`
 
-    For the CLI the default callback URL is, `http://127.0.0.1:31111/oauth/callback`
+    For the CLI the default callback URL is, `http://127.0.0.1:31111/oauth/callback`. The CLI callback URL is not required when using the Device Authorization flow.
 
 4. Register your provider with OpenFaaS