src/openid-auth.md.j2

{# vim: set filetype=markdown.jinja : #}
{%- import 'include/ext-macros.md.j2' as ext with context -%}

OpenID Connect Authentication
=============================

[OpenID Connect](http://openid.net/connect/) is a widely-adopted open standard
for implementing single sign-on (SSO). [Not to be confused with
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
flow](https://openid.net/specs/openid-connect-core-1_0.html#ImplicitFlowAuth)"
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.

(openid-downloading)=

Downloading and installing the OpenID Connect authentication extension
----------------------------------------------------------------------

{{ ext.install('OPENID', 'guacamole-auth-sso', 'openid/guacamole-auth-sso-openid') }}

(guac-openid-config)=

Configuring Guacamole for single sign-on with OpenID Connect
------------------------------------------------------------

{% call ext.config('openid', required=True) %}
Guacamole's OpenID connect support requires several {{ ext.properties() }}
which describe both the identity provider and the Guacamole deployment. These
{{ ext.properties() }} are *absolutely required in all cases*, as they dictate
how Guacamole should connect to the identity provider, how it should verify the
identity provider's response, and how the identity provider should redirect
users back to Guacamole once their identity has been confirmed:
{% endcall %}

### Additional Configuration Options

{% call ext.config('openid-optional') %}
Additional optional {{ ext.properties() }} are available to control how claims
within received ID tokens are used to derive the user's Guacamole username, any
associated groups, the OpenID scopes requested when user identities are
confirmed, and to control the maximum amount of time allowed for various
aspects of the conversation with the identity provider:
{% endcall %}

(openid-login)=

### Controlling login behavior

```{include} include/sso-login-behavior.md
```

#### Automatically redirecting all unauthenticated users

To ensure users are redirected to the OpenID identity provider immediately
(without a Guacamole login screen), ensure the OpenID extension has priority
over all others:

```
extension-priority: openid
```

#### Presenting unauthenticated users with a login screen

To ensure users are given a normal Guacamole login screen and have the option
to log in with traditional credentials _or_ with OpenID, ensure the OpenID
extension does not have priority:

```
extension-priority: *, openid
```

(completing-openid-install)=

### Completing the installation

```{include} include/ext-completing.md
```