Quick start tutorial
Introduction
This tutorial consists of two parts:
Part 1 guides you through the steps required to create a customised login page for your organisation that your application can use to authenticate users.
Part 2 explains how to to integrate your application with Keycloak, the Haventec Identity Access Manager (IAM).
Part 1: Create a customised login page
This part of the tutorial consists of three steps:
- Step 1: Set up your organisation in Haventec Console
- Step 2: Create your customised login page
- Step 3: View your login page
Step 1: Set up your organisation in Haventec Console
Note: The Haventec Console Demo environment is only available for testing products and integrations; it is not designed for a production environment. If you would like to run your application in production, contact Haventec Support.
Go to Haventec Console Demo. The Sign up an organisation page is displayed.
Use this page to sign up your organisation to use Haventec authentication services and create an admin user for your organisation.
Example: Creating an organisation named Demo org and a user named hvdemo1234.
Enter the name of your organisation, the username of the administrator for your organisation, and the administrator's email address.
Select I'm not a robot and complete the CAPTCHA test if required.
Click Sign up.
An activation code is sent to the email address provided. An example is shown below.
Subject: Haventec Console - Activate your Organisation
Hi hvdemo1234,
Thank you for creating your organisation Demo org.
To activate your organisation please enter this activation code
510753
This activation token will expire in 24 hours.
Kind regards,
Haventec Team
The Activate Organisation page is displayed.
Enter the activation code provided in the email, enter and confirm your four-digit PIN, and then click Activate.
Haventec Console is displayed.
The console has several panes. There is a menu at the top, a menu at the left-hand side of the console, and a main content pane.
Top menu
Click Help Center to go to Haventec Support Center.
Note: You need to be a registered Haventec Zendesk user and logged into the support center to be able to access all available articles at the support center. If you are not logged into the support center, some articles or options may not be available to you. Click Sign in at the top-right of the support center to either sign in or view instructions on how to sign up as a verified user.
The organisation and user created earlier in this tutorial are displayed.
Click the username to show further information about the user, manage the user account, and log out the user.
Left-hand menu
Main pane
Step 2: Create your customised login page
The next step is to add an application in which you want to use Haventec authentication services to authenticate your users.
Click Add an application. The following page is displayed.
Enter your application name and description.
Tip: Use the navigation icons to go to the next page and previous page.
Next page
Previous page
Click Next page. The following page is displayed.
Select Enable Authenticate. (Sanctum is not required.)
For Authentication Protocol, select OpenID Connect JWT.
Click Next page. The following page is displayed.
For Logo, click Choose File and select the logo to display on your application login page (must be a png file less than 1 MB).
For Background Image, click Choose File and select the background image of your application login page (must be a jpg file less than 1 MB).
Example
Click Next page. The following page is displayed.
For Do you have your own IAM, or would you like to use Haventec?, select I’d like to use Haventec IAM.
For How do you want your users to sign up?, select Self-service.
Click Next page. The following page is displayed.
For How many verification steps are needed in order to register users?, select 1 Step.
For Configure step options, select EMAIL.
Click Save application. The application setup is saved and the following message is displayed.
Step 3: View your login page
Now for the big unveiling!
Select the Applications page. In the Name column, click the name of the application you have just created.
The Authenticate details page is displayed for the selected application.
Click Protocol Settings.
Copy the URL to the right of App Login Page and paste it in your browser.
Your application login page is displayed.
Congratulations! You have set up a login page to authenticate your users.
Part 2: Keycloak IAM OpenID Connect (OIDC) integration
This part explains how to configure Keycloak IAM and integrate it with the application you created in Part 1.
This part of the tutorial consists of four steps:
- Step 1: Sign in to Haventec Identity Access Manager
- Step 2: Create an OIDC identity provider to connect to your application login page
- Step 3: Create a Keycloak client
- Step 4: Test your configuration
Before commencing this part of the setup, contact Haventec Support to create a Keycloak IAM account for you to test with. Fill out the contact form and we will send you an email with your IAM details.
Subject: Haventec Keycloak Identity Access Manager (IAM) sign in details
Hi hvdemo1234,
Thank you for contacting Haventec Support.
As requested, we have created a Haventec Keycloak IAM account for you.
Please sign in to Haventec IAM using the following details:
Username or email: <email address>
Password: <password>
Click the link below to display the Haventec IAM sign in page:
<link>
Enter the email address and password shown above, and then click Sign In.
Kind regards,
Haventec Team
After receiving your sign in details, continue with the following steps.
Note: Keycloak login requires two-step verification. To enable this you will need to install and set up an authentication app such as Google Authenticator on your mobile device. If your Keycloak access times out, you will be prompted to enter a one-time verification code to sign back into Keycloak. Go to your authentication app. A rolling one-time code is displayed. Enter that code in One-time code below and then click Sign In.
Step 1: Sign in to Haventec Identity Access Manager
Click the link sent by Haventec. The Haventec Keycloak Sign in page is displayed.
Enter the email address and password provided in the email from Haventec.
Click Sign In. Your Realm configuration page is displayed.
Step 2: Create an OIDC identity provider to connect to your application login page
Click Identity Providers in the left-hand menu.
For Identity Provider, select OpenID Connect v1.0.
The Add an identity provider page is displayed.
For Alias, leave the default value of oidc.
For Client Authentication, select Client secret sent as post.
Complete the other mandatory fields using the following values from the Protocol Settings section of the application you created in Haventec Console. Copy and paste these values as explained below:
Tip: Use the copy icon 
to copy the values.
- Copy the value of Client Secret from the Console and paste it into Client Secret in Keycloak.
- Copy the value of Authorization endpoint from the Console and paste it into Authorisation URL in Keycloak.
- Copy the value of Client ID from the Console and paste it into Client ID in Keycloak.
- Copy the value of Token endpoint from the Console and paste it into Token URL in Keycloak.
Click Save.
Note: Once set up, your identity provider will show on the Keycloak sign in page. You can then either sign in using your email address and password or by clicking your identity provider, oidc.
Step 3: Create a Keycloak client
In this step you will create a Keycloak client to communicate with using the OpenID Connect protocol and create a link to test the setup so you won't need to update your application just yet.
The client enables requests to be sent to Keycloak to start the authentication flow, in this case using the OpenID Connect protocol.
Click Clients in the left-hand menu. The Clients page is displayed.
Click Create. The Add Client page is displayed.
For Client ID, enter my-client.
Click Save. The client list is displayed.
Click my-client. The Settings page for my-client is displayed.
Upon a successful authentication, users will be forwarded to the desired page. You will need to white-list that redirect URI. In this tutorial users are being redirected to a publicly-available mock page:
Scroll down to Valid Redirect URIs and, in that field, enter http://mockbin.org/*.
Click Save.
Step 4: Test your configuration
You can now test your application.
Your application can use any OpenID Connect client SDK, for instance AppAuth, but for now let's test it with a crafted link that upon a successful authentication will go to a mock dashboard page: http://mockbin.org/request.
The following link emulates the call that your application would do to Haventec Keycloak to start the authentication flow.
https://iam.demo.haventec.com/auth/realms/my-realm/protocol/openid-connect/auth?client_id=my-client&redirect_uri=http://mockbin.org/request&response_mode=fragment&response_type=code&scope=openid
Replace my_realm with the name of your realm. Your realm name is shown in Haventec IAM Realm Settings.
my_client is the name of the client you created in step 3.
Copy your link and paste it into your browser. The http://mockbin.org/request page is displayed.
Congratulations! You have integrated Keycloak IAM with your customised login page. You now need to configure an application to start using it.
Comments
0 comments
Please sign in to leave a comment.