Configuring the Diffusion management console

Single sign-on

The Diffusion management console can optionally be integrated with a single-sign on system. This is disabled by default.

Authentication is accomplished by obtaining an opaque token from a cookie that is passed to a custom authenticator. JWT tokens are useful in this scenario, but any binary data can be used.

Architecture of Diffusion management console single sign-on workflow.

Note: In order use to this feature securely, the Diffusion server must be configured with an authentication handler which performs authentication with single-use tokens.

Writing console authentication portals

The console authentication portal is responsible for authenticating the user with an external authentication provider. This is usually performed with SAML, OAuth or OpenID connect.

If the user successfully authenticates, the console authentication portal must set a cookie on a domain such that it will be provided to the console by the user's browser. This may be accomplished by setting a cookie on a shared parent domain of the authentication portal and the console, or by using reverse proxies to present the authentication portal on the same domain as the console. The console authentication has total control of how the cookie is configured, but the name must match the value of the SSO_COOKIE field in html/console/config.js.

Once a cookie has been set, the console authentication portal must redirect the user's browser back to the Diffusion management console, with the query parameter sso-login present.

Note: In the interests of security, the following cookie attributes are recommended:

MaxAge of 60 seconds, or as short as reasonably possible.
The Secure attribute set, with the console available over HTTPS.
Some browsers may log warnings if SameSite is not specified.

Writing custom authentication handlers for console authentication

A custom authentication handler must be configured in the Diffusion server . The console will send login requests to Diffusion with the principal Diffusion Management Console SSO and custom credentials containing the value stored in the cookie.

The authentication handler is then responsible for authenticating the session as usual, including setting the session principal and roles as appropriate. For more information, see Authenticating new sessions.