web/versioned_docs/version-0.13/auth/social-auth/keycloak.md
import useBaseUrl from '@docusaurus/useBaseUrl'; import DefaultBehaviour from './_default-behaviour.md'; import OverrideIntro from './_override-intro.md'; import OverrideExampleIntro from './_override-example-intro.md'; import UsingAuthNote from './_using-auth-note.md'; import WaspFileStructureNote from './_wasp-file-structure-note.md'; import GetUserFieldsType from './_getuserfields-type.md'; import ApiReferenceIntro from './_api-reference-intro.md'; import UserSignupFieldsExplainer from '../_user-signup-fields-explainer.md';
Wasp supports Keycloak Authentication out of the box.
Keycloak is an open-source identity and access management solution for modern applications and services. Keycloak provides both SAML and OpenID protocol solutions. It also has a very flexible and powerful administration UI.
Let's walk through enabling Keycloak authentication, explain some of the default settings, and show how to override them.
Enabling Keycloak Authentication comes down to a series of steps:
User entity.Let's start by properly configuring the Auth object:
<Tabs groupId="js-ts"> <TabItem value="js" label="JavaScript"> ```wasp title="main.wasp" app myApp { wasp: { version: "^0.13.0" }, title: "My App", auth: { // 1. Specify the User entity (we'll define it next) // highlight-next-line userEntity: User, methods: { // 2. Enable Keycloak Auth // highlight-next-line keycloak: {} }, onAuthFailedRedirectTo: "/login" }, } ``` </TabItem> <TabItem value="ts" label="TypeScript"> ```wasp title="main.wasp" app myApp { wasp: { version: "^0.13.0" }, title: "My App", auth: { // 1. Specify the User entity (we'll define it next) // highlight-next-line userEntity: User, methods: { // 2. Enable Keycloak Auth // highlight-next-line keycloak: {} }, onAuthFailedRedirectTo: "/login" }, } ``` </TabItem> </Tabs>The userEntity is explained in the social auth overview.
Let's now define the app.auth.userEntity entity:
http://localhost:3001/auth/keycloak/callback for local development.https://my-server-url.com/auth/keycloak/callback.Add these environment variables to the .env.server file at the root of your project (take their values from the previous step):
KEYCLOAK_CLIENT_ID=your-keycloak-client-id
KEYCLOAK_CLIENT_SECRET=your-keycloak-client-secret
KEYCLOAK_REALM_URL=https://your-keycloak-url.com/realms/master
We assumed in the KEYCLOAK_REALM_URL env variable that you are using the master realm. If you are using a different realm, replace master with your realm name.
Let's define the necessary authentication Routes and Pages.
Add the following code to your main.wasp file:
// 6. Define the routes
route LoginRoute { path: "/login", to: LoginPage }
page LoginPage {
component: import { Login } from "@src/pages/auth.jsx"
}
```
// 6. Define the routes
route LoginRoute { path: "/login", to: LoginPage }
page LoginPage {
component: import { Login } from "@src/pages/auth.tsx"
}
```
We'll define the React components for these pages in the src/pages/auth.{jsx,tsx} file below.
:::info We are using Tailwind CSS to style the pages. Read more about how to add it here. :::
Let's now create an auth.{jsx,tsx} file in the src/pages.
It should have the following code:
export function Login() {
return (
<Layout>
<LoginForm />
</Layout>
)
}
// A layout component to center the content
export function Layout({ children }) {
return (
<div className="w-full h-full bg-white">
<div className="min-w-full min-h-[75vh] flex items-center justify-center">
<div className="w-full h-full max-w-sm p-5 bg-white">
<div>{children}</div>
</div>
</div>
</div>
)
}
```
export function Login() {
return (
<Layout>
<LoginForm />
</Layout>
)
}
// A layout component to center the content
export function Layout({ children }: { children: React.ReactNode }) {
return (
<div className="w-full h-full bg-white">
<div className="min-w-full min-h-[75vh] flex items-center justify-center">
<div className="w-full h-full max-w-sm p-5 bg-white">
<div>{children}</div>
</div>
</div>
</div>
)
}
```
:::info Auth UI Our pages use an automatically generated Auth UI component. Read more about Auth UI components here. :::
Yay, we've successfully set up Keycloak Auth!
Running wasp db migrate-dev and wasp start should now give you a working app with authentication.
To see how to protect specific pages (i.e., hide them from non-authenticated users), read the docs on using auth.
Add keycloak: {} to the auth.methods dictionary to use it with default settings:
We are using Keycloak's API and its /userinfo endpoint to fetch the user's data.
{
sub: '5adba8fc-3ea6-445a-a379-13f0bb0b6969',
email_verified: true,
name: 'Test User',
preferred_username: 'test',
given_name: 'Test',
family_name: 'User',
email: '[email protected]'
}
The fields you receive will depend on the scopes you requested. The default scope is set to profile only. If you want to get the user's email, you need to specify the email scope in the configFn function.
entity User {=psl
id Int @id @default(autoincrement())
username String @unique
displayName String
psl=}
// ...
```
```js title="src/auth/keycloak.js"
export const userSignupFields = {
username: () => "hardcoded-username",
displayName: (data) => data.profile.name,
}
export function getConfig() {
return {
scopes: ['profile', 'email'],
}
}
```
entity User {=psl
id Int @id @default(autoincrement())
username String @unique
displayName String
psl=}
// ...
```
```ts title="src/auth/keycloak.ts"
import { defineUserSignupFields } from 'wasp/server/auth'
export const userSignupFields = defineUserSignupFields({
username: () => "hardcoded-username",
displayName: (data: any) => data.profile.name,
})
export function getConfig() {
return {
scopes: ['profile', 'email'],
}
}
```
<GetUserFieldsType />
The keycloak dict has the following properties:
configFn: ExtImportThis function must return an object with the scopes for the OAuth provider.
<Tabs groupId="js-ts"> <TabItem value="js" label="JavaScript"> ```js title="src/auth/keycloak.js" export function getConfig() { return { scopes: ['profile', 'email'], } } ``` </TabItem> <TabItem value="ts" label="TypeScript"> ```ts title="src/auth/keycloak.ts" export function getConfig() { return { scopes: ['profile', 'email'], } } ``` </TabItem> </Tabs>userSignupFields: ExtImportRead more about the userSignupFields function here.