Setting up SSO with Phase Two and Keycloak

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 to leverage an open source SSO provider

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!

In addition, by choosing an open source SSO provider in Keycloak, you have also picked a cost-effective option too. Read more about understanding the costs of implementing an open source provider for IAM.