We're excited today to announce the launch of our dedicated clusters offering. Our Phase Two enhanced Keycloak distribution is now available as a hosted, dedicated cluster in the region of your choice.

About 9 months ago, we launched our self-service, shared deployments, offering customers the ability to create Phase Two enhanced Keycloak realms on our shared clusters. Over that period, we've provided over 700 free realms for testing and small production use cases. Many of you have reached out to us asking about an SLA, isolated resources, and ability to grow into larger use cases. Based on your requests and feedback, we built out our dedicated cluster offering.

What is Phase Two again?​

Phase Two helps SaaS builders accelerate time-to-market and enterprise adoption with powerful SSO, identity and user management features. To that end, Phase Two has created an enhanced distribution of Keycloak that bundles several essential open source extensions for modern SaaS use cases. We support hosted and on-prem customers for a variety of use cases.

Why dedicated?​

Dedicated clusters allow us to provide compute, network and storage isolation for customer workloads, and to easily deploy in the region where customer's users are. With dedicated clusters, we can guarantee an SLA that meets customer's needs with no resource contention from other customers.

Furthermore, it allows us to support customer-provided domain names, and access to monitoring and management capabilities not available in the shared clusters.

How did you do it?​

We built out our dedicated cluster offering using the best-of-breed open source tools and managed services.

The core consists of Kubernetes clusters in each supported AWS and GCP region. New dedicated clusters are provisioned instantly using FluxCD, a continuous delivery solution that gives us the history and auditability of git. Monitoring and alerting is done using Prometheus, Grafana, and a suite of external services that give us a complete view of cluster health.

The database tier uses a managed CockroachDB service provided by Cockroach Labs. Phase Two is the only provider that is capable of hosting the current Keycloak distribution (the "legacy" store) using CockroachDB. Working with Cockroach Labs gives us the expertise and reliability from hosting thousands of customer clusters at massive scale.

Take me to it!​

Starting today, you'll be able to log into the updated dashboard, and create your dedicated cluster by selecting a region and setting up your billing information.

Following successful billing setup, you will be returned to the Dashboard while your Cluster is provisioned. Once provisioned, you'll be able to create up to 20 realms per cluster, using the same easy setup as you are used to in the shared deployment offering.

Most clusters will be provisioned within 30 minutes, but some requests may take up to 24 hours. Additionally, for payment types such as ACH or SEPA, cluster provisioning will begin following payment clearing (up to 4 days in some cases).

How much does it cost?​

Plans start at $499US per month when paid annually. This provides a set of compute, network and storage resources that have been tested for common use cases for up to 20 realms and 1 million users. If your use case is uncommon or you plan to scale beyond that, our system is designed to scale up with your needs. Our plans scale linearly with resource demands beyond our minimums.

We will continue to support a robust Free tier.

What's next? (psst... Global clusters)​

Many of our on-prem, suppport customers with large use cases asked us to build out a solution for massive-scale, fault-tolerant, multi-region use cases. One of the great parts of building support for Keycloak's existing storage system for CockroacDB is that we've been able to explore use cases that were previously impossible using the standard Keycloak distribution, or required complex, error-prone configurations. For use cases with these requirements, plus global proximity to users and regional failover, we built global clusters, backed by CockroachDB multi-region database, for which we are now in beta.

These clusters provide a minimum of 3 global regions, with 3 instances of Phase Two enhanced Keycloak per region. Global server load balancing provides geographic region affinity and failover to connect your users with the closest, available instances.

There will be two price tiers for global clusters, depending on your use of our shared CockroachDB clusters, or your own dedicated clusters. We expect to launch general availability of global clusters later in Q3 2023.

Please contact sales@phasetwo.io to talk to us about your global cluster use case.

Brand is important to modern SaaS companies, and nowhere is that more apparent than at the front door: the login experience. Unfortunately, the default design of the Keycloak login experience has a "face only a mother could love".

In order to allow customers to customize that experience, we've extended the default Keycloak theming functionality to allow you to easily customize the login pages from the admin console. This eliminates the need to package and deploy a custom theme, and allows fast iteration without restart.

Simple customization​

If you're in a hurry, logo and color customization can be achieved by adding your logo's URL and three color choices. These are available in the General and Login tabs of the Styles section.

In order for these setting to take effect, your Realm Settings Themes must also be set to Attributes for the Login theme type

Full customization using CSS​

Many of you will have more stringent branding requirements. For this, you can override the styles of the default Keycloak login theme. To discover the base styles that are available using this theme, we recommend

Note that using CSS overrides will cause the colors from simple customization not to work.

In order to load your CSS, paste it into the "CSS" field in the Login tab of the Styles section.

This CSS will be the last CSS loaded, overridding the styles in the default keycloak login theme.

References:

• Keycloak login CSS - The default CSS for the keycloak login theme.
• Patternfly 4 - The styling library used by the theme.

CSS Examples​

To get you started with some ideas, we've created 3 example login themes that were done by overridding the CSS. These are free of license restriction, so feel free to download, use and customize the CSS at the links with the example images.

• Consumer - CSS

• Enterprise - CSS

• SaaS - CSS

Images and other assets​

You'll notice that images, icons and fonts not found in the standard Keycloak themes are used. These are referenced by URL in the CSS. For example, if you are used to loading a custom font in the <head> of your HTML, it is possible to do it in CSS using @import:

@import url("https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700&family=Lexend+Deca:wght@300;400;500;600;700&family=Lexend:wght@300;400;500;600;700&family=Work+Sans:wght@300;400;500;600;700&display=swap");

And background and other images can be referenced by their full URL using url(...):

.login-pf body {
  background-image: url("https://raw.githubusercontent.com/p2-inc/keycloak-themes/main/examples/saas/assets/SaaS%20BG.webp");
}

Success!​

As always, our success is based on the success of our customers. We hope this extension and guide has helped you update the default Keycloak login branding to match that of your needs. If you have suggestions for further improvement of this feature, please reach out on GitHub!

tl;dr​

We’ve changed the license of our core extensions from the AGPL v3 to the Elastic License v2. We wanted to share why we made this change and what it means for our customers and community.

Why?​

From our earliest stages, Phase Two has been built as a set of extensions to Keycloak. We have made a commitment that source code for our core exetensions will always be available so that our customers can migrate to their own deployment, while maintaining the extension functionality provided by Phase Two.

As our product matured and found a market fit, it became clear to us that our current license was failing to give our customers that guarantee, and failing to give our company the protection to ensure we could build a business and continue to invest in our extensions.

We've had some very deep conversations with customers and contributors about the future of licensing, and learned a lot about what other companies in our shoes have done. We truly appreciate all of the engagement and feedback, and have done our best to make a decision that is in the best interest of our company, customers and community.

What's allowed?​

1. Hosting and using the extensions by companies as part of their own product.
2. Derivative works that maintain the same license.

What's prohibited?​

1. Providing the extensions as a hosted or managed service. This includes bundling and distribution by companies who sell their products for on-prem and private cloud use.

We believe that the Elastic License strikes a great balance, and we're excited for our next phase of growth!

We've received a lot of support requests about the right way to set up SSO connections. We've published a 5 minute video showing you how to do it easily. Also, the script is included below in case you miss anything!

Script​

Developers have been asking for concise setup instructions for SSO. You’re here for our enterprise SSO functionality. We hear you. Here’s a quick live setup to show you how easy it is.

I’m assuming you have already created a self-serve deployment.

• Start by opening the console.
• Navigate to the Organizations tab.
• Create a new organization. In this case, set a domain when creating an organization that corresponds to the email domains you want to match to their SSO provider.
• Create a Portal Link by selecting it from the action menu of the organization. This is usually meant to be sent to the organization administrator, but in this case, we’ll open this link in an incognito window and configure the identity provider ourselves.

We’ll use the identity provider wizard to setup a SSO connection to Azure AD. I’ve sped this up a bit, but you’ll get an idea of what is happening. Depending on your setup and target identity provider, this will be different.

Now let’s secure an application and use our new SSO connection to log in. For this purpose, we’ve got a debugging application on Github you can use to quickly see how a front end application is secured and what data is shared between Phase Two and the application.

• Clone our debug-app from github, and open up the frontend folder in your favorite editor or IDE.
• Go back to the admin console and navigate to the Clients tab. Create a new client. Let’s call it frontend. This will be a public OIDC client, with localhost:3001 as the root and redirect uri.
• Get the keycloak.json from the configuration and copy it. Paste it into keycloak.json to configure your debug-app.

Before we continue, we need to configure an authentication flow that does our SSO redirect.

• Navigate to the Authentication tab, and duplicate the Browser flow.
• Add the Home IdP Discovery authenticator and move it into the position before the user forms. Configure it to not require a verified domain nor email.
• Finally, using the action menu, bind it to the browser flow.

Go back to the debug-app, and let’s try a login using an email domain that matches the one we configured.

• First, run npm i and npm start to start the debug app, and navigate to http://localhost:3001 in your browser. See that it redirects to the default login.
• Enter the email address in the new email only form.
• We are redirected to the Azure identity provider we set up.
• Log in to Azure, and then we are redirected to back to debug-app.
• Let’s take a look at the token and see the data that came over from Azure.

As a bonus, let’s map some information about the user’s organization memberships into the token in case we need to do something with that information in our application.

• Go back to the Admin UI and navigate to the Client we created.
• Select the frontend-dedicated client scope.
• Add a mapper by configuration.
• Select the Organization Role mapper and configure it as shown.
• Save the configuration.

Now let’s go back to the debug-app and reload.

• Take a look at the token. It now contains information about the organization we created.
• The user was automatically created and added as a member to the organization when we logged in through the Azure identity provider.

You now have a fully working authentication and enterprise SSO setup for your application. It took about 5 minutes!

There are a lot of guides out there, official and unofficial, for how to secure applications with Keycloak. The subject is rather broad, so it's difficult to know where to start. To begin, we'll be focusing on Keycloak's use of OpenID Connect (OIDC), and how to use that standard, along with some helpful libraries, to secure a simple but instructive application.

For the purposes of the sample, we'll actually be using two common applications, a frontend single-page application (SPA) written in JavaScript, and a backend REST API written for Node.js. The language we selected for the sample is JavaScript, but the principles apply no matter the implementation technology you choose.

What is OIDC?​

When learning about identity and access management technologies, you'll be confronted with an alphabet-soup of acronyms to learn. OIDC, or OpenID Connect is one of the most important ones for securing applications, be it browser-based, APIs, mobile or native. Our friend over at OneLogin does a great job of explaining OIDC in plain english for those that are curious.

For the purpose of this guide, it is sufficient to know that OIDC is an open authentication protocol that works on top of the OAuth 2.0 framework. OIDC allows individuals to use single sign-on (SSO) to access relying party sites using OpenID Providers (OPs), such as an email provider or social network, to authenticate their identities. It provides the application or service with information about the user, the context of their authentication, and access to their profile information.

Login flow​

A "flow" in OIDC terms is a mechanism of authenticating a user, and obtaning access tokens. The flow we'll be using in this guide is called the authorization code flow. Fortunately, the internals of the flow are not necessary to understand, as Keycloak handles the details for you.

However, it is useful to see what is going on in the login process, so that you understand your user's experience.

Setup​

We'll make an assumption for this guide that you are using a cloud deployment of Phase Two enhanced Keycloak. If you haven't already set one up, go over to the self-service launch announcement for details. You may also use your own Keycloak setup, but that setup is beyond the scope of this article.

The sample applications are available in our demo repo on Github. Clone that repo to your local machine. You'll find the applications in the frontend and backend directory, and a set of supporting files for configuration and deployment.

git clone https://github.com/p2-inc/debug-app.git
cd debug-app

Client​

Every application that Keycloak protects is considered a Client. Log into your Keycloak realm, and click on Clients in the left navigation, and click Create client.

1. Enter frontend as the Client ID and click Next
2. In the Capability config screen, keep the defaults and click Save
3. In the Access settings screen, enter the following values:
   1. http://localhost:3001/* for Valid redirect URIs
   2. + in Valid post logout redirect URIs
   3. + in Web origins
4. Click Save
5. In the upper right corner, open the Action menu and select Download adapter config. Click Download and move the file to the debug-app repo you cloned under the frontend folder.

Make a user​

Before we run the application, we need to create a user to log in. Click on Users in the left navigation, and click Add user. You only need to give the user a username and click Create. Find the Credentials tab and click Set password to give the user a password.

Running the sample apps​

Open two terminal windows and go to the directory of the repo you cloned in both. To start, run the following commands in each terminal:

Frontend:

cd frontend/
npm install
npm start

Backend:

cd backend/
npm install
KC_REALM=<your-realm-name> KC_URL=<your-keycloak-url> npm start

Be sure to replace the realm name, and the URL of your Keycloak installation (e.g. https://usw2.auth.ac/auth/).

This will install the necessary components using npm, and will start the servers for both applications. Note: the applications use ports 3001 and 3002 by default. If you have other applications running on these ports, you may have to temporarily shut them down.

Putting it all together​

Load http://localhost:3001/ in your browser. This will load the frontend application, which will be immediately redirected to the Keycloak login page. Log in with the user you created.

Once you log in, you'll see your profile, and several menu items. First click to the Access token menu item. You'll see the information from the parsed access token that was returned by Keycloak. This contains information about the user, but also claims related to the users roles and groups. This is because access tokens are meant to be read and validated by resource servers (i.e. our backend service).

Next, click ID token. You'll see similar information to what we saw in the access token, but limited to a standardized set of information that identifies the authentication state of the user. ID tokens are not meant for calling resource servers, and because of that, don't contain claims that are meant to be validated by backend services.

Clicking Service will call the backend service. You'll see a message that indicates the frontend called the backend, passing the access token, and was authorized to access a secured service.

You can also try the built-in Keycloak Account Management console by clicking Account, which gives the user a simple way to manage their information that is stored in Keycloak. It is not necessary to use this with your applications, as you may choose to build it in to your app. However, it's a good tool to have out of the box.

Finally, clicking Logout will take you back to the login page. This is actually sending you to the frontend's initial page, which is redirecting you to the login page as its default behavior.

What just happened?​

There's a lot that goes into implementation of the OIDC flow we used to secure our sample applications. Part of the reason to use Keycloak is the mature implementation and client libraries that make protecting applications in a secure way almost trivial.

We encourage you to look at the source in the sample applications (specifically frontend/app.js and backend/app.js) and observe how the Keycloak client libraries are used to secure these applications. This will be a good place to start when you are working on securing your own applications.

Your application​

Another incredible advantage to using standards like OIDC is that you are not constrained to using Keycloak libraries. Because your applications may not be written in JavaScript also, it's easy to use other language OIDC client libraries. We maintain a list of OIDC libraries, and the OpenID Foundation also maintains lists of certified and uncertified implementations

Today you saw how to quickly secure an application using Keycloak, and learned more about the underlying OIDC standards. We look forward to seeing what you build!

Someone who is reading this article is probably very different that the average internet user when it comes to passwords. Developers and IT admins, either because of security savvy or compliance, use password managers, multi-factor authentication (MFA) mechanisms, or prefer sites that offer password-less authentication. Furthermore, they are keenly aware of the weaknesses in their personal "attack surface", and search for ways to balance convenience with risk.

But you are here because you want to find a way to implement magic links quickly. First, some background.

What are magic links?​

Magic links are a type of password-less authentication that allow your users to log in to your application following a link that is emailed to them, rather than typing a username and password. Magic links can also be used as a part of a multi-factor authentication (MFA) strategy.

In a magic link flow, the application's authentication provider asks users for an email address rather than a password. The authentication provider generates a link with an embedded token, and sends to the user's email. There may be some other steps taken by the provider, such as verifying the provided email address matches an existing user. The user then opens the email, clicks the link, is verified by the authentication provider, and is granted access to the application

Pros and cons​

Like any mechanism that tries to streamline a security process such as authentication, there are both pros and cons to the magic link approach. First in the plus column:

• Enhances user experience, which makes users more likely to use your application, and be satisfied with the experience. This drives user engagement.
• User onboarding is accelerated, as magic links can be sent to new users as well as existing ones. Registration for your application is as easy as entering your email address.
• You'll never have a password breach. When there are no passwords, there are no password breaches. A huge number of corporate data breaches are due to insufficient and compromised passwords.
• No more customer support requests related to lost passwords. Over half of customer support requests are due to authentication problems, many of those are users unable to remember their passwords. This eliminates a huge portion of those.

Nothing is perfect, and there are also several potential downsides to magic links:

• Account security and access are now tied to the security of the user's email account. If the user's computer or other device is compromised, and attacker could potentially obtain the link and impersonate the user.
• If the user or email provider does not enforce encrypted network access to email, it may be possible for an attacker to perform a man-in-the-middle attack where they can obtain the link by observing network traffic.
• Ability to access your application is now tied to email deliverability. If your email service or the user's email provider fails to deliver the email containing the link in a timely fashion, it could deteriorate the experience for the user.

Limiting risk​

Fortunately, there are things your application and the user can do in order to limit some of the possible downside risks of using magic links. Your application can:

• Make the magic links single use, or set a very short expiration time for the links.
• Enforce an additional factor when using magic links.

Your user can:

• Choose an email provider that enforces the use of encrypted connections.
• Use multi-factor authentication (MFA) mechanisms to further protect their email accounts.

Setup guide​

Sorry for the wait! We wanted to give you an overview of magic links before diving into how to set them up with Phase Two.

If you haven't already, get an account on Phase Two. You'll notice that we use magic links in addition to social login options. As we said above, we're trying to make it as frictionless as possible to get in and start using the product.

Once you log in and create your first deployment, open the Phase Two enhanced Keycloak console. In order to email links to your users, you'll need to set up email. If you haven't already done that, head over to our email setup guide.

After you've completed email setup, select the Authentication menu item, and then select the Magic link flow from the list.

Open the configuration for the Magic Link Authenticator by clicking the gear icon on the last line with the Magic Link execution. You'll notice two options:

• Force create user creates a new user when an email is provided that does not match an existing user. This allows the use of magic links to register new users that have not been previously seen.
• Update profile on create adds an UPDATE_PROFILE required action if the user was created. This means that the user will need to fill out other required fields such as first/last name, etc.

For the purpose of our demonstration, let's set Force create user to ON and Update profile on create to OFF (remember, low friction). Save the configuration, and go back to the flow page.

In the Action menu of the flow page, select Bind, and select Browser flow.

Now you're ready to test it out. If you don't have an application that is setup and protected by Keycloak, you can use the built-in account console to try it out. Navigate to the Clients menu, and open the link next to the account client in an incognito window (this will prevent conflict, as you are already logged in to the admin console as the administrator).

Click Sign In and you'll be redirected to the authentication page. Enter your email address, and you'll be sent a magic link. Click on the link in your email, and you'll see your details in the account console.

Go back to the admin console in the other browser window, and navigate to the Users section. You will be able to find the user that was just created.

Magic links are a great way to streamline your user onboarding and experience to help you easily drive engagement across your application. Phase Two makes it quick and easy to integrate magic links (and social login, and enterprise SSO, and much more). Stay tuned for more guides that will help you build the authentication experience that is right for your app.

One of the first things you will need to do when getting a Keycloak Realm ready for use is to set up your email server configuration. There are many system emails that are sent to users in the course of verifying and updating user accounts: Email address verification, magic links, password reset, account update, login failure notifications, identity provider linking, etc.

In order to provide your users with a positive experience, these messages need a way to get to them. Keycloak supports any internet reachable SMTP server. If you are currently testing, and don't have an email server or service that you currently use, SendGrid provides free accounts that allow you to send up to 100 emails per day forever. For debugging, you can also use a service like MailTrap to give you a catch-all for emails coming from Keycloak.

If you are using a Phase Two Deployment, log in to the self-service dashboard, and click on the Open Console link for the Deployment you wish to use. Once in the Keycloak admin console, click Realm settings in the left menu, and then click the Email tab.

In the first section, labeled Template, you will set options that will be used in the templates for the emails that are sent to your users. The only required field is the From field, which must contain the email address the user will see the email originating from. This should be an email address that your email server is expecting, and it will not block for authorization reasons.

The other fields in the Template section are not required, but will enhance how your emails look:

• From address used to send emails (required)
• From display name a user-friendly name displayed along From
• Reply to an email address that will be used by email clients when your user replies to an email
• Reply to display name a user-friendly name displayed along Reply to
• Envelope from Bounce Address used for the mails that are rejected

In the Connection & Authentication section, you will provide details of your SMTP server:

• Host indicates the SMTP server hostname used for sending emails
• Port indicates the SMTP server port (usually 25, 465, 587, or 2525)
• Encryption support encryption for communication with your SMTP server
• Authentication if your SMTP server requires authentication, and supply the Username and Password

Finally, before you click Save, click the Test connection button to send a test email to the email address of the currently logged in user. If you don't have that set, you might have click Save and edit your user before you come back. You'll receive a success message, or information that will help you resolve problems.

Once you do that, you'll have accomplished a significant task which enables lots of other functionality!

Also, stay tuned for another post on how to customize your email templates to match your branding and messaging.

We've been pretty quiet over the summer. Since we released the Organizations and Magic Link extensions and open sourced them, there has been a lot of interest in using Phase Two.

We were flattered by the inbound interest, but our small team wasn't able to keep up with demand for trial accounts. Rather than scramble against that demand, we opted to pause new accounts, and instead build a self-service tool to allow anyone to quickly provision a new deployment a try it out.

Today we're announcing the beta launch of the Phase Two Self-service deployment tool. This tool allows you to easily create new deployments of the Phase Two enhanced version of Keycloak in our secure, highly-available clusters. In the future, it will also allow you to deploy dedicated instances that use your own database.

Take a look at how easy it is to get started:

The clusters that run our deployments are available in two regions (AWS, us-west-2 and eu-central-1), and are backed by CockroachDB, giving you scale, resilience and low-latency performance. In the future, clusters and dedicated instances will be available in other regions based on demand.

We hope you find this new tool valuable, and we look forward to feedback and participation from both our customers and the wider Keycloak community.

TRY IT NOW!

Today we're making two announcements: A new, highly-requested feature, and the open sourcing of the extension at the same time. We've received a lot of requests from customers to implement "magic link" login functionality that would allow users to login to an application using a link sent to their email or over some other secure channel.

To that end, we've implemented two pathways for creating a magic link. One can be configured in the Authentication section of the admin UI by duplicating the Browser flow, and replacing the normal Username/Password/OTP forms with the Magic Link execution type This mechanism inserts a authenticator in the login flow that intercepts the email address and sends the magic link in an email to to the user.

We've also implemented a web service that allows you to create a magic link without necessarily sending an email. This will allow you to send the link through another channel. Specification for the new endpoint can be found in the Magic Link API Documentation.

Both methods have the option of forcing the creation of a new user when an unknown email address is used. This allows a combination login/registration flow that combines an email verification. We think this really nails reducing friction in a new user flow.

We're open sourcing the Keycloak extensionsso that the broad Keycloak community can benefit right away. We are doing this in line with our committment to keeping our core extensions open source. We hope you find these extensions valuable, and we look forward to feedback and participation from both our customers and the wider Keycloak community.

The extension is available on GitHub https://github.com/p2-inc/keycloak-magic-link

Today we're open sourcing set of Keycloak extensions that are focused on solving several of the common use cases of multi-tenant, SaaS applications that Keycloak does not solve out of the box. We are doing this in line with our committment to keeping our core extensions open source. These extensions are the basis of our Organizations features, which allow Phase Two customers to model their own customers in their systems and create enterprise "team" functionality that suits their business case.

A variation of this code has been built, enhanced and used in production by several customers for almost two years. It is now available as open source for members of the broader Keycloak community. We hope you find these extensions valuable, and we look forward to feedback and participation from both our customers and the wider Keycloak community.

The extension is available on GitHub https://github.com/p2-inc/keycloak-orgs