GitHub

Wasp supports GitHub Authentication out of the box. GitHub is a great external auth choice when you're building apps for developers, as most of them already have a GitHub account.

Letting your users log in using their GitHub accounts turns the signup process into a breeze.

Let's walk through enabling GitHub Authentication, explain some of the default settings, and show how to override them.

Setting up GitHub Auth​

Enabling GitHub Authentication comes down to a series of steps:

1. Enabling GitHub authentication in the Wasp file.
2. Adding the User entity.
3. Creating a GitHub OAuth app.
4. Adding the necessary Routes and Pages
5. Using Auth UI components in our Pages.

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

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

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

1. Adding GitHub Auth to Your Wasp File​

Let's start by properly configuring the Auth object:

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

2. Add the User Entity​

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

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

3. Creating a GitHub OAuth App​

To use GitHub as an authentication method, you'll first need to create a GitHub App and provide Wasp with your client key and secret. Here's how you do it:

1. Create a GitHub account if you do not already have one: https://github.com.

2. Create and configure a new GitHub App: https://github.com/settings/apps.

   [画像:GitHub App Screenshot 1]

3. We have to fill out App name and Homepage URL fields. Additionally we will add our authorization Callback URLs:

   • For development, put: http://localhost:3001/auth/github/callback.
   • Once you know your production URL you can add it via the Add Callback URL button, e.g. https://your-server-url.com/auth/github/callback.

   [画像:GitHub App Screenshot 2]

4. We will turn off the Active checkbox under the Webhook title, and then we can click Create GitHub App.

   [画像:GitHub App Screenshot 3]

5. Finally, we can click Generate a new client secret button and then copy both Client ID and Client secret.

   [画像:GitHub App Screenshot 4]

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):

GITHUB_CLIENT_ID=your-github-client-id
GITHUB_CLIENT_SECRET=your-github-client-secret

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:

// ...

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

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

6. Creating the Client Pages​

Let's create a auth.tsx file in the src/pages folder and add the following to it:

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>
);
}

importtype{ReactNode}from"react";
import{LoginForm}from"wasp/client/auth";

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

// A layout component to center the content
exportfunctionLayout({ children }:{ children: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>
);
}

We imported the generated Auth UI components and used them in our pages. Read more about the Auth UI components here.

Conclusion​

Yay, we've successfully set up GitHub Auth! 🎉

[画像:GitHub 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 gitHub: {} to the auth.methods dictionary to use it with default settings.

appmyApp{
wasp: {
version: "^0.20.0"
},
title: "My App",
auth: {
userEntity: User,
methods: {
gitHub: {}
},
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 GitHub​

We are using GitHub's API and its /user and /user/emails endpoints to get the user data.

The data we receive from GitHub on the /user endpoint looks something this:

{
"login":"octocat",
"id":1,
"name":"monalisa octocat",
"avatar_url":"https://github.com/images/error/octocat_happy.gif",
"gravatar_id":""
// ...
}

And the data from the /user/emails endpoint looks something like this:

[
{
"email":"[email protected]",
"verified":true,
"primary":true,
"visibility":"public"
}
]

The fields you receive will depend on the scopes you requested. By default we don't specify any scopes. If you want to get the emails, you need to specify the user or user:email scope in the configFn function.

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

Using the Data Received From GitHub​

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:

appmyApp{
wasp: {
version: "^0.20.0"
},
title: "My App",
auth: {
userEntity: User,
methods: {
gitHub: {
configFn: import{ getConfig }from"@src/auth/github",
userSignupFields: import{ userSignupFields }from"@src/auth/github"
}
},
onAuthFailedRedirectTo: "/login"
},
}

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

// ...

import{ defineUserSignupFields }from"wasp/server/auth";

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

exportfunctiongetConfig(){
return{
scopes:["user"],
};
}

import{ defineUserSignupFields }from"wasp/server/auth";

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

exportfunctiongetConfig(){
return{
 scopes:["user"],
};
}

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 GitHub ID like this:

const githubIdentity = user.identities.github

// GitHub User ID for example "12345678"
githubIdentity.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.

appmyApp{
wasp: {
version: "^0.20.0"
},
title: "My App",
auth: {
userEntity: User,
methods: {
gitHub: {
configFn: import{ getConfig }from"@src/auth/github",
userSignupFields: import{ userSignupFields }from"@src/auth/github"
}
},
onAuthFailedRedirectTo: "/login"
},
}

The gitHub dict has the following properties:

• configFn: ExtImport​

  This function should return an object with the scopes for the OAuth provider.

  • JavaScript
  • TypeScript

  src/auth/github.js

  exportfunctiongetConfig(){
  return{
  scopes:[],
  };
  }
  

• 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,
  });
  

  Read more about the userSignupFields function here.