Developing a dash button web component based on the Stencil.js framework ensures consistent support across all modern frontend frameworks with minimal configurations. Therefore, by incorporating Keycloak-based authentication with SSO features, minimal configuration is needed to secure any frontend application.
To install the dash-button web component, copy and paste it into your frontend application.
<script type='module' src='https://unpkg.com/dash-button-web@0.0.18/dist/esm/web-compnont.js'></script>You can find the NPM package named dash-button-web.
If it is a framework, you wll need to configure more options. Therefore, follow the Stencil.js documentation.
First, you need to install the latest Keycloak server, or you can use an existing one.
First, you need to start the Keycloak server. You can simply initiate the Docker image of the Keycloak server using the command below:
docker run -p 8080:8080 -e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=admin quay.io/keycloak/keycloak:23.0.4 start-devIf you need additional installation guidelines, please refer to the Keycloak documentation.
Next, log in to the Keycloak admin panel and create a realm using a chosen name. For example, here I have created a realm named 'demo'.
Next, create a client and configure URLs. For development purposes, set valid redirect URLs and set web origins as '*' as follows.
Next, create a user with credentials for testing purposes.
Here, we are demonstrating how to configure the application on an Angular-based application and a basic HTML-based application. If you need to install React or Vue.js, follow the Stencil.js documentation.
First, you need to enable the custom component support feature in the Angular project. To do that, the following code block needs to be added to the src/app/app.module.ts file.
@NgModule({
…
schemas: [
CUSTOM_ELEMENTS_SCHEMA
],
})Once the above addition is completed, it is required to import the below module as follows.
import { CUSTOM_ELEMENTS_SCHEMA} from '@angular/core';Next, you need to put the script file path in the src/index.html file header section as follows.
<script type='module' src='https://unpkg.com/dash-button-web@0.0.18/dist/esm/web-compnont.js'></script>Note: Starting from v0.0.16, you need to add the FontAwesome stylesheet file to your application. If your application is already using this package, you can ignore this.
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.7.2/css/all.min.css" />
Therefore, the header section of your index file should look like this:
<head>
<meta name="viewport" content="width=device-width, initial-scale=1">
<link rel="icon" type="image/x-icon" href="favicon.ico">
<script type='module' src='https://unpkg.com/dash-button-web@0.0.18/dist/esm/web-compnont.js'></script>
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.7.2/css/all.min.css" />
...After that, you can pass configuration options as follows using the web component.
| Attribute | Description | Type | Default |
|---|---|---|---|
client-id |
Keycloak client ID |
string |
`` |
keycloak-uri |
Keycloak server URI |
string |
"http://localhost:8080" |
realm |
Keycloak realm |
string |
`` |
redirect-uri |
Application redirect URI |
string |
`` |
show-post-login-text |
Successfully logged in shows a custom button message |
boolean |
false |
auth-method |
Authentication method |
string |
check-sso, (login-required)
|
app-id |
Application unique ID |
string |
`` |
portal-url |
Portal URL |
string |
`` |
portal-api-url |
Portal API URL |
string |
`` |
show-unauthorized-modal |
Show unauthorized modal |
boolean |
false |
other-link-type |
Add new links for the menu |
string |
local or global |
application-display-name |
Menu application display name |
string |
Applications |
disable-application-tab |
disable application tab |
boolean |
false |
menu-view-type |
the style of the menu |
string |
grid/list |
| Attribute | Description | Type | Default |
|---|---|---|---|
primary-color |
Set primary colour |
string |
`` |
accent-color |
Set secondary or accent color |
string |
`` |
AuthMethod Using the auth-method attribute updates the application's authentication workflow.
login-required: User is forced to the login screen if they are not logged in.
check-sso: User is not forced to the login screen; instead, when the user clicks the login button, they are redirected to the login screen.
Now, you are almost done. In the final stage, you can place the web-component button tag at the top of the navigation bar using the following code block.
<dash-button keycloak-uri="http://localhost:8080" realm="demo" client-id="testapp" auth-method="login-required" show-post-login-text="false"></dash-button>After that test your application can be test with user credentials and then you can get an output similar to this.
You need to follow similar procedures as above.
First, you need to import the script tag into the header section of your main HTML file as follows.
<head>
<meta name="viewport" content="width=device-width, initial-scale=1">
<link rel="icon" type="image/x-icon" href="favicon.ico">
...
<script type='module' src='https://unpkg.com/dash-button-web@0.0.18/dist/esm/web-compnont.js'></script>
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.7.2/css/all.min.css"
...After that, all you need to do is place the dash button in your preferred location on the web page. To do so, use the following web component button tag and place it in your application with preferred configuration options.
<dash-button keycloak-uri="http://localhost:8080" realm="demo" client-id="testapp"></dash-button>That's it, enjoy!
v0.0.18
- Bug fixed and improved documentation.
v0.0.17
- Added a new environment variable option for the Config Portal API endpoint.
v0.0.16
- Added customization option to change the main menu view type.
- Added a new option to retrieve the main menu list and display it from the portal API.
- Replaced all icons with FontAwesome. (Any third-party application now needs to import FontAwesome.)
v0.0.15
- Added configuration option to customize the application name in the menu.
- Introduced feature to disable the application tab.
- Display user profile photo in the dashboard button.
- Removed hardcoded menu links from the dashboard button; now retrieves the menu link list dynamically from the backend service.