GUACAMOLE-2261: Add documentation for openid extensions code flow, client secret, ...

src/include/openid-optional.properties.in

@@ -1,3 +1,93 @@
+#
+# The OpenID response type, defining if *Implicit Flow* or *Code Flow* will be
+# used. The valid values are limited to the following:
+#
+# **id_token**: Use standard OpenID Connect *Implict Flow*
+#
+# **token**: Certain Identity Providers use the response type {samp}`token`,
+# notably *AWS Cognito*, to define *Implicit Flow* returning both the
+# id token and access token. This option allows these Identity Providers to
+# be used despite their non compliant behaviour.
+#
+# **code**: Use standard OpenID Connect *Code Flow*
+#
+# By default, to allow existing Guacamole OpenID configurations to work
+# without change, the response type is assumed to be {samp}`id-token`
+openid-response-type: id_token
+
+#
+# The authorization endpoint (URI) of the OpenID service.
+#
+# This value should be provided to you by the identity provider. For identity
+# providers that implement [OpenID Connect Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html),
+# it is better to use the `openid-well-known-endpoint` parameter instead. This
+# value however can replace or override the values returned by the well-known
+# endpoint.
+#
+openid-authorization-endpoint: https://identity-provider/auth
+
+#
+# The endpoint (URI) of the JWKS service which defines how received ID tokens
+# ([JSON Web Tokens](https://jwt.io/) or JWTs) shall be validated.
+#
+# This value should be provided to you by the identity provider. For
+# identity providers that implement [OpenID Connect
+# Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html),
+# it is better to use the `openid-well-known-endpoint` parameter instead. This
+# value however can replace or override the values returned by the well-known
+# endpoint.
+#
+openid-jwks-endpoint: https://identity-provider/jwks
+
+#
+# The endpoint (URI) of the token service which defines how received codes
+# are excahanged for ID tokens.
+#
+# This value should be provided to you by the identity provider. For
+# identity providers that implement [OpenID Connect
+# Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html),
+# it is better to use the `openid-well-known-endpoint` parameter instead. This
+# value however can replace or override the values returned by the well-known
+# endpoint.
+#
+# It is only used if the response type is `code`.
+#
+openid-token-endpoint: https://identity-provider/token
+
+#
+# The issuer to expect for all received ID tokens.
+#
+# This value should be provided to you by the identity provider. For
+# identity providers that implement [OpenID Connect
+# Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html),
+# it is better to use the `openid-well-known-endpoint` parameter instead. This
+# value however can replace or override the values returned by the well-known
+# endpoint.
+#
+openid-issuer: identity-provider
+
+#
+# Boolean value for whether Proof Key for Code Exchange (PKCE) should be used.
+#
+# PKCE is only available if you are using a *Code Flow* response type. This
+# option allows the use of a random 256-bit challenge and verifier in the
+# requests to the Ientity Provider, ensuring that the request for the code
+# and the exchange of the code for the id token have the same origin.
+#
+openid-pkce-required: false
+
+#
+# The OpenID client secret which should be submitted to the OpenID service
+# when necessary. This value is typically provided to you by the OpenID
+# service when OpenID credentials are generated for your application.
+#
+# This value is only used for [Confidential
+# Clients](https://datatracker.ietf.org/doc/html/rfc6749#section-2.1) as
+# defined by the Oauth 2.0 standard, and only if using *Code Flow*
+# authentication.
+#
+opendid-client-secret: secret
+
 #
 # The claim type within any valid JWT that contains the authenticated user's
 # username. By default, the "`email`" claim type is used.
@@ -48,8 +138,21 @@ openid-max-token-validity: 300
 # OpenID request can result in successful authentication within Guacamole. By
 # default, each generated nonce expires after 10 minutes.
 #
+# This value is only used with *Implicit Flow*.
+#
 openid-max-nonce-validity: 10
 
+#
+# The maximum amount of time that a PKCE verifier generated by the Guacamole
+# server should remain valid, in minutes. As each OpenID request has a
+# requiring PKCE has a unique verifier, this imposes an upper limit on the amount
+# of time any particular OpenID request can result in successful authentication
+# within Guacamole. By default, each generated PKCE verifier expires after 10
+# minutes.
+#
+# This value is only used with *Code Flow* with *PKCE* enabled.
+openid-max-pkce-verifier-validity: 10
+
 #
 # The logout endpoint (URI) of the OpenID Connect identity provider. When
 # configured, users will be redirected to this endpoint when they log out from

src/include/openid.properties.in

@@ -1,40 +1,21 @@
 #
-# The authorization endpoint (URI) of the OpenID service.
-#
-# This value should be provided to you by the identity provider. For identity
-# providers that implement [OpenID Connect Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html),
-# this value can be retrieved from the `authorization_endpoint` property of the
-# JSON file hosted at {samp}`{https://identity-provider}/.well-known/openid-configuration`, where
-# `https://identity-provider` is the base URL of the identity provider.
-#
-openid-authorization-endpoint: https://identity-provider/auth
-
-#
-# The endpoint (URI) of the JWKS service which defines how received ID tokens
-# ([JSON Web Tokens](https://jwt.io/) or JWTs) shall be validated.
-#
-# This value should be provided to you by the identity provider. For
-# identity providers that implement [OpenID Connect
-# Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html),
-# this value can be retrieved from the `jwks_uri` property of the JSON
-# file hosted at
-# {samp}`{https://identity-provider}/.well-known/openid-configuration`, where
-# `https://identity-provider` is the base URL of the identity provider.
-#
-openid-jwks-endpoint: https://identity-provider/jwks
-
-#
-# The issuer to expect for all received ID tokens.
-#
-# This value should be provided to you by the identity provider. For
-# identity providers that implement [OpenID Connect
-# Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html),
-# this value can be retrieved from the `issuer` property of the JSON
-# file hosted at
-# {samp}`{https://identity-provider}/.well-known/openid-configuration`, where
-# `https://identity-provider` is the base URL of the identity provider.
-#
-openid-issuer: identity-provider
+# The OpenID Connect Discovery endpoint
+#
+# For identity providers that implement [OpenID Connect
+# Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html), this
+# endpoint can be used to automatically discover the other needed configuration
+# parameters, including {samp}`openid-issuer`, {samp}`openid-token-endpoint`
+# {samp}`openid-authorization-endpoint` and {samp}`openid-jwks-endpoint`.
+# This parameter is not strictly required, but if absent must be replaced with
+# these four parameters.
+#
+# Please note that an outgoing http connection from Guacamole is used in the
+# discovery, and as with all network connections it might fail. This extension
+# will make several attempts during the two minutes after startup to discover
+# the configuration. Please check your logs if an error occurs during login
+# attempts.
+#
+openid-well-known-endpoint: https://identity-provider/.well-known/openid-configuration
 
 #
 # The OpenID client ID which should be submitted to the OpenID service when

src/openid-auth.md.j2

@@ -10,15 +10,22 @@ OAuth](https://oauth.net/articles/authentication/), which is *not* an
 authentication protocol, OpenID Connect defines an authentication protocol in
 the form of a simple identity layer on top of OAuth 2.0.
 
-Guacamole's OpenID Connect support implements the "[implicit
+Guacamole's OpenID Connect supports both "[implicit
 flow](https://openid.net/specs/openid-connect-core-1_0.html#ImplicitFlowAuth)"
+and [code
+flow](https://openid.net/specs/openid-connect-core-1_0.html#CodeFlowAuth)"
 of the OpenID Connect standard, and allows authentication of Guacamole users to
 be delegated to an identity provider which implements OpenID Connect, removing
 the need for users to log into Guacamole directly. This module must be layered
 on top of other authentication extensions that provide connection information,
 such as the [database authentication extension](jdbc-auth), as it only provides
 user authentication.
 
+[OAuth 2.0 Implicit Grants](https://oauth.net/2/grant-types/implicit/) are
+considered to be deprecated due to the inherent risks of returning access
+tokens in an HTTP redirect without confirmation that it has been received by
+the client.
+
 ```{include} include/warn-config-changes.md
 ```
 

src/vault.md.j2

@@ -112,7 +112,7 @@ Required configuration
 
 {% call ext.config('ksm', required=True) %}
 Guacamole requires only a single configuration property to configure secret
-retrieval from KSM, `ksm-config`, which must be provided the base64
+retrieval from a Vault, `vault-config`, which must be provided the base64
 configuration value retrieved from KSM using the one-time token [obtained when
 Guacamole was registered with KSM as an application as described above](adding-guac-to-ksm).
 All other {{ ext.properties() }} are optional.