Hugo Theme Stack - SSO Authentication
OpenID SSO Authentication Documentation
This documentation provides a guide on how to use the OpenID Single Sign-On (SSO) authentication feature in a Hugo page which uses hugo-theme-stack
as main theme. The OpenID class provides methods to initialize and interact with the OpenID authentication system.
Usage
To enable SSO authentication with OpenID in your Hugo project, follow the steps below:
-
Create a JavaScript file in your project's assets folder. This file will contain the OpenID class and its associated methods. You can choose any name for the file, but for this example, let's assume you name it
auth.js
. -
Add the following configuration to your config.yaml file to enable SSO authentication:
params: # SSO Authentication ssoAuthentication: enabled: true scriptPath: 'js/auth.js'
Set the
enabled
parameter totrue
to enable SSO authentication, and provide the correct path to the JavaScript file you created in the scriptPath parameter. In this example, we assume the file is located in the js folder within the assets folder.
OpenID class
The file is located in static/js/sso/openid.js
of the hugo-theme-stack
-
Constructor Arguments:
-
url
(string, optional): The URL of the OpenID authentication server. The default value ishttps://accounts.rtworkspace.com/auth/
. -
realm
(string, optional): The realm or domain name associated with the OpenID authentication server. The default value isrta
. -
clientId
(string, required): The client ID associated with your application. This ID is required for OpenID initialization.
-
-
Methods:
-
getClient()
: This method returns the Keycloak client instance associated with the OpenID class. -
init(options)
: This method initializes the OpenID authentication system with the provided options. It takes an options object as the argument, which can contain the following properties:-
onLoad
(string, optional): The behavior to perform on page load. The default value ischeck-sso
. Possible values include-
login-required
: authenticates the client if the user is logged in to Keycloak or displays the login page if the user is not logged in. -
check-sso
only authenticates the client if the user is already logged in. If the user is not logged in, the browser is redirected back to the application and remains unauthenticated.
-
-
silentPath
(string, optional): The path to the silent check SSO endpoint. The default value is/sso/check
. -
authenticatedCallback
(function, optional): A callback function to be executed when the user is authenticated. -
unauthenticatedCallback
(function, optional): A callback function to be executed when the user is unauthenticated. -
errorCallback
(function, optional): A callback function to handle errors during initialization.
-
-
Example Usage
See the assets/js/auth.js
file below.
Note
Please note that the provided code snippet is already written to cover various cases that may occur in SSO Authentication. You can copy it and override the necessary parts as per your specific requirements.