A plugin for the Kitura-Credentials framework that authenticates using the GitHub web login
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
Sources/CredentialsGitHub
docs
.gitignore
.gitmodules
.jazzy.yaml
.swift-version
.travis.yml
CONTRIBUTING.md
LICENSE
Package.swift
README.md

README.md

Kitura

Docs Build Status - Master macOS Linux Apache 2 Slack Status

Kitura-CredentialsGitHub

Plugin for the Credentials framework that authenticate using GitHub

Summary

Plugin for Kitura-Credentials framework that authenticates using the GitHub web login with OAuth2 API.

Table of Contents

Swift version

The latest version of Kitura-CredentialsGitHub requires Swift 4.0 or newer. You can download this version of the Swift binaries by following this link. Compatibility with other Swift versions is not guaranteed.

Example of GitHub web login

This guide assumes basic knowledge of Kitura app routing.

First, set up the session middleware:

import KituraSession

router.all(middleware: Session(secret: "Very very secret..."))

Create an instance of CredentialsGitHub plugin and register it with Credentials framework:

import Credentials
import CredentialsGitHub

let credentials = Credentials()
let gitCredentials = CredentialsGitHub(clientId: gitClientId, clientSecret: gitClientSecret, callbackUrl: serverUrl + "/login/github/callback", userAgent: "my-kitura-app", options: ["scopes": ["user:email"]])
credentials.register(gitCredentials)

Where:

  • gitClientId is the Client ID of your app in your GitHub Developer application settings
  • gitClientSecret is the Client Secret of your app in your GitHub Developer application settings
  • callbackUrl is used to tell the GitHub web login page where the user's browser should be redirected when the login is successful. It should be a URL handled by the server you are writing.
  • userAgent is an optional argument that passes along a User-Agent of your choice on API calls against GitHub. By default, Kitura-CredentialsGitHub is set as the User-Agent. User-Agent is required when invoking GitHub APIs.
  • options is an optional dictionary ([String: Any]); the allowable options are listed in CredentialsGitHubOptions

Next, specify where to redirect non-authenticated requests:

credentials.options["failureRedirect"] = "/login/github"

Connect credentials middleware to handle requests to a protected path on the server, such as /private:

router.all("/private", middleware: credentials)
router.get("/private/data", handler: { request, response, next in
  ...  
  next()
})

And call authenticate to login with GitHub and to handle the redirect (callback) from the GitHub login web page after a successful login:

router.get("/login/github", handler: credentials.authenticate(gitCredentials.name))

router.get("/login/github/callback", handler: credentials.authenticate(gitCredentials.name))

License

This library is licensed under Apache 2.0. Full license text is available in LICENSE.