npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@adrianjost/oauth2-firebase

v1.0.0

Published

This library provides OAuth2 server implementation for Firebase

Downloads

23

Readme

@adrianjost/oauth2-firebase

⚠️ This is a fork of oauth2-firebase, with additional support and customizations. More details below.

This library provides OAuth2 server implementation for Firebase. The points are:

  • Supporting Google Sign-In, GitHub Login and Facebook Login to authenticate users as Federation ID provider using Firebase Authentication.
  • Providing each endpoint for Cloud Functions.
  • Storing information into Cloud Firestore.
  • Supporting Authorization Code Grant, Implicit Grant and Client Credentials grant of OAuth 2.0.

NPM Version

Differences to oauth2-firebase

  • support for custom authentication pages
  • define your own CF invocator, to configure your preferred execution region region and compute resources.
    • this also allows you to implement a single CF wrapper to have all oauth2 endpoints in one CF.
  • less dependencies - no ejs => smaller bundle size

How to install

This section describes how to use this library.

Prerequisite

You must already have some Firebase project which enables Cloud Functions, Cloud Firestore and Firebase Authentication. Especially, it is necessary to enable the Google Sign-In or Facebook Login for Federation ID provider on the Firebase Authentication.

Install this library

This library has been providing as JavaScript library on the npm repository. You can install this library with the npm command. We represent your project directory ${PROJECT_HOME}.

$ cd ${PROJECT_HOME}
$ cd functions
$ npm install @adrianjost/oauth2-firebase --save

Define endpoints as Cloud Functions

This library provides some endpoints for OAuth 2.0. Each endpoint is a handler function for the express.

If you use the TypeScript to write your functions, add the following code to your functions/index.ts file.

$ vi index.ts

The code you need to write is the following:

Google Sign-In

import * as functions from "firebase-functions";
import {
  authorize,
  Configuration,
  googleAccountAuthentication,
  token,
} from "@adrianjost/oauth2-firebase";

Configuration.init({
  crypto_auth_token_secret_key_32:
    functions.config().crypto.auth_token_secret_key_32,
  project_api_key: functions.config().project.api_key,
});

exports.token = functions.https.onRequest(token());
exports.authorize = functions.https.onRequest(authorize());
exports.authentication = functions.https.onRequest(
  googleAccountAuthentication()
);

// ...

Facebook Login

import * as functions from "firebase-functions";
import {
  authorize,
  Configuration,
  facebookAccountAuthentication,
  token,
} from "@adrianjost/oauth2-firebase";

Configuration.init({
  crypto_auth_token_secret_key_32:
    functions.config().crypto.auth_token_secret_key_32,
  project_api_key: functions.config().project.api_key,
});

exports.token = functions.https.onRequest(token());
exports.authorize = functions.https.onRequest(authorize());
exports.authentication = functions.https.onRequest(
  facebookAccountAuthentication()
);

// ...

GitHub Login

import * as functions from "firebase-functions";
import {
  authorize,
  Configuration,
  githubAccountAuthentication,
  token,
} from "@adrianjost/oauth2-firebase";

Configuration.init({
  crypto_auth_token_secret_key_32:
    functions.config().crypto.auth_token_secret_key_32,
  project_api_key: functions.config().project.api_key,
});

exports.token = functions.https.onRequest(token());
exports.authorize = functions.https.onRequest(authorize());
exports.authentication = functions.https.onRequest(
  githubAccountAuthentication()
);

// ...

By the code above, the following endpoints are defined:

  • https://.../token - Token endpoint.
  • https://.../authorize - Authorization endpoint.
  • https://.../authentication - Login page for Google Sign-In.

Generate a shared key

This library uses a shared key for navigating pages. You need to generate a random string for the shared key. The string must be 32 length. For example:

$ cat /dev/urandom | base64 | fold -w 32 | head -n 1

Set a configuration value to your project

After generating the random string, you need to set the string as the shared key with the following firebase command.

firebase functions:config:set crypto.auth_token_secret_key_32=<YOUR_GENERATED_RANDOM_STRING>

In addition, you need to set the API Key value of your Firebase project. You can retrieve the API Key value by the following steps:

  1. Go to the setting page of your Firebase project: https://console.firebase.google.com/project/<YOUR_PROJECT_ID>/settings/general/
  2. Get the string of the field labeled Web API Key.

Then, execute the following command to register the configuration:

firebase functions:config:set project.api_key=<YOUR_API_KEY>

Deploy your project

After writing the code and setting the configuration, deploy your project to the Firebase.

$ firebase deploy --only functions

Operations

You need to setup the database to operate OAuth2.0 server as like the following:

  • Register your client
  • Set a description for each scope

Register your client

In OAuth2.0, each client must be registered in advance. This library uses the Cloud Firestore as the storage for the client definitions. In the current version, you need to register client definitions with the Firebase Console manually. To register a client definition, add a new doc in a "clients" collection as like the following:

  • Collection: clients
  • Doc ID: Auto-generated. This will be used as a Client ID value.
  • Fields:
    • user_id - The user ID which represents this client as a user.
    • provider_name - The provider name who this client provides.
    • client_secret - The client secret string. You need to generate this string as the shared key, and need to share the provider.
    • redirect_uri - If this client supports Authorization Code grant and Implicit grant, you need to set this redirect_uri string.
    • grant_type - This is an object. Each key represents a grant type, and each value is boolean whether the grant type is supported or not. You need to set these entries: authorization_code, password, client_credentials and refresh_token.
    • response_type - This is an object. Each key represents a response type, and each value is boolean whether the response type is supported or not. You need to set these entries: code and token.
    • scope - This is an object. Each key represents a scope, and each value is boolean whether the scope is supported or not. You need to set the entry: profile.

The following is a sample JSON string which represents the values above:

{
  "user_id": "client@123",
  "provider_name": "Google, Inc.",
  "client_secret": "foobar123456",
  "redirect_uri": "https://foobar.com/foo/bar/baz",
  "grant_type": {
    "authorization_code": true,
    "password": false,
    "client_credentials": true,
    "refresh_token": true
  },
  "response_type": {
    "code": true,
    "token": true
  },
  "scope": {
    "profile": true
  }
}

Set a description for each scope

This library shows a consent page to ask whether they allow or deny scopes. You need to register descriptions for each scope with the Firebase Console manually. To register a scope description, add a new doc in a "scopes" collection as like the following:

  • Collection: scopes
  • Doc ID: Auto-generated.
  • Fields:
    • name - Scope name (ex. "profile").
    • description - Scope description (ex. "User profile information (User ID and Nickname)").

The following is a sample JSON string which represents the values above:

{
  "name": "profile",
  "description": "User profile information (User ID and Nickname)"
}

Use Additional Endpoints

This library provides some additional endpoints:

  • userinfo - Userinfo API endpoint.
  • tokeninfo - Tokeninfo API endpoint.

Userinfo API endpoint

In OpenID Connect specification, the userinfo endpoint is defined. It provides the authenticated user's information. You can provide the userinfo API endpoint easily by writing the following code:

import {userinfo} from "@adrianjost/oauth2-firebase";
...
exports.userinfo = functions.https.onRequest(userinfo());

This userinfo endpoint works as a protected resource endpoint. That is, the access token is necessary to use this endpoint. For example:

$ curl -X POST -H "Authorization: Bearer <YOUR_ACCESS_TOKEN>" https://.../userinfo

If the access token is valid, you will retrieve the following result:

{
  "sub": "<AUTHENTICATED_USER_ID>",
  "name": "<AUTHENTICATED_USER_NAME>"
}

Tokeninfo API endpoint

The tokeninfo API endpoint provides the information of the passed access token. By this endpoint, you can confirm whether the passed access token is issued for your client or not. You can provide the tokeninfo API endpoint easily by writing the following code:

import {tokeninfo} from "@adrianjost/oauth2-firebase";
...
exports.tokeninfo = functions.https.onRequest(tokeninfo());

The tokeninfo API endpoint accepts an access token as a query parameter called "access_token". For example:

curl https://.../tokeninfo?access_token=<YOUR_ACCESS_TOKEN>

If the access token is valid, you will retrieve the following result:

{
  "aud": "<CLIENT_ID>",
  "sub": "<USER_ID>",
  "expires_in": "<EXPIRES_IN_VALUE>",
  "scope": "<SCOPE_VALUES>"
}

You can check whether the access token is for your client or not by comparing the aud value.

Configurations

You can configure each behavior of this library.

Set expires_in values to access tokens

You can set each expires_in values (unit: sec) for access tokens per grant types. For example:

const expiresInMap = new Map<string, number>();
expiresInMap.set("authorization_code", 2678400);
expiresInMap.set("implicit", 86400);
expiresInMap.set("password", 86400);
expiresInMap.set("client_credentials", 2678400);
expiresInMap.set("refresh_token", 2678400);
Configuration.init({
  ...
  tokens_expires_in: expiresInMap
});

In this library, the default values are:

  • Authorization Code Grant: 86400
  • Implicit Grant: 3600
  • Password: 86400
  • Client Credentials: 86400
  • Refresh Token: 86400

Customize the consent page design

This library provides a very simple design of the consent page. But, you can customize the design. For instance, you can provide your own template string for the consent page from your code.

To customize the page design, you need to create a new class which implements the ConsentViewTemplate interface. For example, the class code will be like the following:

import {
  ConsentData,
  ConsentViewTemplate,
} from "@adrianjost/oauth2-firebase/dist/endpoint/views/consent_view_template";

export class MyConsentViewTemplate implements ConsentViewTemplate {
  public provide() {
    return async (
      data: ConsentData
    ): Promise<string> => /*html*/ `<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8" />
  <meta
    name="viewport"
    content="width=device-width, initial-scale=1, maximum-scale=1"
  />
  <title>Authorization page</title>
</head>
<body>
  <p>${data.providerName} requests the following permissions:</p>
  <ul>
    ${data.scopeString
      .split(" ")
      .map((key) => `<li>${data.scopes.get(key)}</li>`)
      .join("")}
  </ul>
  <p>Could you allow them?</p>
  <form method="post" action="${data.actionPath}">
    <input type="hidden" name="auth_token" value="${data.encryptedAuthToken}" />
    <input type="hidden" name="user_id" value="${data.encryptedUserId}" />
    <button type="submit" name="action" value="allow">Allow</button>
    <button type="submit" name="action" value="deny">Deny</button>
  </form>
</body>
</html>`;
  }
}

This library provides the following values to the template for rendering.

  • providerName: string - The provider name of the client.
  • scopeString: string - The scope string devided by space the client code specifies.
  • scopes: Map<string, string> - The map object which has a set of the scope name and its description.
  • encryptedAuthToken: string - The encrypted auth token. You need to set this as the hidden parameter.
  • encryptedUserId: string - The encrypted user ID. You need to set this as the hidden parameter.

And, you need to set the instance to the Configuration class instance as like the following:

import * as functions from "firebase-functions";
import {
  authorize,
  Configuration,
  googleAccountAuthentication,
  token,
  userinfo,
} from "@adrianjost/oauth2-firebase";
import { MyConsentViewTemplate } from "./my_consent_view_template";

Configuration.init({
  crypto_auth_token_secret_key_32:
    functions.config().crypto.auth_token_secret_key_32,
  project_api_key: functions.config().project.api_key,
  views_consent_template: new MyConsentViewTemplate(),
});

exports.token = functions.https.onRequest(token());
exports.authorize = functions.https.onRequest(authorize());
exports.authentication = functions.https.onRequest(
  googleAccountAuthentication()
);
exports.userinfo = functions.https.onRequest(userinfo());

// ...

Customize the authentication page design

Similar to the consent page, you can customize the authentication page design. To customize the page design, you need to create a new class which implements the AuthenticationViewTemplate interface.

import {
  AuthenticationData,
  AuthenticationViewTemplate,
} from "@adrianjost/oauth2-firebase/dist/endpoint/views/authentication_view_template";

export class MyAuthenticationViewTemplate
  implements AuthenticationViewTemplate
{
  public provide() {
    return async (data: AuthenticationData): Promise<string> => /*html*/ `...`;
  }
}

You also need to set the instance to the Configuration class instance as like the following:

import { Configuration } from "@adrianjost/oauth2-firebase";
import { MyAuthenticationViewTemplate } from "./my_authentication_view_template";

Configuration.init({
  // ...
  views_authentication_template: new MyAuthenticationViewTemplate(),
});

Add Your Protected Resource Endpoint

In this library, the userinfo protected resource endpoint is provided as default. But, you can add your own protected resource endpoint. Each protected resource receives the request including the access token issued for users/clients, checks whether the access token is valid or not against using the protected resource, and actually returns the resources and/or creates some resource or does something. This library provides a convenience abstract class. You can define your endpoint by creating a new class which extends the abstract class and implements the following two methods:

  • validateScope() - Check whether the passed scopes are valid to call this endpoint.
  • handleRequest() - The code body to access to target resources.

To publish your endpoint on the Cloud Functions, you need to retrieve the endpoint function by the endpoint property. As the result, your code will be like the following:

import * as express from "express";
import { AbstractProtectedResourceEndpoint } from "@adrianjost/oauth2-firebase";
import { ProtectedResourceEndpointResponse } from "oauth2-nodejs";

class FriendsEndpoint extends AbstractProtectedResourceEndpoint {
  protected validateScope(scopes: string[]): boolean {
    return scopes.indexOf("frields") !== -1;
  }

  protected handleRequest(
    req: express.Request,
    endpointInfo: ProtectedResourceResponse
  ): Promise<string> {
    return new Promise<string>((resolve, reject) => {
      fetchFrields(endpointInfo.userId)
        .then((friends) => {
          resolve(JSON.stringify(friends));
        })
        .catch((e) => {
          reject(e);
        });
    });
  }
}

exports.friends = functions.https.onRequest(new FriendsEndpoint().endpoint);

If the passed access token is invalid, the handleRequest() function will not be called and returns an error response by the abstract class.