6 posts tagged with "frameworks"

Securing Remix Apps with Keycloak

April 24, 2024 · 4 min read

Phase Two

In this article we'll be using Keycloak to quickly augment an application with user management and SSO. We will demonstrate the integration by securing a page for logged-in users. This quickly provides a jump-off point to more complex integrations.

info

If you just want to skip to the code, visit the Phase Two Remix example. We also have a plain React example.

Setting up a Keycloak Instance

Instructions

tip

If you already have a functioning Keycloak instance, you can skip to the next section.

Rather than trying to set up a "from scratch" instance of Keycloak, we're going to short-circuit that process by leveraging a free Phase Two Starter instance. The Starter provides a free hosted instance of Phase Two's enhanced Keycloak ready for light production use cases.

Visit the sign-up page.
Enter an email, use a Github account, or use an existing Google account to register.
Follow the register steps. This will include a sign-in link being sent to your email. Use that for password-less login.
After creating an account, a realm is automatically created for you with all of the Phase Two enhancements. You need to create a Deployment in the Shared Phase Two infrastructure in order to gain access to the realm. Without a deployment created, the Create Shared Deployment modal will automatically pop up.
Create a Shared Deployment by providing a region (pick something close to your existing infrastructure), a name for the deployment, and selecting the default organization that was created for you upon account creation. Hit "Confirm" when ready. Standby while our robots get to work generating your deployment. This can take a few seconds.
After the deployment is created and active, you can access the Keycloak Admin console by clicking "Open Console" for that deployment. Open it now to see the console.

At this point, move on to the next step in the tutorial. We'll be coming back to the Admin Console when its time to start connecting our App to the Keycloak instance.

Setting up an OIDC Client

Instructions

We need to create a OpenID Connect Client in Keycloak for the app to communicate with. Keycloak's docs provide steps for how to create an OIDC client and all the various configurations that can be introduced. Follow the steps below to create a client and get the right information necessary for app configuration.

Open the Admin UI by clicking Open Console in the Phase Two Dashboard.
Click Clients in the menu.
Click Create client.
Leave Client type set to OpenID Connect.
Enter a Client ID. This ID is an alphanumeric string that is used in OIDC requests and in the Keycloak database to identify the client.
Supply a Name for the client.
Click Next.
Under the Capability Config section, leave the defaults as selected. This can be configured further later.
- Client authentication to On.
- Authorization to Off.
- Standard flow checked. Direct access grants checked. All other items unchecked.
Click Next.
Under Login settings we need to add a redirect URI and Web origin in order. Assuming you are using the example applicaiton:
Valid redirect URI (allows redirect back to application)
```
http://localhost:3000/*
```
Web origins (allows for Token auth call)
```
http://localhost:3000
```
URI and Origin Details
The choice of localhost is arbitrary. If you are using an example application running locally, this will apply. If you are using an app that you actually have deployed somewhere, then you will need to substitute the appropriate URI for that.
Click Save

OIDC Config

We will need values to configure our application. To get these values follow the instructions below.

Click Clients in the menu.
Find the Client you just created and click on it. In the top right click the Action dropdown and select Download adapter config.
Select Keycloak OIDC JSON in the format option. The details section will populate with the details we will need.
- Note the realm, auth-server-url, and resource values.
You also need to copy the Client secret in the Credential tab for the client to use. Once on the Credential tab, click the copy button to copy the key to your clipboard. Save the key somewhere for use later in this tutorial

Adding a Non-Admin User

Instructions

info

It is bad practice to use your Admin user to sign in to an Application.

Since we do not want to use our Admin user for signing into the app we will build, we need to add a another non-admin user.

Open the Admin UI by clicking Open Console in the Phase Two Dashboard.
Click Users in the menu.
Click Add user.
Fill out the information for Email, First name, and Last name. Click Create.
We will now set the password for this user manually. Click Credentials (tab) and click Set Password. Provide a password for this user. For our use case, as a tutorial, you can leave "Temporary" set to "Off".
Click Save and confirm the password by clicking Save password

Setting up a Remix Project

info

We will use the Phase Two Remix example code here, but the logic could easily be applied to any existing application.

Clone the Phase Two example repo.
Open the Remix folder within /frameworks/remix.
Run npm install and then npm run dev -- --port 3000. This example leverages remix-auth and remix-keycloak to provide HOC support.
Open the app/services/keycloak.server.ts file. This is a server only file. We will be updating a few values from the prior section where we set up our OIDC client. Taking the values from the OIDC Client Config section, set those values in the code. While it is recommended to use Environment variables for the secret, for the purpose of this tutorial, paste in the Client secret from the OIDC client creation section for the value of clientSecret:

const kcConfig = {
  useSSL: true,
  domain: "usw2.auth.ac/auth",
  realm: "shared-deployment-001",
  clientID: "reg-example-1",
  clientSecret: "CLIENT_SECRET", // Paste "Client secret" here. Use Environment variables in prod
  callbackURL: "http://localhost:3000/auth/keycloak/callback",
};

Those are used to popluate the config for the KeycloakStrategy:

export default new KeycloakStrategy(kcConfig, ({ profile }) => profile);

The config is then used with the Authenticator instance in the app/services/auth.server.ts file. The authenticator instance uses the Session Storage to manage the state of authentication via a cookie.

import { Authenticator } from "remix-auth";
import keycloakServer from "./keycloak.server";
import { sessionStorage } from "~/services/session.server";

export const authenticator = new Authenticator(sessionStorage);

authenticator.use(keycloakServer);

At this point our entire application will be able to access all information and methods needed to perform authentication. View the session.server.ts file for additional information about how the SessionStorage is used. The SessionStorage stores the Keycloak token and is used to derive the authenticated state. View user.tsx for exactly how the code is authenticating your user. The sections rendering the Log in and Log out buttons are conditional areas based on the authenticated context. The buttons invoke server-side APIs provided by remix-auth.

The logic using the authenticator to conditionally determine the Authenticated state, can be used to secure routes, components, and more.

Open localhost:3000. You will see the Phase Two example landing page. You current state should be Not authenticated. Click Log In. This will redirect you to your login page.
info
Use the non-admin user created in the previous section to sign in.
Enter the credentials of the non-admin user you created. Click Submit. You will then be redirected to the application. The Phase Two example landing page now loads your Authenticated state, displaying your user's email and name.
Neat! If you clear the browser state for that tab, then you will have to be redirected away to sign-in again.

Learning more

Phase Two's enhanced Keycloak provides many ways to quickly control and tweak the log in and user management experience. Our blog has many use cases from customizing login pages, setting up magic links (password-less sign in), and Organization workflows.

Securing Vue Apps with Keycloak

September 14, 2023 · One min read

Phase Two

info

If you just want to skip to the code, visit the Phase Two Vue example.

Setting up a Keycloak Instance

Instructions

tip

If you already have a functioning Keycloak instance, you can skip to the next section.

Visit the sign-up page.
Enter an email, use a Github account, or use an existing Google account to register.
Follow the register steps. This will include a sign-in link being sent to your email. Use that for password-less login.
After creating an account, a realm is automatically created for you with all of the Phase Two enhancements. You need to create a Deployment in the Shared Phase Two infrastructure in order to gain access to the realm. Without a deployment created, the Create Shared Deployment modal will automatically pop up.
Create a Shared Deployment by providing a region (pick something close to your existing infrastructure), a name for the deployment, and selecting the default organization that was created for you upon account creation. Hit "Confirm" when ready. Standby while our robots get to work generating your deployment. This can take a few seconds.
After the deployment is created and active, you can access the Keycloak Admin console by clicking "Open Console" for that deployment. Open it now to see the console.

At this point, move on to the next step in the tutorial. We'll be coming back to the Admin Console when its time to start connecting our App to the Keycloak instance.

Setting up an OIDC Client

Instructions

Open the Admin UI by clicking Open Console in the Phase Two Dashboard.
Click Clients in the menu.
Click Create client.
Leave Client type set to OpenID Connect.
Enter a Client ID. This ID is an alphanumeric string that is used in OIDC requests and in the Keycloak database to identify the client.
Supply a Name for the client.
Click Next.
Under the Capability Config section, leave the defaults as selected. This can be configured further later.
- Client authentication to On.
- Authorization to Off.
- Standard flow checked. Direct access grants checked. All other items unchecked.
Click Next.
Under Login settings we need to add a redirect URI and Web origin in order. Assuming you are using the example applicaiton:
Valid redirect URI (allows redirect back to application)
```
http://localhost:3000/*
```
Web origins (allows for Token auth call)
```
http://localhost:3000
```
URI and Origin Details
The choice of localhost is arbitrary. If you are using an example application running locally, this will apply. If you are using an app that you actually have deployed somewhere, then you will need to substitute the appropriate URI for that.
Click Save

OIDC Config

We will need values to configure our application. To get these values follow the instructions below.

Click Clients in the menu.
Find the Client you just created and click on it. In the top right click the Action dropdown and select Download adapter config.
Select Keycloak OIDC JSON in the format option. The details section will populate with the details we will need.
- Note the realm, auth-server-url, and resource values.
You also need to copy the Client secret in the Credential tab for the client to use. Once on the Credential tab, click the copy button to copy the key to your clipboard. Save the key somewhere for use later in this tutorial

Adding a Non-Admin User

Instructions

info

It is bad practice to use your Admin user to sign in to an Application.

Since we do not want to use our Admin user for signing into the app we will build, we need to add a another non-admin user.

Open the Admin UI by clicking Open Console in the Phase Two Dashboard.
Click Users in the menu.
Click Add user.
Fill out the information for Email, First name, and Last name. Click Create.
We will now set the password for this user manually. Click Credentials (tab) and click Set Password. Provide a password for this user. For our use case, as a tutorial, you can leave "Temporary" set to "Off".
Click Save and confirm the password by clicking Save password

Setting up a Vue.js Project

info

We will use the Phase Two Vue example code here, but the logic could easily be applied to any existing application.

This example uses Vue.js. We're going to leverage oidc-client-ts to integrate OIDC authentication with the Vue app. The oidc-client-ts package is a well-maintained and used library. It provides a lot of utilities for building out a fully production app.

Clone the Phase Two example repo.
Open the Vue folder within /frameworks/vue and open the /nuxt/oidc-client-ts folder.
Run npm install and then npm run dev.

We'll review where we configure out Keycloak instance. First open /auth.ts. In this file you will want to update it with the values for the Keycloak instance we set-up earlier in the tutorial. Update the clientSecret with the value. Use and environment variable here if you wish.

export const keycloakConfig = {
  authorityUrl: "https://euc1.auth.ac",
  applicationUrl: "http://localhost:3000",
  realm: "shared-deployment-001",
  clientId: "reg-example-1",
  clientSecret: "CLIENT_SECRET",
};

After the config, you can see how the OIDC instance is started.

const settings = {
  authority: `${keycloakConfig.authorityUrl}/auth/realms/${keycloakConfig.realm}`,
  client_id: keycloakConfig.clientId,
  client_secret: keycloakConfig.clientSecret,
  redirect_uri: `${window.location.origin}/auth`,
  silent_redirect_uri: `${window.location.origin}/silent-refresh`,
  post_logout_redirect_uri: `${window.location.origin}`,
  response_type: "code",
  userStore: new WebStorageStateStore(),
  loadUserInfo: true,
};
this.userManager = new UserManager(settings);

With the Keycloak instance defined, we attach this to the app instance for Vue. Switch to /main.ts
```
import Auth from "@/auth";
// ...
app.config.globalProperties.$auth = Auth;
```
We pull in the Auth instance then expose it through the $auth variable.
There are a few main pages in play here that we define to create paths the library can leverage. The /view/auth and /view/silent-refresh create paths at the same name. These are used to do the redirection during authentication. From within these we use the Auth instance to direct the user around within the app. For instance in /views/AuthView:
```
export default {
  name: "AuthAuthenticated",
  async mounted() {
    try {
      await this.$auth.signinCallback();
      this.$router.push("/");
    } catch (e) {
      console.error(e);
    }
  },
};
```
The router.push naively sends someone to the home page. This could be updated to go to any number of places, including the page one started the login flow from if you were to store that information to be retrieved.

Now that we have all the things setup, we can define the user component /components/User to easily pull information about the user's state and display the appropriate UI.

export default {
  name: "UserComponent",
  data() {
    return {
      user: null,
      signIn: () => this.$auth.signinRedirect(),
      logout: () => this.$auth.signoutRedirect(),
    };
  },
  async created() {
    const user = await this.$auth.getUser();
    if (user) {
      this.user = user;
    }
  },
};

With this, the user object is now easily available. A simple v-if="user" allows the app to determine what UI to show.

Learning more

Securing Nuxt Apps with Keycloak

September 8, 2023 · 7 min read

Phase Two

info

If you just want to skip to the code, visit the Phase Two Nuxt example.

Setting up a Keycloak Instance

Instructions

tip

If you already have a functioning Keycloak instance, you can skip to the next section.

Visit the sign-up page.
Enter an email, use a Github account, or use an existing Google account to register.
Follow the register steps. This will include a sign-in link being sent to your email. Use that for password-less login.
After creating an account, a realm is automatically created for you with all of the Phase Two enhancements. You need to create a Deployment in the Shared Phase Two infrastructure in order to gain access to the realm. Without a deployment created, the Create Shared Deployment modal will automatically pop up.
Create a Shared Deployment by providing a region (pick something close to your existing infrastructure), a name for the deployment, and selecting the default organization that was created for you upon account creation. Hit "Confirm" when ready. Standby while our robots get to work generating your deployment. This can take a few seconds.
After the deployment is created and active, you can access the Keycloak Admin console by clicking "Open Console" for that deployment. Open it now to see the console.

At this point, move on to the next step in the tutorial. We'll be coming back to the Admin Console when its time to start connecting our App to the Keycloak instance.

Setting up an OIDC Client

Instructions

Open the Admin UI by clicking Open Console in the Phase Two Dashboard.
Click Clients in the menu.
Click Create client.
Leave Client type set to OpenID Connect.
Enter a Client ID. This ID is an alphanumeric string that is used in OIDC requests and in the Keycloak database to identify the client.
Supply a Name for the client.
Click Next.
Under the Capability Config section, leave the defaults as selected. This can be configured further later.
- Client authentication to On.
- Authorization to Off.
- Standard flow checked. Direct access grants checked. All other items unchecked.
Click Next.
Under Login settings we need to add a redirect URI and Web origin in order. Assuming you are using the example applicaiton:
Valid redirect URI (allows redirect back to application)
```
http://localhost:3000/*
```
Web origins (allows for Token auth call)
```
http://localhost:3000
```
URI and Origin Details
The choice of localhost is arbitrary. If you are using an example application running locally, this will apply. If you are using an app that you actually have deployed somewhere, then you will need to substitute the appropriate URI for that.
Click Save

OIDC Config

We will need values to configure our application. To get these values follow the instructions below.

Click Clients in the menu.
Find the Client you just created and click on it. In the top right click the Action dropdown and select Download adapter config.
Select Keycloak OIDC JSON in the format option. The details section will populate with the details we will need.
- Note the realm, auth-server-url, and resource values.
You also need to copy the Client secret in the Credential tab for the client to use. Once on the Credential tab, click the copy button to copy the key to your clipboard. Save the key somewhere for use later in this tutorial

Adding a Non-Admin User

Instructions

info

It is bad practice to use your Admin user to sign in to an Application.

Since we do not want to use our Admin user for signing into the app we will build, we need to add a another non-admin user.

Open the Admin UI by clicking Open Console in the Phase Two Dashboard.
Click Users in the menu.
Click Add user.
Fill out the information for Email, First name, and Last name. Click Create.
We will now set the password for this user manually. Click Credentials (tab) and click Set Password. Provide a password for this user. For our use case, as a tutorial, you can leave "Temporary" set to "Off".
Click Save and confirm the password by clicking Save password

Setting up a Nuxt Project

info

We will use the Phase Two Nuxt example code here, but the logic could easily be applied to any existing application.

This example uses Nuxt3. There are a couple methods by which you can integrate Keycloak to your Nuxt application. We're going to explore two methods here, one uses keycloak-js and the other leverages oidc-client-ts. The keycloak-js library provides a simple, client-only method, but lacks some of the sophistication provided by the oidc-client library that is heavily supported and more widely used.

Using `keycloak-js`

info

For this example, we need to disable "Client Authentication" in the OIDC client that was setup earlier. This is available under Client > Settings > Capability config > Client authentication to OFF.

Clone the Phase Two example repo.
Open the Nuxt folder within /frameworks/nuxt and open the keycloak-js folder within /frameworks/nuxt/keycloak-js.
Run npm install and then npm run dev. keycloak-js is a Javascript library that provides a fast way to secure an application.
The project makes use of the following Nuxt items: components, composables, layouts, and plugins. We'll review each in kind.
The main component that shows the User's authenticated state is in /components/User. In this component we call the useKeycloak composable, which let's us key into the keycloak-js functions that we've wrapped to make easily availble.
```
const { keycloak, authState } = useKeycloak();

function login() {
  keycloak.login();
}

function logout() {
  keycloak.logout();
}
```
Lower in the file the component leverages v-if checks to determine if the authState is authenticated or not. Depending on the state, a Log in or Log out button is available.

Let's take a look at the setup for the composable next. Our composable is in /composables/keycloak-c. A composable is a function defined that can be called anywhere in the Nuxt application. It's a good way to abstract logic to be reused. In our case we use it to wrap a keycloak-js plugin (more on that in the next step) and help provided a state value for the authenticated state.

export const useKeycloak = () => {
  const nuxtApp = useNuxtApp();
  const keycloak = nuxtApp.$keycloak as Keycloak;
  const authState = useState("authState", () => "unAuthenticated");

  keycloak.onAuthSuccess = () => (authState.value = "authenticated");
  keycloak.onAuthError = () => (authState.value = "error");

  return {
    keycloak,
    authState,
  };
};

In the plugin, /plugins/keycloak.client.ts we instantiate the keycloak-js library. We can then attach that instance to the NuxtApp instance. Substitute the correct values for your Keycloak instance that we created earlier in the tutorial.

export default defineNuxtPlugin((nuxtApp) => {
  const initOptions: KeycloakConfig = {
    url: "https://euc1.auth.ac/auth/",
    realm: "shared-deployment-001",
    clientId: "reg-example-1",
  };

  const keycloak = new Keycloak(initOptions);

  nuxtApp.$keycloak = keycloak;

  keycloak.init({
    onLoad: "check-sso",
  });
});

The logic for checking the authenticated state can be used to expand in ways to secure your site in a number of ways.

Using `oidc-client`

The oidc-client-ts package is a well-maintained and used library. It provides a lot of utilities for building out a fully production app.

Clone the Phase Two example repo.
Open the Nuxt folder within /frameworks/nuxt and open the /nuxt/oidc-client-ts folder.
Run npm install and then npm run dev.
The structure of the project is similar to the keycloak-js version but with a the use of services, stores, and middleware.
We'll review where we configure out Keycloak instance. First open /services/keycloak-config.ts. In this file you will want to update it with the values for the Keycloak instance we set-up earlier in the tutorial. Make sure you are using the one with Client Authentication enabled. Update the clientSecret with the value. Use and environment variable here if you wish.
```
export const keycloakConfig = {
  authorityUrl: "https://euc1.auth.ac",
  applicationUrl: "http://localhost:3000",
  realm: "shared-deployment-001",
  clientId: "reg-example-1",
  clientSecret: "CLIENT_SECRET",
};
```

Switch over to the /services/auth-service now to see how the Oidc instance is started. The class pulls in values from the keycloakConfig to use in the constructor. The other functions are wrappers around methods provided by the oidc-client library. This allows us to key into things like signInRedirect and signoutRedirect.

How the settings are integrated:

const settings = {
  authority: `${keycloakConfig.authorityUrl}/auth/realms/${keycloakConfig.realm}`,
  client_id: keycloakConfig.clientId,
  client_secret: keycloakConfig.clientSecret,
  redirect_uri: `${window.location.origin}/auth`,
  silent_redirect_uri: `${window.location.origin}/silent-refresh`,
  post_logout_redirect_uri: `${window.location.origin}`,
  response_type: "code",
  userStore: new WebStorageStateStore(),
  loadUserInfo: true,
};
this.userManager = new UserManager(settings);

Example function wrapper:

public signInRedirect() {
  return this.userManager.signinRedirect();
}

With the AuthService defined, we can now expose that through a composable. Switch to the /composables/useServices file. The file is simple but provides a way for any component to hook into the service instance.
```
import AuthService from "@/services/auth-service";
import ApplicationService from "@/services/application-service";
import { useAuth } from "@/stores/auth";

export const useServices = () => {
  const authStore = useAuth();

  return {
    $auth: new AuthService(),
    $application: new ApplicationService(authStore.access_token),
  };
};
```
We pull in the AuthService then expose it through the $auth variable. The $application variable exposes the ApplicationService which is provided as an example of how you could secure API calls.
We leverage the pinia library to make store User information to make it easily accessible. Open /stores/auth/index. From within this file, we can wrap the User object exposed by the oidc-client package. This can then be leveraged in the middleware function we want to define or to pull information quickly about the user.
There are a few main pages in play here that we define to create paths the library can leverage. The /pages/auth, /pages/logout, /pages/silent-refresh create paths at the same name. These are used to do the redirection during authentication or log out. From within these we use the AuthService to direct the user around within the app. For instance in /auth:
```
const authenticateOidc = async () => {
  try {
    await services.$auth.signInCallback();
    router.push("/");
  } catch (error) {
    console.error(error);
  }
};

await authenticateOidc();
```
The router.push naively sends someone to the home page. This could be updated to go to any number of places, including the page one started the login flow from if you were to store that information to be retrieved.

We have also created a middleware file in /middleware/auth.global to be used in a couple of ways. It checks if the user is authenticated and based on that knowledge, stores the user information in the store (if not there) or could be used to send someone to login. For our example, we created buttons to initiate that but there is a comment which shows how you could force a set of paths to require login.

const authFlowRoutes = ["/auth", "/silent-refresh", "/logout"];

export default defineNuxtRouteMiddleware(async (to, from) => {
  const authStore = useAuth();
  const services = useServices();
  const user = (await services.$auth.getUser()) as User;

  if (!user && !authFlowRoutes.includes(to.path)) {
    // use this to automatically force a sign in and redirect
    // services.$auth.signInRedirect();
  } else {
    authStore.setUpUserCredentials(user);
  }
});

Now that we have all the things setup, we can define the user component /components/User to easily pull information about the user's state and display the appropriate UI.
```
const authStore = useAuth();
const user = authStore.user;

const signIn = () => services.$auth.signInRedirect();
const signOut = () => services.$auth.logout();
```
With this, the user object is now easily available. A simple v-if="user" allows the app to determine what UI to show.
A bit more complicated of a setup, but more elegant in the handling of the logged in flow. The oidc-client allows for much better fine-tuning of the experience.

Learning more

Django Web Authentication with Keycloak

August 31, 2023 · 6 min read

Phase Two

Django is a high-level, open-source web framework for building web applications using the Python programming language. It follows the Model-View-Controller (MVC) architectural pattern.

In this article we'll be using Keycloak to secure a Django Web application.

info

If you just want to skip to the code, visit the Phase Two Django example. We are also building Keycloak examples for other frameworks.

Setting up a Django Project

The following could be applied to an existing Django application, but we have chosen to use the excellent tutorial application built by Mozilla as our example. If you aren't yet familiar with Django, we encourage you to follow the tutorial there.

The completed code for that tutorial is available in their GitHub repository. We'll clone it to get started.

Quick Start

To get this project up and running locally on your computer:

Set up the Python development environment. We recommend using a Python virtual environment.

Assuming you have Python setup, run the following commands (if you're on Windows you may use py or py -3 instead of python to start Python):

pip install -r requirements.txt
python manage.py makemigrations
python manage.py migrate
python manage.py collectstatic
python manage.py test # Run the standard tests. These should all pass.
python manage.py createsuperuser # Create a superuser
python manage.py runserver

Open a browser to http://127.0.0.1:8000/admin/ to open the admin site
Create a few test objects of each type.
Open tab to http://127.0.0.1:8000 to see the main site, with your new objects.

Setting up a Keycloak Instance

Before customizing the Django app, we need to set up and configure our Keycloak instance.

Instructions

tip

If you already have a functioning Keycloak instance, you can skip to the next section.

Visit the sign-up page.
Enter an email, use a Github account, or use an existing Google account to register.
Follow the register steps. This will include a sign-in link being sent to your email. Use that for password-less login.
After creating an account, a realm is automatically created for you with all of the Phase Two enhancements. You need to create a Deployment in the Shared Phase Two infrastructure in order to gain access to the realm. Without a deployment created, the Create Shared Deployment modal will automatically pop up.
Create a Shared Deployment by providing a region (pick something close to your existing infrastructure), a name for the deployment, and selecting the default organization that was created for you upon account creation. Hit "Confirm" when ready. Standby while our robots get to work generating your deployment. This can take a few seconds.
After the deployment is created and active, you can access the Keycloak Admin console by clicking "Open Console" for that deployment. Open it now to see the console.

At this point, move on to the next step in the tutorial. We'll be coming back to the Admin Console when its time to start connecting our App to the Keycloak instance.

Setting up an OIDC Client

Instructions

Open the Admin UI by clicking Open Console in the Phase Two Dashboard.
Click Clients in the menu.
Click Create client.
Leave Client type set to OpenID Connect.
Enter a Client ID. This ID is an alphanumeric string that is used in OIDC requests and in the Keycloak database to identify the client.
Supply a Name for the client.
Click Next.
Under the Capability Config section, leave the defaults as selected. This can be configured further later.
- Client authentication to On.
- Authorization to Off.
- Standard flow checked. Direct access grants checked. All other items unchecked.
Click Next.
Under Login settings we need to add a redirect URI and Web origin in order. Assuming you are using the example applicaiton:
Valid redirect URI (allows redirect back to application)
```
http://localhost:3000/*
```
Web origins (allows for Token auth call)
```
http://localhost:3000
```
URI and Origin Details
The choice of localhost is arbitrary. If you are using an example application running locally, this will apply. If you are using an app that you actually have deployed somewhere, then you will need to substitute the appropriate URI for that.
Click Save

OIDC Config

We will need values to configure our application. To get these values follow the instructions below.

Click Clients in the menu.
Find the Client you just created and click on it. In the top right click the Action dropdown and select Download adapter config.
Select Keycloak OIDC JSON in the format option. The details section will populate with the details we will need.
- Note the realm, auth-server-url, and resource values.
You also need to copy the Client secret in the Credential tab for the client to use. Once on the Credential tab, click the copy button to copy the key to your clipboard. Save the key somewhere for use later in this tutorial

Adding a Non-Admin User

Instructions

info

It is bad practice to use your Admin user to sign in to an Application.

Since we do not want to use our Admin user for signing into the app we will build, we need to add a another non-admin user.

Open the Admin UI by clicking Open Console in the Phase Two Dashboard.
Click Users in the menu.
Click Add user.
Fill out the information for Email, First name, and Last name. Click Create.
We will now set the password for this user manually. Click Credentials (tab) and click Set Password. Provide a password for this user. For our use case, as a tutorial, you can leave "Temporary" set to "Off".
Click Save and confirm the password by clicking Save password

Install and configure the Django OIDC library

Now that we've installed and configured Keycloak, we need to setup Django to replace the native authentication method provided by the framework. The first task is to install a library that is compatible with Keycloak's OIDC implementation.

The mozilla-django-oidc library provides an easy way to integrate Keycloak (or any OpenID Connect-compliant identity provider) with your Django app. It abstracts many of the complexities of integrating authentication and authorization. Here's how you can set it up:

Install the Package: Install the mozilla-django-oidc package using pip:
```
pip install mozilla-django-oidc
```

Configure Django Settings: Update your Django app's settings.py to include the necessary configurations for mozilla-django-oidc:

INSTALLED_APPS = [
    # ...
    'django.contrib.auth',
    'mozilla_django_oidc',  # Load after django.contrib.auth
    # ...
]

AUTHENTICATION_BACKENDS = (
    'mozilla_django_oidc.auth.OIDCAuthenticationBackend',
    # ...
)

OIDC_RP_CLIENT_ID = 'your-client-id'
OIDC_RP_CLIENT_SECRET = 'your-client-secret'
OIDC_OP_AUTHORIZATION_ENDPOINT = 'https://keycloak-url/auth/realms/your-realm/protocol/openid-connect/auth'
OIDC_OP_TOKEN_ENDPOINT = 'https://keycloak-url/auth/realms/your-realm/protocol/openid-connect/token'
OIDC_OP_USER_ENDPOINT = 'https://keycloak-url/auth/realms/your-realm/protocol/openid-connect/userinfo'
OIDC_OP_JWKS_ENDPOINT = 'https://keycloak-url/auth/realms/your-realm/protocol/openid-connect/certs'
OIDC_RP_SIGN_ALGO = 'RS256'

LOGIN_URL = 'oidc_authentication_init'
LOGOUT_REDIRECT_URL = '/'
LOGIN_REDIRECT_URL = '/'

Replace your-client-id, your-client-secret, and the Keycloak URLs with your actual Keycloak configurations.

Add URLs: Update your Django app's urls.py to include the authentication URLs provided by mozilla-django-oidc:
```
urlpatterns += [
    path('oidc/', include('mozilla_django_oidc.urls')),
]
```

Using it in your app

Protect your views

Use Decorators for Access Control. You can now use the @oidc_protected decorator to protect views that require authentication and potentially specific roles:

from mozilla_django_oidc.decorators import oidc_protected

@oidc_protected
def protected_view(request):
    # Your view logic

Accessing user information

You can access user information after authentication using the request.oidc_user attribute. For example:

def profile_view(request):
    user_info = request.oidc_user.userinfo
    # Access user_info['sub'], user_info['email'], etc.
    # Your view logic

By default, mozilla-django-oidc looks up a Django user matching the email field to the email address returned in the user info data from Keycloak.

If a user logs into your site and doesn’t already have an account, by default, mozilla-django-oidc will create a new Django user account. It will create the User instance filling in the username (hash of the email address) and email fields.

Use Username rather than Email

mozilla-django-oidc defaults to setting up Django users using the email address as the user name from keycloak was required. Fortunately, preferred_username is set up by default in Keycloak as a claim. The claim can used by overriding the OIDCAuthenticationBackend class in mozilla_django_oidc.auth and referring to this in AUTHENTICATION_BACKENDS as below:

# Classes to override default OIDCAuthenticationBackend (Keycloak authentication)
from mozilla_django_oidc.auth import OIDCAuthenticationBackend

class KeycloakOIDCAuthenticationBackend(OIDCAuthenticationBackend):

 def create_user(self, claims):
     """ Overrides Authentication Backend so that Django users are
         created with the keycloak preferred_username.
         If nothing found matching the email, then try the username.
     """
     user = super(KeycloakOIDCAuthenticationBackend, self).create_user(claims)
     user.first_name = claims.get('given_name', '')
     user.last_name = claims.get('family_name', '')
     user.email = claims.get('email')
     user.username = claims.get('preferred_username')
     user.save()
     return user

 def filter_users_by_claims(self, claims):
     """ Return all users matching the specified email.
         If nothing found matching the email, then try the username
     """
     email = claims.get('email')
     preferred_username = claims.get('preferred_username')

     if not email:
         return self.UserModel.objects.none()
     users = self.UserModel.objects.filter(email__iexact=email)

     if len(users) < 1:
         if not preferred_username:
             return self.UserModel.objects.none()
         users = self.UserModel.objects.filter(username__iexact=preferred_username)
     return users

 def update_user(self, user, claims):
     user.first_name = claims.get('given_name', '')
     user.last_name = claims.get('family_name', '')
     user.email = claims.get('email')
     user.username = claims.get('preferred_username')
     user.save()
     return user

In settings.py, overide the new library you have just added in AUTHENTICATION_BACKENDS :

 # mozilla_django_oidc - Keycloak authentication
 "fragalysis.auth.KeycloakOIDCAuthenticationBackend",

Logging out

You can use the @oidc_logout decorator to log the user out of both your app and Keycloak:

from mozilla_django_oidc.decorators import oidc_logout

@oidc_logout
def logout_view(request):
    # Your logout view logic

Add support for Django Rest Framework

Django Rest Framework (DRF) is a flexible toolkit built on top of Django, specifically designed for building RESTful APIs.

If you want DRF to authenticate users based on an OAuth access token provided in the Authorization header, you can use the DRF-specific authentication class which ships with the package.

Add this to your settings:

REST_FRAMEWORK = {
    'DEFAULT_AUTHENTICATION_CLASSES': [
        'mozilla_django_oidc.contrib.drf.OIDCAuthentication',
        'rest_framework.authentication.SessionAuthentication',
        # other authentication classes, if needed
    ],
}

Note that this only takes care of authenticating against an access token, and provides no options to create or renew tokens.

If you’ve created a custom Django OIDCAuthenticationBackend and added that to your AUTHENTICATION_BACKENDS, the DRF class should be smart enough to figure that out. Alternatively, you can manually set the OIDC backend to use:

OIDC_DRF_AUTH_BACKEND = 'mozilla_django_oidc.auth.OIDCAuthenticationBackend'

Learning more

Securing Next.js Apps with Keycloak

August 14, 2023 · 4 min read

Phase Two

info

If you just want to skip to the code, visit the Phase Two Next.js example. We also have a plain React example.

Setting up a Keycloak Instance

Instructions

tip

If you already have a functioning Keycloak instance, you can skip to the next section.

Visit the sign-up page.
Enter an email, use a Github account, or use an existing Google account to register.
Follow the register steps. This will include a sign-in link being sent to your email. Use that for password-less login.
After creating an account, a realm is automatically created for you with all of the Phase Two enhancements. You need to create a Deployment in the Shared Phase Two infrastructure in order to gain access to the realm. Without a deployment created, the Create Shared Deployment modal will automatically pop up.
Create a Shared Deployment by providing a region (pick something close to your existing infrastructure), a name for the deployment, and selecting the default organization that was created for you upon account creation. Hit "Confirm" when ready. Standby while our robots get to work generating your deployment. This can take a few seconds.
After the deployment is created and active, you can access the Keycloak Admin console by clicking "Open Console" for that deployment. Open it now to see the console.

At this point, move on to the next step in the tutorial. We'll be coming back to the Admin Console when its time to start connecting our App to the Keycloak instance.

Setting up an OIDC Client

Instructions

Open the Admin UI by clicking Open Console in the Phase Two Dashboard.
Click Clients in the menu.
Click Create client.
Leave Client type set to OpenID Connect.
Enter a Client ID. This ID is an alphanumeric string that is used in OIDC requests and in the Keycloak database to identify the client.
Supply a Name for the client.
Click Next.
Under the Capability Config section, leave the defaults as selected. This can be configured further later.
- Client authentication to On.
- Authorization to Off.
- Standard flow checked. Direct access grants checked. All other items unchecked.
Click Next.
Under Login settings we need to add a redirect URI and Web origin in order. Assuming you are using the example applicaiton:
Valid redirect URI (allows redirect back to application)
```
http://localhost:3000/*
```
Web origins (allows for Token auth call)
```
http://localhost:3000
```
URI and Origin Details
The choice of localhost is arbitrary. If you are using an example application running locally, this will apply. If you are using an app that you actually have deployed somewhere, then you will need to substitute the appropriate URI for that.
Click Save

OIDC Config

We will need values to configure our application. To get these values follow the instructions below.

Click Clients in the menu.
Find the Client you just created and click on it. In the top right click the Action dropdown and select Download adapter config.
Select Keycloak OIDC JSON in the format option. The details section will populate with the details we will need.
- Note the realm, auth-server-url, and resource values.
You also need to copy the Client secret in the Credential tab for the client to use. Once on the Credential tab, click the copy button to copy the key to your clipboard. Save the key somewhere for use later in this tutorial

Adding a Non-Admin User

Instructions

info

It is bad practice to use your Admin user to sign in to an Application.

Since we do not want to use our Admin user for signing into the app we will build, we need to add a another non-admin user.

Open the Admin UI by clicking Open Console in the Phase Two Dashboard.
Click Users in the menu.
Click Add user.
Fill out the information for Email, First name, and Last name. Click Create.
We will now set the password for this user manually. Click Credentials (tab) and click Set Password. Provide a password for this user. For our use case, as a tutorial, you can leave "Temporary" set to "Off".
Click Save and confirm the password by clicking Save password

Setting up a Next.js Project

info

We will use the Phase Two Next.js example code here, but the logic could easily be applied to any existing application.

This example uses Next.js 13 and splits server and client components accordingly.

Clone the Phase Two example repo.
Open the Next.js folder within /frameworks/nextjs.
Run npm install and then npm run dev. This example leverages NextAuth.js to provide hook and HOC support.
NextAuth.js configures an API route that is uses for the Authentication of the Client. It generates the routes automatically for you. These are added to Next.js in the api/auth/[...nextauth]/route.ts file.
Open the src/lib/auth.ts file. This is a server only file. We will be updating a few values from the prior section where we set up our OIDC client. Taking the values from the OIDC Client Config section, set those values in the code. While it is recommended to use Environment variables for the secret, for the purpose of this tutorial, paste in the Client secret from the OIDC client creation section for the value of clientSecret
```
const authServerUrl = "https://euc1.auth.ac/auth/";
const realm = "shared-deployment-001";
const clientId = "reg-example-1";
const clientSecret = "CLIENT_SECRET"; // Paste "Client secret" here. Use Environment variables in prod
```
Those are used to popluate the AuthOptions config for the KeycloakProvider:
```
export const AuthOptions: NextAuthOptions = {
  providers: [
    KeycloakProvider({
      clientId,
      clientSecret,
      issuer: `${authServerUrl}realms/${realm}`,
    }),
  ],
};
```
The config is then provided to the AuthProvider in the /src/app/layout.tsx file. Next.js uses this file to generate an HTML view for this page.
```
import { NextAuthProvider as AuthProvider } from "./providers";
...
<AuthProvider {...oidcConfig}>
  <App />
</AuthProvider>
```
At this point our entire application will be able to access all information and methods needed to perform authentication. View the providers.tsx file for additional information about how the SessionProvider is used. The SessionProvider enables use of Hooks to derive the authenticated state. View user.component.tsx for exactly how the code is authenticating your user. The sections rendering the "Log in" and "Log out" buttons are conditional areas based on the authenticated context. The buttons invoke functions provided by NextAuth.
The logic using the hook to conditionally determine the Authenticated state, can be used to secure routes, components, and more.
Open localhost:3000. You will see the Phase Two example landing page. You current state should be "Not authenticated". Click Log In. This will redirect you to your login page.
info
Use the non-admin user created in the previous section to sign in.
Enter the credentials of the non-admin user you created. Click Submit. You will then be redirected to the application. The Phase Two example landing page now loads your "Authenticated" state, displaying your user's email and their Token.
After your first log in, click Log out. Then click Log in again. Notice how this time you will not be redirected to sign in as your state is already in the browser. Neat! If you clear the browser state for that tab, then you will have to be redirected away to sign-in again.

Learning more

Instant User Management, SSO, and Secure Pages for ReactJS

August 2, 2023 · 3 min read

Phase Two

info

If you just want to skip to the code, visit the Phase Two ReactJS example.

Setting up a Keycloak Instance

Instructions

tip

If you already have a functioning Keycloak instance, you can skip to the next section.

Visit the sign-up page.
Enter an email, use a Github account, or use an existing Google account to register.
Follow the register steps. This will include a sign-in link being sent to your email. Use that for password-less login.
After creating an account, a realm is automatically created for you with all of the Phase Two enhancements. You need to create a Deployment in the Shared Phase Two infrastructure in order to gain access to the realm. Without a deployment created, the Create Shared Deployment modal will automatically pop up.
Create a Shared Deployment by providing a region (pick something close to your existing infrastructure), a name for the deployment, and selecting the default organization that was created for you upon account creation. Hit "Confirm" when ready. Standby while our robots get to work generating your deployment. This can take a few seconds.
After the deployment is created and active, you can access the Keycloak Admin console by clicking "Open Console" for that deployment. Open it now to see the console.

At this point, move on to the next step in the tutorial. We'll be coming back to the Admin Console when its time to start connecting our App to the Keycloak instance.

Setting up an OIDC Client

Instructions

Open the Admin UI by clicking Open Console in the Phase Two Dashboard.
Click Clients in the menu.
Click Create client.
Leave Client type set to OpenID Connect.
Enter a Client ID. This ID is an alphanumeric string that is used in OIDC requests and in the Keycloak database to identify the client.
Supply a Name for the client.
Click Next.
Under the Capability Config section, leave the defaults as selected. This can be configured further later.
- Client authentication to Off.
- Authorization to Off.
- Standard flow checked. Direct access grants checked. All other items unchecked.
Click Next.
Under Login settings we need to add a redirect URI and Web origin in order. Assuming you are using the example applicaiton:
Valid redirect URI (allows redirect back to application)
```
http://localhost:3000/*
```
Web origins (allows for Token auth call)
```
http://localhost:3000
```
URI and Origin Details
The choice of localhost is arbitrary. If you are using an example application running locally, this will apply. If you are using an app that you actually have deployed somewhere, then you will need to substitute the appropriate URI for that.
Click Save

OIDC Config

We will need values to configure our application. To get these values follow the instructions below.

Click Clients in the menu.
Find the Client you just created and click on it. In the top right click the Action dropdown and select Download adapter config.
Select Keycloak OIDC JSON in the format option. The details section will populate with the details we will need.
- Note the realm, auth-server-url, and resource values.

Adding a Non-Admin User

Instructions

info

It is bad practice to use your Admin user to sign in to an Application.

Since we do not want to use our Admin user for signing into the app we will build, we need to add a another non-admin user.

Open the Admin UI by clicking Open Console in the Phase Two Dashboard.
Click Users in the menu.
Click Add user.
Fill out the information for Email, First name, and Last name. Click Create.
We will now set the password for this user manually. Click Credentials (tab) and click Set Password. Provide a password for this user. For our use case, as a tutorial, you can leave "Temporary" set to "Off".
Click Save and confirm the password by clicking Save password

Setting up a ReactJS Project

info

We will use the Phase Two ReactJS example code here, but the logic could easily be applied to any existing application.

Clone the Phase Two example repo.
Open the ReactJS folder within /frameworks/reactjs.
Run npm install and then npm start. This example leverages react-oidc-context (which uses oidc-client-ts) to provide hook and HOC support.
Open the index.tsx file. We will be updating a few values from the prior section where we set up our OIDC client. Taking the values from the OIDC Client Config section, set those values in the code.
```
const authServerUrl = "https://euc1.auth.ac/auth/";
const realm = "shared-deployment-001";
const client = "reg-example-1";
```
Those are used to popluate the OIDC config
```
const oidcConfig = {
  authority: `${authServerUrl}realms/${realm}`,
  client_id: client,
  redirect_uri: "http://localhost:3000/authenticated",
  onSigninCallback: (args: any) =>
    window.history.replaceState(
      {},
      document.title,
      window.location.pathname
    ),
};
```
The config is then provided to the AuthProvider.
```
<AuthProvider {...oidcConfig}>
  <App />
</AuthProvider>
```
At this point our entire applicationw will be able to access all information and methods needed to perform authentication. View Auth.tsx for exactly how the code is authenticating your user. The sections rendering the "Log in" and "Log out" buttons are conditional areas based on the authenticated context.
The logic using the hook to conditionally determine the Authenticated state, can be used to secure routes, components, and more.
Open localhost:3000. You will see the Phase Two example landing page. You current state should be "Not authenticated". Click Log In. This will redirect you to your login page.
info
Use the non-admin user created in the previous section to sign in.
Enter the credentials of the non-admin user you created. Click Submit. You will then be redirected to the application. The Phase Two example landing page now loads your "Authenticated" state, displaying your user's email and their Token.
After your first log in, click Log out. Then click Log in again. Notice how this time you will not be redirected to sign in as your state is already in the browser. Neat! If you clear the browser state for that tab, then you will have to be redirected away to sign-in again.

Setting up a Keycloak Instance​

Setting up an OIDC Client​

OIDC Config​

Adding a Non-Admin User​

Setting up a Remix Project​

Learning more​

Setting up a Keycloak Instance​

Setting up an OIDC Client​

OIDC Config​

Adding a Non-Admin User​

Setting up a Vue.js Project​

Learning more​

Setting up a Keycloak Instance​

Setting up an OIDC Client​

OIDC Config​

Adding a Non-Admin User​

Setting up a Nuxt Project​

Using keycloak-js​

Using oidc-client​

Learning more​

Setting up a Django Project​

Quick Start​

Setting up a Keycloak Instance​

Setting up an OIDC Client​

OIDC Config​

Adding a Non-Admin User​

Install and configure the Django OIDC library​

Using it in your app​

Protect your views​

Accessing user information​

Use Username rather than Email​

Logging out​

Add support for Django Rest Framework​

Learning more​

Setting up a Keycloak Instance​

Setting up an OIDC Client​

OIDC Config​

Adding a Non-Admin User​

Setting up a Next.js Project​

Learning more​

Setting up a Keycloak Instance​

Setting up an OIDC Client​

OIDC Config​

Adding a Non-Admin User​

Setting up a ReactJS Project​

Learning more​

Setting up a Keycloak Instance

Setting up an OIDC Client

OIDC Config

Adding a Non-Admin User

Setting up a Remix Project

Learning more

Setting up a Keycloak Instance

Setting up an OIDC Client

OIDC Config

Adding a Non-Admin User

Setting up a Vue.js Project

Learning more

Setting up a Keycloak Instance

Setting up an OIDC Client

OIDC Config

Adding a Non-Admin User

Setting up a Nuxt Project

Using `keycloak-js`

Using `oidc-client`

Learning more

Setting up a Django Project

Quick Start

Setting up a Keycloak Instance

Setting up an OIDC Client

OIDC Config

Adding a Non-Admin User

Install and configure the Django OIDC library

Using it in your app

Protect your views

Accessing user information

Use Username rather than Email

Logging out

Add support for Django Rest Framework

Learning more

Setting up a Keycloak Instance

Setting up an OIDC Client

OIDC Config

Adding a Non-Admin User

Setting up a Next.js Project

Learning more

Setting up a Keycloak Instance

Setting up an OIDC Client

OIDC Config

Adding a Non-Admin User

Setting up a ReactJS Project

Learning more