Kiwi IAM

This library is meant to be used together with kiwicom/iam for user authorization, and IAP for authentication.

Permissions are defined as Okta groups. IAM parses (and caches) these groups, and returns the relevant permissions for each user, based on the the service requesting the data.

Usage

1. Authentication
2. Authorization
   • Requirements
   • SDL first
   • GraphQLJS
3. IAP token generation
   • Pre-requisites
   • Usage

Authentication

For authentication through IAP you can use the express middleware as in the example below.

import { authenticationMiddleware } from "@kiwicom/iam";

const options = {
  // The correct audience for your project can be found in GCP.
  audience: process.env.IAP_AUDIENCE,
};

const app = express();
// Routes created here will be unauthenticated.
app.use(authenticationMiddleware(options));
// Routes created here will be authenticated.

Authorization

Requirements

• You will need a service token for Kiwi IAM.

• Your user agent should be in the format service/version (organization environment) (eg. my-secure-app/2c1e28a (Kiwi.com sandbox)).

• email: if using directives the user email should be set in context, if using GraphQL-JS it should be passed to isUserAuthorized.

  Either way, it is recommended to use the authentication part of this library to set the email in context, or to extract it from the token after it's verified.

SDL first approach (directives)

schema.graphql

# import * from '@kiwicom/iam/AuthorizationDirective.graphql'

type Query {
  paymentCard: String @requires(permission: "payment-card.read")
}

type Mutation{
  updatePaymentCard(input: PaymentCardInfo!) @requires(permission: "payment-card.write")
}

server.js

import { authorizationDirective } from "@kiwicom/iam";

const schema = makeExecutableSchema({
  typeDefs,
  resolvers,
  schemaDirectives: {
    requires: authorizationDirective({
      serviceUserAgent: "Overseer/f7a1295 (Kiwi.com sandbox)",
      emailPath: "userEmail", // path for getting user email in context, default is 'iapEmail'
      iamURL: process.env.KIWI_IAM_URL,
      iamToken: process.env.KIWI_IAM_TOKEN,
    }),
  },
});

GraphQL-JS

NOTE: do not forget to await for isUserAuthorized, otherwise it will always evaluate to true (being async it returns a Promise, and objects in JS evaluate to true).

import { isUserAuthorized } from "@kiwicom/iam";

const serviceUserAgent = "Overseer/f7a1295 (Kiwi.com sandbox)";

export default new GraphQLObject({
  name: "Booking",
  fields: {
    paymentCard: {
      // This field is available only to users with 'payment-card:read' permissions.
      type: PaymentCard,
      resolve: async ({ paymentCard }, args, { email }) => {
        if (
          !(await isUserAuthorized(
            serviceUserAgent,
            email,
            "payment-card:read",
            process.env.KIWI_IAM_URL,
            process.env.KIWI_IAM_TOKEN,
          ))
        ) {
          throw Error("Unauthorized");
        }
        return paymentCard;
      },
    },
  },
});

IAP token generation for programmatic authentication

For local development it is useful to be able to generate a refresh_token. This library supplies a script for doing this.

Pre-requisites

• OAuth client ID credentials ("Client ID" and "Client secret") for authenticating from a desktop app: https://cloud.google.com/iap/docs/authentication-howto#authenticating_from_a_desktop_app

Usage

Fill the following environment variables:

CLIENT_ID - OAuth Client ID for authenticating from a desktop app
CLIENT_SECRET - OAuth Client secret for authenticating from a desktop app

These are optional environment variables:

GOOGLE_REDIRECT_URI - local server uri, which uses google OAuth for redirecting (default 'http://localhost:3000')
OAUTH_SERVER_PORT - your local server port (default '3000')

package.json

{
  "scripts": {
    "generate:token": "node ./node_modules/@kiwicom/iam/dist/scripts"
  }
}

Now run generate:token. This script will start local server (on default port 3000) and the server will automatically open your browser with Google's OAuth web page for your application. After clicking on the button, Google will redirect you back to your GOOGLE_REDIRECT_URI (which defaults to http://localhost:3000) and you will be provided with a refresh_token (starting with 1/) that has long validity and can be used for local development.

Contributing

We are always looking for people to contribute! Please check https://github.com/kiwicom/js-iam-middleware/blob/master/CONTRIBUTING.md for the guidelines.

License

The code in this project is licensed under MIT license. By contributing to js-iam-middleware, you agree that your contributions will be licensed under its MIT license.