https://github.com/Kitura/Kitura-CredentialsGoogle

A plugin for the Kitura-Credentials framework that authenticates using the Google web login
https://github.com/Kitura/Kitura-CredentialsGoogle

Last synced: 2 months ago
JSON representation

A plugin for the Kitura-Credentials framework that authenticates using the Google web login

• Host: GitHub
• URL: https://github.com/Kitura/Kitura-CredentialsGoogle
• Owner: Kitura
• License: apache-2.0
• Created: 2016-04-03T08:13:27.000Z (about 8 years ago)
• Default Branch: master
• Last Pushed: 2020-11-27T15:25:12.000Z (over 3 years ago)
• Last Synced: 2024-04-14T19:18:57.919Z (3 months ago)
• Language: Swift
• Size: 772 KB
• Stars: 8
• Watchers: 24
• Forks: 9
• Open Issues: 0
• Metadata Files:
  • Readme: README.md
  • Contributing: CONTRIBUTING.md
  • License: LICENSE.txt

Lists

• awesome-ibmcloud - kitura-credentials-google - A plugin for the Kitura-Credentials framework that authenticates using the Google web login. (Platform)

README

        


    

        

    





    

        

    

    

    

    

    

    

    

    

    

    



# Kitura-CredentialsGoogle

Plugin for the Kitura-Credentials framework that authenticates using the Google web login and a Google OAuth token.

## Summary

Plugin for the [Kitura-Credentials](https://github.com/Kitura/Kitura-Credentials) framework that authenticates using the [Google web login with OAuth 2.0](https://developers.google.com/youtube/v3/guides/auth/server-side-web-apps) and a [Google OAuth token](https://developers.google.com/identity/protocols/OAuth2) that was acquired by a mobile app or other client of the Kitura based backend.

## Swift version

The latest version of Kitura-CredentialsGoogle requires **Swift 4.0** or newer. You can download this version of the Swift binaries by following this [link](https://swift.org/download/). Compatibility with other Swift versions is not guaranteed.

## Usage

#### Add dependencies

Add the `Kitura-CredentialsGoogle` and `Credentials` packages to the dependencies within your application’s `Package.swift` file. Substitute `"x.x.x"` with the latest `Kitura-CredentialsGoogle` [release](https://github.com/Kitura/Kitura-CredentialsGoogle/releases) and the latest `Kitura-Credentials` [release](https://github.com/Kitura/Kitura-Credentials/releases).

```swift

.package(url: "https://github.com/Kitura/Kitura-Credentials.git", from: "x.x.x")

.package(url: "https://github.com/Kitura/Kitura-CredentialsGoogle.git", from: "x.x.x")

```

Add `CredentialsGoogle` and `Credentials` to your target's dependencies:

```swift

.target(name: "example", dependencies: ["CredentialsGoogle", "Credentials"]),

```

#### Import packages

```swift

import Credentials

import CredentialsGoogle

```

## Example of Google web login

A complete sample can be found in [Kitura-Sample](https://github.com/Kitura/Kitura-Sample).




First set up the session:

```swift

import KituraSession

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

```

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

```swift

import Credentials

import CredentialsGoogle

let credentials = Credentials()

let googleCredentials = CredentialsGoogle(clientId: googleClientId,

                                          clientSecret: googleClientSecret,

                                          callbackUrl: serverUrl + "/login/google/callback",

                                          options: options)

credentials.register(googleCredentials)

```

**Where:**

   - *googleClientId* is the Client ID from the credentials tab of your project in the Google Developer's console

   - *googleClientSecret* is the Client Secret from the credentials tab of your project in the Google Developer's console

   - *options* is an optional dictionary ([String:Any]) of Google authentication options whose keys are listed in `CredentialsGoogleOptions`

**Note:** The *callbackUrl* parameter above is used to tell the Google 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.

Specify where to redirect non-authenticated requests:

```swift

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

```

Connect `credentials` middleware to requests to `/private`:

```swift

router.all("/private", middleware: credentials)

router.get("/private/data", handler:

    { request, response, next in

        ...  

        next()

})

```

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

```swift

router.get("/login/google",

           handler: credentials.authenticate(googleCredentials.name))

router.get("/login/google/callback",

           handler: credentials.authenticate(googleCredentials.name))

```

## Example of authentication with a Google OAuth token

This example shows how to use `CredentialsGoogleToken` plugin to authenticate post requests, it shows both the server side and the client side of the request involved.

### Server side

First create an instance of `Credentials` and an instance of `CredentialsGoogleToken` plugin:

```swift

import Credentials

import CredentialsGoogle

let credentials = Credentials()

let googleCredentials = CredentialsGoogleToken(options: options)

```

**Where:**

- *options* is an optional dictionary ([String:Any]) of Google authentication options whose keys are listed in `CredentialsGoogleOptions`

Now register the plugin:

```swift

credentials.register(googleCredentials)

```

Connect `credentials` middleware to post requests:

```swift

router.post("/collection/:new", middleware: credentials)

```

If the authentication is successful, `request.userProfile` will contain user profile information received from Google:

```swift

router.post("/collection/:new") {request, response, next in

  ...

  let profile = request.userProfile

  let userId = profile.id

  let userName = profile.displayName

  ...

  next()

}

```

### Client side

The client needs to put the [Google access token](https://developers.google.com/identity/protocols/OAuth2) in the request's `access_token` HTTP header field, and "GoogleToken" in the `X-token-type` field:

```swift

let urlRequest = NSMutableURLRequest(URL: NSURL(string: "http://\(serverUrl)/collection/\(name)"))

urlRequest.HTTPMethod = "POST"

urlRequest.HTTPBody = ...

urlRequest.addValue(googleAccessToken, forHTTPHeaderField: "id_token")

urlRequest.addValue("GoogleToken", forHTTPHeaderField: "X-token-type")     

Alamofire.request(urlRequest).responseJSON {response in

  ...

}

```

## API documentation

For more information visit our [API reference](http://kitura.github.io/Kitura-CredentialsGoogle/).

## Community

We love to talk server-side Swift, and Kitura. Join our [Slack](http://swift-at-ibm-slack.mybluemix.net/) to meet the team!

## License

This library is licensed under Apache 2.0. Full license text is available in [LICENSE](https://github.com/Kitura/Kitura-CredentialsGoogle/blob/master/LICENSE.txt).