Version: 0.16.0

Keycloak

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.

Setting up Keycloak Auth

Enabling Keycloak Authentication comes down to a series of steps:

Enabling Keycloak authentication in the Wasp file.
Adding the User entity.
Creating a Keycloak client.
Adding the necessary Routes and Pages
Using Auth UI components in our Pages.

Here's a skeleton of how our main.wasp should look like after we're done:

main.wasp

// Configuring the social authentication
appmyApp{
auth: { ... }
}

// Defining routes and pages
routeLoginRoute{ ... }
pageLoginPage{ ... }

1. Adding Keycloak Auth to Your Wasp File

Let's start by properly configuring the Auth object:

JavaScript
TypeScript

main.wasp

appmyApp{
wasp: {
version: "^0.19.0"
},
title: "My App",
auth: {
// 1. Specify the User entity (we'll define it next)
userEntity: User,
methods: {
// 2. Enable Keycloak Auth
keycloak: {}
},
onAuthFailedRedirectTo: "/login"
},
}

main.wasp

appmyApp{
wasp: {
version: "^0.19.0"
},
title: "My App",
auth: {
// 1. Specify the User entity (we'll define it next)
userEntity: User,
methods: {
// 2. Enable Keycloak Auth
keycloak: {}
},
onAuthFailedRedirectTo: "/login"
},
}

The userEntity is explained in the social auth overview.

2. Adding the User Entity

Let's now define the app.auth.userEntity entity in the schema.prisma file:

JavaScript
TypeScript

schema.prisma

// 3. Define the user entity
model User{
 id Int@id@default(autoincrement())
// Add your own fields below
// ...
}

schema.prisma

// 3. Define the user entity
model User{
 id Int@id@default(autoincrement())
// Add your own fields below
// ...
}

3. Creating a Keycloak Client

Log into your Keycloak admin console.
Under Clients, click on Create Client.

[画像:Keycloak Screenshot 1]

Fill in the Client ID and choose a name for the client.

[画像:Keycloak Screenshot 2]

In the next step, enable Client Authentication.

[画像:Keycloak Screenshot 3]

Under Valid Redirect URIs, add http://localhost:3001/auth/keycloak/callback for local development.

[画像:Keycloak Screenshot 4]

Once you know on which URL(s) your API server will be deployed, also add those URL(s).
For example: https://my-server-url.com/auth/keycloak/callback.

Click Save.
In the Credentials tab, copy the Client Secret value, which we'll use in the next step.

[画像:Keycloak Screenshot 5]

4. Adding Environment Variables

Add these environment variables to the .env.server file at the root of your project (take their values from the previous step):

.env.server

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.

5. Adding the Necessary Routes and Pages

Let's define the necessary authentication Routes and Pages.

Add the following code to your main.wasp file:

JavaScript
TypeScript

main.wasp

// ...

routeLoginRoute{path: "/login",to: LoginPage}
pageLoginPage{
component: import{Login}from"@src/pages/auth.jsx"
}

main.wasp

// ...

routeLoginRoute{path: "/login",to: LoginPage}
pageLoginPage{
component: import{Login}from"@src/pages/auth.tsx"
}

We'll define the React components for these pages in the src/pages/auth.tsx file below.

6. Create the Client Pages

info

We are using Tailwind CSS to style the pages. Read more about how to add it here.

Let's now create an auth.tsx file in the src/pages. It should have the following code:

JavaScript
TypeScript

src/pages/auth.jsx

import{LoginForm}from'wasp/client/auth'

exportfunctionLogin(){
return(
<Layout>
<LoginForm/>
</Layout>
)
}

// A layout component to center the content
exportfunctionLayout({ children }){
return(
<divclassName="h-full w-full bg-white">
<divclassName="flex min-h-[75vh] min-w-full items-center justify-center">
<divclassName="h-full w-full max-w-sm bg-white p-5">
<div>{children}</div>
</div>
</div>
</div>
)
}

src/pages/auth.tsx

import{LoginForm}from'wasp/client/auth'

exportfunctionLogin(){
return(
<Layout>
<LoginForm/>
</Layout>
)
}

// A layout component to center the content
exportfunctionLayout({ children }:{ children:React.ReactNode}){
return(
<divclassName="h-full w-full bg-white">
<divclassName="flex min-h-[75vh] min-w-full items-center justify-center">
<divclassName="h-full w-full max-w-sm bg-white p-5">
<div>{children}</div>
</div>
</div>
</div>
)
}

Auth UI

Our pages use an automatically generated Auth UI component. Read more about Auth UI components here.

Conclusion

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.

Default Behaviour

Add keycloak: {} to the auth.methods dictionary to use it with default settings:

JavaScript
TypeScript

main.wasp

appmyApp{
wasp: {
version: "^0.19.0"
},
title: "My App",
auth: {
userEntity: User,
methods: {
keycloak: {}
},
onAuthFailedRedirectTo: "/login"
},
}

main.wasp

appmyApp{
wasp: {
version: "^0.19.0"
},
title: "My App",
auth: {
userEntity: User,
methods: {
keycloak: {}
},
onAuthFailedRedirectTo: "/login"
},
}

When a user signs in for the first time, Wasp creates a new user account and links it to the chosen auth provider account for future logins.

Overrides

By default, Wasp doesn't store any information it receives from the social login provider. It only stores the user's ID specific to the provider.

There are two mechanisms used for overriding the default behavior:

userSignupFields
configFn

Let's explore them in more detail.

Data Received From Keycloak

We are using Keycloak's API and its /userinfo endpoint to fetch the user's data.

Keycloak user 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.

For up-to-date info about the data received from Keycloak, please refer to the Keycloak API documentation.

Using the Data Received From Keycloak

When a user logs in using a social login provider, the backend receives some data about the user. Wasp lets you access this data inside the userSignupFields getters.

For example, the User entity can include a displayName field which you can set based on the details received from the provider.

Wasp also lets you customize the configuration of the providers' settings using the configFn function.

Let's use this example to show both fields in action:

JavaScript
TypeScript

main.wasp

appmyApp{
wasp: {
version: "^0.19.0"
},
title: "My App",
auth: {
userEntity: User,
methods: {
keycloak: {
configFn: import{ getConfig }from"@src/auth/keycloak.js",
userSignupFields: import{ userSignupFields }from"@src/auth/keycloak.js"
}
},
onAuthFailedRedirectTo: "/login"
},
}

schema.prisma

model User{
 id Int@id@default(autoincrement())
 username String@unique
 displayName String
}

// ...

src/auth/keycloak.js

exportconst userSignupFields ={
username:()=>'hardcoded-username',
displayName:(data)=> data.profile.name,
}

exportfunctiongetConfig(){
return{
scopes:['profile','email'],
}
}

main.wasp

appmyApp{
wasp: {
version: "^0.19.0"
},
title: "My App",
auth: {
userEntity: User,
methods: {
keycloak: {
configFn: import{ getConfig }from"@src/auth/keycloak.js",
userSignupFields: import{ userSignupFields }from"@src/auth/keycloak.js"
}
},
onAuthFailedRedirectTo: "/login"
},
}

schema.prisma

model User{
 id Int@id@default(autoincrement())
 username String@unique
 displayName String
}

// ...

src/auth/keycloak.ts

import{ defineUserSignupFields }from'wasp/server/auth'

exportconst userSignupFields =defineUserSignupFields({
username:()=>'hardcoded-username',
displayName:(data:any)=> data.profile.name,
})

exportfunctiongetConfig(){
return{
 scopes:['profile','email'],
}
}

Wasp automatically generates the defineUserSignupFields function to help you correctly type your userSignupFields object.

Using Auth

To read more about how to set up the logout button and get access to the logged-in user in both client and server code, read the docs on using auth.

When you receive the user object on the client or the server, you'll be able to access the user's Keycloak ID like this:

const keycloakIdentity = user.identities.keycloak

// Keycloak User ID for example "12345678-1234-1234-1234-123456789012"
keycloakIdentity.id

Read more about accessing the user data in the Accessing User Data section of the docs.

API Reference

Provider-specific behavior comes down to implementing two functions.

configFn
userSignupFields

The reference shows how to define both.

For behavior common to all providers, check the general API Reference.

JavaScript
TypeScript

main.wasp

appmyApp{
wasp: {
version: "^0.19.0"
},
title: "My App",
auth: {
userEntity: User,
methods: {
keycloak: {
configFn: import{ getConfig }from"@src/auth/keycloak.js",
userSignupFields: import{ userSignupFields }from"@src/auth/keycloak.js"
}
},
onAuthFailedRedirectTo: "/login"
},
}

main.wasp

appmyApp{
wasp: {
version: "^0.19.0"
},
title: "My App",
auth: {
userEntity: User,
methods: {
keycloak: {
configFn: import{ getConfig }from"@src/auth/keycloak.js",
userSignupFields: import{ userSignupFields }from"@src/auth/keycloak.js"
}
},
onAuthFailedRedirectTo: "/login"
},
}

The keycloak dict has the following properties:

configFn: ExtImport

This function must return an object with the scopes for the OAuth provider.
- JavaScript
- TypeScript
src/auth/keycloak.js
exportfunctiongetConfig(){ return{ scopes:['profile','email'], } }
src/auth/keycloak.ts
exportfunctiongetConfig(){ return{ scopes:['profile','email'], } }

`userSignupFields: ExtImport`

userSignupFields defines all the extra fields that need to be set on the User during the sign-up process. For example, if you have address and phone fields on your User entity, you can set them by defining the userSignupFields like this:

JavaScript
TypeScript

src/auth.js

import{ defineUserSignupFields }from'wasp/server/auth'

exportconst userSignupFields =defineUserSignupFields({
address:(data)=>{
if(!data.address){
thrownewError('Address is required')
}
return data.address
},
phone:(data)=> data.phone,
})

src/auth.ts

import{ defineUserSignupFields }from'wasp/server/auth'

exportconst userSignupFields =defineUserSignupFields({
address:(data)=>{
if(!data.address){
thrownewError('Address is required')
}
return data.address
}
phone:(data)=> data.phone,
})

Read more about the userSignupFields function here.

Setting up Keycloak Auth​

1. Adding Keycloak Auth to Your Wasp File​

2. Adding the User Entity​

3. Creating a Keycloak Client​

4. Adding Environment Variables​

5. Adding the Necessary Routes and Pages​

6. Create the Client Pages​

Conclusion​

Default Behaviour​

Overrides​

Data Received From Keycloak​

Using the Data Received From Keycloak​

Using Auth​

API Reference​

configFn: ExtImport​

userSignupFields: ExtImport​

Setting up Keycloak Auth

1. Adding Keycloak Auth to Your Wasp File

2. Adding the User Entity

3. Creating a Keycloak Client

4. Adding Environment Variables

5. Adding the Necessary Routes and Pages

6. Create the Client Pages

Conclusion

Default Behaviour

Overrides

Data Received From Keycloak

Using the Data Received From Keycloak

Using Auth

API Reference

`configFn: ExtImport`

`userSignupFields: ExtImport`