The GitHub OAuth Flow For Idio Web Server.
npm install @idio/github
@idio/github is The GitHub OAuth Flow For the Idio Web Server.
``sh`
yarn add @idio/github
- Table Of Contents
- API
- githubOAuth(app, config): void
* GithubOAuthConfig
* GithubEmail
- Copyright
The package is available by importing its default function:
`js`
import github from '@idio/github'
githubOAuth(
config: !GithubOAuthConfig,
): void - app* _goa.Application: The Goa/Koa Application.
- config* !GithubOAuthConfig: Options for the middleware.
__GithubOAuthConfig__: Options for the program.
| Name | Type & Description | Default |
|---|---|---|
| client_id* | string | - |
The app's client id. | ||
| client_secret* | string | - |
The app's client secret. | ||
| path | string | /auth/github |
The server path to start the login flaw at. | ||
| redirectPath | string | - |
The redirect path (must start with /). If not specified, ${path}/redirect will be used. | ||
| scope | string | - |
The scope to ask permissions for. No scope by default. | ||
| session | method.">!_goa.Middleware | - |
The configured session middleware in case the session property is not globally available on the context. | ||
| finish | (ctx: Context, token: string, scope: string, user: !GithubUser, next: function()) => !Promise | |
The function to complete the authentication that receives the token and the data about the user, such as name and id. The default function redirects to /.ctx* Context: The app context.token* string: The exchanged token.scope* string: The scopes which the user authorised the app to access.user* !GithubUser: The scopes which the user authorised the app to access.next* function(): Calls next middleware. | ||
| error | (ctx: !Context, error: string, description: string, next: function()) => !Promise | |
The function to be called in case of error. If not specified, the middleware will throw an internal server error. ctx* !Context: The app context.error* string: The error type.description* string: The explanation of the error.next* function(): Calls next middleware. | ||
`jsx
import github from '..'
import idio from '@idio/idio'
const Server = async () => {
const { url, app, router, middleware: {
session,
} } = await idio({
session: {
keys: [process.env.SESSION_KEY],
},
})
router.get('/', session, (ctx) => {
ctx.body = render(
github(app, {
session,
client_id: process.env.CLIENT_ID,
client_secret: process.env.CLIENT_SECRET,
scope: 'user:email',
error(ctx, error) {
ctx.redirect(/?error=${error})`
},
path: '/github',
async finish(ctx, token, scope, user, next) {
console.log(user.name, user.login, user.company)
ctx.session.user = user.login
ctx.session.manuallyCommit()
ctx.redirect('/')
},
})
return { app, url }
}`
[+] CLIENT_ID [+] CLIENT_SECRET [+] SESSION_KEY
http://localhost:5000
{
body: 'Redirecting to https://www.github.com/login/oauth/authorize?client_id=f0a8762e7329780e85de&redirect_uri=http%3A%2F%2Flocalhost%3A5000%2Fgithub%2Fredirect&state=8275&scope=user%3Aemail.',
headers: {
'set-cookie': [
'koa:sess=eyJnaXRoaWItc3RhdGUiOjgyNzUsIl9leHBpcmUiOjE1ODI4OTY0NTk1OTIsIl9tYXhBZ2UiOjg2NDAwMDAwfQ==; path=/; expires=Fri, 28 Feb 2020 13:27:39 GMT; httponly',
'koa:sess.sig=mPZuFR0kFz8XFkQRJeuTm3VnMfw; path=/; expires=Fri, 28 Feb 2020 13:27:39 GMT; httponly'
],
location: 'https://www.github.com/login/oauth/authorize?client_id=f0a8762e7329780e85de&redirect_uri=http%3A%2F%2Flocalhost%3A5000%2Fgithub%2Fredirect&state=8275&scope=user%3Aemail',
'content-type': 'text/html; charset=utf-8',
'content-length': '391',
date: 'Thu, 27 Feb 2020 13:27:39 GMT',
connection: 'close'
},
statusCode: 302,
statusMessage: 'Found'
}
> Redirect to Dialog https://www.github.com/login/oauth/authorize?client_id=f0a8762e7329780e85de&redirect_uri=http%3A%2F%2Flocalhost%3A5000%2Fgithub%2Fredirect&state=8275&scope=user%3Aemail
`
If authorisation was successful, the server will make a request to GitHub API at /user path with the token, to get user's public info. This information can then be accessed in the finish function passed in the config.
If the user:email scope was requested, emails returned from the /user/emails API path will also be populated in the emails field. If the user's main email is private, it won't be visible in the email field, so that this scope should be requested if the email address needs to be collected.
__GithubEmail__
| Name | Type & Description |
|---|---|
| email* | string |
The email address. | |
| verified* | boolean |
Whether the email was verified. | |
| primary* | boolean |
Whether the email is primary. | |
| visibility* | string |
Either public or private. |
__GithubUser__: Public user information
| Name | Type & Description |
|---|---|
| email* | ?string |
Publicly visible email address. octocat@github.com or null. | |
| emails* | !Array<!GithubEmail> |
All email addresses accessible if the user:email scope was requested. | |
| login* | string |
octocat | |
| id* | number |
1 | |
| node_id* | string |
MDQ6VXNlcjE= | |
| avatar_url* | string |
https://github.com/images/error/octocat_happy.gif | |
| gravatar_id* | string |
| |
| url* | string |
https://api.github.com/users/octocat | |
| html_url* | string |
https://github.com/octocat | |
| followers_url* | string |
https://api.github.com/users/octocat/followers | |
| following_url* | string |
https://api.github.com/users/octocat/following{/other_user} | |
| gists_url* | string |
https://api.github.com/users/octocat/gists{/gist_id} | |
| starred_url* | string |
https://api.github.com/users/octocat/starred{/owner}{/repo} | |
| subscriptions_url* | string |
https://api.github.com/users/octocat/subscriptions | |
| organizations_url* | string |
https://api.github.com/users/octocat/orgs | |
| repos_url* | string |
https://api.github.com/users/octocat/repos | |
| events_url* | string |
https://api.github.com/users/octocat/events{/privacy} | |
| received_events_url* | string |
https://api.github.com/users/octocat/received_events | |
| type* | string |
User | |
| site_admin* | boolean |
false | |
| name* | string |
monalisa octocat | |
| company* | string |
GitHub | |
| blog* | string |
https://github.com/blog | |
| location* | string |
San Francisco | |
| hireable* | boolean |
false | |
| bio* | string |
There once was... | |
| public_repos* | number |
2 | |
| public_gists* | number |
1 | |
| followers* | number |
20 | |
| following* | number |
0 | |
| created_at* | string |
2008-01-14T04:33:35Z | |
| updated_at* | string |
2008-01-14T04:33:35Z |
A custom implementation of the finish function can be provided, only that session must be manually committed after being set.
`js``
/**
* @param {!_idio.Context} ctx
* @param {string} token
* @param {string} scope
* @param {!_idio.GithubUser} user
*/
export const defaultFinish = async (ctx, token, scope, user, next) => {
ctx.session['token'] = token
ctx.session['scope'] = scope
ctx.session['user'] = user
await ctx.session.manuallyCommit()
ctx.redirect('/')
}
GNU Affero General Public License v3.0
Affero GPL means that you're not allowed to use this middleware on the web unless you release the source code for your application. This is a restrictive license which has the purpose of defending Open Source work and its creators.
Please refer to the Idio license agreement for more info on dual-licensing. You're allowed to use this middleware without disclosing the source code if you sign up on the neoluddite.dev package reward scheme.
alt="Art Deco"> | © Art Deco™ for Idio 2020 |
|---|