web/docs/auth/social-auth/github.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 { CardLink } from '@site/src/components/CardLink'; import GithubData from '../entities/_github-data.md'; import AccessingUserDataNote from '../_accessing-user-data-note.md'; import SocialLoginClientPages from './_social-login-client-pages.md';
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.
Enabling GitHub Authentication comes down to a series of steps:
User entity.Let's start by properly configuring the Auth object:
import { app } from "@wasp.sh/spec"
export default app({
name: "myApp",
wasp: { version: "{latestWaspVersion}" },
title: "My App",
auth: {
// highlight-next-line
// 1. Specify the User entity (we'll define it next)
// highlight-next-line
userEntity: "User",
methods: {
// highlight-next-line
// 2. Enable GitHub Auth
// highlight-next-line
gitHub: {}
},
onAuthFailedRedirectTo: "/login"
},
// ...
})
Let's now define the auth.userEntity entity in the schema.prisma file:
// 3. Define the user entity
model User {
// highlight-next-line
id Int @id @default(autoincrement())
// Add your own fields below
// ...
}
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:
Create a GitHub account if you do not already have one: https://github.com.
Create and configure a new GitHub App: https://github.com/settings/apps.
We have to fill out App name and Homepage URL fields. Additionally we will add our authorization Callback URLs:
http://localhost:3001/auth/github/callback.https://your-server-url.com/auth/github/callback.We will turn off the Active checkbox under the Webhook title, and then we can click Create GitHub App.
Finally, we can click Generate a new client secret button and then copy both Client ID and Client secret.
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
Let's define the necessary authentication Routes and Pages.
Add the following code to your main.wasp.ts file:
import { app, page, route } from "@wasp.sh/spec"
import { LoginPage } from "./src/pages/auth" with { type: "ref" }
export default app({
// ...
spec: [
route("LoginRoute", "/login", page(LoginPage)),
],
})
We'll define the React components for these pages in the src/pages/auth.{jsx,tsx} file below.
Yay, we've successfully set up 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.
Add gitHub: {} to the auth.methods object to use it with default settings.
import { app } from "@wasp.sh/spec"
export default app({
name: "myApp",
wasp: { version: "{latestWaspVersion}" },
title: "My App",
auth: {
userEntity: "User",
methods: {
// highlight-next-line
gitHub: {}
},
onAuthFailedRedirectTo: "/login"
},
// ...
})
We are using GitHub's API and its /user and /user/emails endpoints to get the user data.
:::info We combine the data from the two endpoints
You'll find the emails in the emails property in the object that you receive in userSignupFields.
This is because we combine the data from the /user and /user/emails endpoints if the user or user:email scope is requested.
:::
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.
import { app } from "@wasp.sh/spec"
import { getConfig, userSignupFields } from "./src/auth/github" with { type: "ref" }
export default app({
name: "myApp",
wasp: { version: "{latestWaspVersion}" },
title: "My App",
auth: {
userEntity: "User",
methods: {
gitHub: {
// highlight-next-line
configFn: getConfig,
// highlight-next-line
userSignupFields
}
},
onAuthFailedRedirectTo: "/login"
},
// ...
})
model User {
id Int @id @default(autoincrement())
username String @unique
displayName String
}
// ...
import { defineUserSignupFields } from "wasp/server/auth"
export const userSignupFields = defineUserSignupFields({
username: () => "hardcoded-username",
displayName: (data: any) => data.profile.name,
})
export function getConfig() {
return {
scopes: ["user"],
}
}
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:
<CardLink to="../../api/@wasp.sh/spec/interfaces/SocialAuthConfig" kind="api" title="SocialAuthConfig" description="All the options for the gitHub auth method." />
For the provider-specific behavior of the configFn and userSignupFields functions, check the Overrides section. For behavior common to all providers, check the Social Auth Overview.