discourse-apim

RCPCH API access management within Discourse

Setup

• Ensure Docker is installed and running
• Check out the main Discourse GitHub repo (https://github.com/discourse/discourse)
• Check out this repository
• Create a symlink between the main Discourse repo and this repo
  • In the Discourse repo run ln -s [location of this repo] plugins/discourse-apim
• Follow the Discourse Docker development instructions
  • d/boot_dev --init
  • Run the Rails backend in one terminal: d/rails s
  • Run the Ember frontend in another: d/ember-cli

Implemented

• Self service generate API credentials for individuals (ie our free tiers)
• Show monthly API usage for individuals
• Generate a monthly CSV of usage across all subscriptions

Roadmap

• Combine customers with old and new subscriptions into a single row in the CSV
• Show monhtly API usage for paying customers (ie members of the appropriate Discourse group)
• Show existing API credentials to paying customers
• Regenerate new API credentials (internally saving old API keys for reference where appropriate)
• Support APIs using OAuth credentials

Data Model

Each row in the plugin UI is a combination of three Azure APIM concepts:

• User
  • One to one mapping with a user in our Discourse forum
  • For Discourse groups (ie paying customers) we create a single user representing the group
• Product
  • One to one mapping with an API
  • Free products do not require approval and must have quota or rate limiting
  • Paid for products require approval and are only shown to users within a customer group in Discourse
• Subscription
  • Essentially the API key, the mechanism for a user to consume a product
  • Each user (including customer group ones) should have only one subscription per product
  • They may however have older ones that are no longer active or come from an old APIM instance

From now on if we refer to "User" below it can be both users that represent individuals on the free tier and a user representing a group.

The discourse plugion talks to the API management API directly:

• https://learn.microsoft.com/en-us/rest/api/apimanagement/apimanagementrest/api-management-rest
• https://learn.microsoft.com/en-us/rest/api/apimanagement/apimanagementrest/azure-api-management-rest-api-authentication#ProgrammaticallyCreateToken

To generate the list of APIs we combine the following API calls:

• Product - List By Service.
  • For individual users we filter by products that do not require approval so they can only sign up to our free products.
  • For a paid customer group we show the products they have been signed up for
  • For administrators viewing either we show all products regardless, allowing them to match as they see fit
• User Subscription - List
  • Contains a scope field against each subscription which we match against the products to show which ones they already have credentials for

To display API keys we can use:

• Subscription - List Secrets

To request a new API key is two API calls:

• User - Create Or Update
  • It's fine to call that on every request as if the user already exists it won't fail
  • The resource name is very picky but I think we can replace any non [A-Z,a-z] character from their email with -. That way we don't need to use the Discourse user ID in Azure APIM.
• Subscription - Create Or Update

We save the user IDs as a custom field on the appropriate Discourse user or group. This allows us to manually change them to accomodate those generated by hand in the Azure UI before this plugin was built.

We also need a list of additional subscription IDs so that we can calculate usage even if the subscription has been recreated or to accomodate subscriptions from a previous APIM instance in Azure.

To generate usage:

• Reports - List By Subscription
  • Call this hourly with monthly time ranges back as far as we want to go
  • Persist the results (currently Redis, should be a normal Rails model in the future)
  • Calculate usage reports by pulling all the data out of the database
  • Show usage for an individual user by filtering by a given set of subscription IDs stored as custom fields