API product RBAC

[arunz6161]

Share with chat channel so that Andrew P and others can review it.

[cnovak]

Objective

The objective is to allow API Providers to control who can discover or use APIs through the developer portal. Not all APIs should be visible or usable by all developers that can access a developer portal.

Background

There has been a need for API producers to be able to change the access control of documents and usage of an API for a long time. Right now we do not have a good solution in Drupal 8 portals.
Apigee Edge has the concept of an API Product. An API Product is the association between an API App (keys) and an API:

When creating an API proxy, an API Key or OAuth policy can be added to the proxy, which forces authentication before the API can be used. The way a developer gets access is by creating an App in the developer portal. This app contains credentials to use the app.
An API Product creates an indirect relationship to API Proxies for flexibility on what is exposed to a developer. An API Product may contain only part of an API Proxy, or may contain multiple API Proxies.
One point of confusion is that in Apigee Edge, you can create an API Proxy using an OpenAPI spec. However from the developer’s perspective, only API Products are shown.

Sidenote: An API Product creates an indirect relationship to API Proxies for flexibility on what is exposed to a developer. An API Product may contain only part of an API Proxy, or may contain multiple API Proxies. One point of confusion is that in Apigee Edge, you can create an API Proxy using an OpenAPI spec. However from the developer’s perspective, only API Products are shown.

Requirements

Restrict access on reading docs or creating apps

As an API Provider, I only want certain developers or teams of developers to read documentation or use a given API product so that I can hide that API Product from most developers.

Examples:

• I only want developers working at Initech to use our Messaging API since we only give access to specific partners. We published the API documentation and a “Getting Started with Messaging API” page, and a “Messaging” forum. None of this content should be visible to anyone besides the Initech developers.

Restrict access to creating apps

As an API Provider, I want any developer or teams of developers to be able to read documentation about a given API product, but want to only allow certain developers to be able to use that API product so that we can add manual or automatic steps before approving access.

Examples:

• I want my Weather API to be indexed by Google, but want the API to only be used by developers that contact us via a web form so that we can vet them before they are able to use the API.
• Only allow developers that fill out a terms and conditions form to be able to use our Image Search API in beta.

Set access defaults for new API Products

As an API provider, I want to set the access control of a new API Product to be hidden for all users except certain people on my team so that developers do not use the product until I have tested it.

Design

Since Drupal already has a robust access control system, the plan is to use already existing modules to control access, such as the Permissions by Term module.

The current implementation uses a custom entity for API Docs. This solution however does not work well with taxonomy based access control solutions since they usually work with Node entity types.
The Permissions by Term module has a submodule named Permissions by Entity, but that solution does not work with views so you cannot hide the display of API Docs through permissions. Instead the view listing displays, and when you click on the listing you get a permission denied message.

To make things easier, we can make a new 2.x version of API Catalog that uses Node entities instead of a custom entity.

We will also need to make changes to the Apigee SmartDocs Plugin for Maven since the endpoint to call for the API will chan

API Catalog Changes

• Change APIDoc entities into a Node entity
• Update view for API Catalog listing to use this new APIDoc Node content type
• Create a way to migrate content to the Node entity from 1.x version
• Update Documentation if needed

Apigee SmartDocs Plugin for Maven

• Make endpoint configurable, or create a new version that has new URL endpoint

Future Roadmap

The Apigee Edge and Apigee M10n modules have a permission system that works with API Products. Investigate how we use one way to lay out access control for API Products on API Catalog, Apigee Edge, and Apigee M10n modules.

[giteshk]

We want to maintain a 8.x-1.0 version with the old approach and 8.x-2.0 with the new content node approach

[cnovak]

We don't want to maintain the old version, but do want to give time for anyone that added features on top of the 1.0 version to move to 2.0 version. There would not be any breaking changes if you did not add any custom code, but in case someone does we need to bump major version to follow semantic versioning.

[giteshk]

@cnovak Any timeframe on when this will be available?

[cnovak]

We are very close to releasing a PR for this, you can subscribe to notifications to check when the PR is pushed up.

[m-khan23]

@cnovak @giteshk is there any work around for this? We are releasing API documentation for internal use on Monday 5/4 and have no way to hide it from external users at this point.

[giteshk]

@m-khan23 , Have you tried restricting access to your API Docs by changing "View published API docs" permission to a targeted role. So Anonymous users don't get access to it?

[m-khan23]

@giteshk we aren't looking for a blanket policy. Here is the context:
Anonymous users: See API A, B, C
Users with 'External Role': See API A, B, C
Users with 'Internal Role': See API A, B, C and D

Even if there is a wonky technical work around, we are okay with that for now because as it stands today - we don't have a clean way to go live with API D on 5/4.

[kiranjyoth]

@m-khan23 Here is a way you can achieve this.
If you have /apis that will display all API docs of all products and users can see all published documentation. Which includes ABC&D.
But If you enable classification of your API docs using a taxonomy term reference field, For example, refer to the screenshot

You can use a module (https://www.drupal.org/project/permissions_by_term) to set permissions on this node by making the taxonomy term not visible to certain roles. This permissions will trickle down to Node view, and Also views displays using node view permissions.

Hope that helps!

[m-khan23]

@kiranjyoth hey, thanks for the tips. While all other pages respect settings we have applied via the 'Permissions by Term' module, we have never been able to get the API catalog to play nice. I've tried what you have suggested again and no - go.

Do you have a running example of this?

[cnovak]

@kiranjyoth , @giteshk: @arlina-espinoza just posted PR #71 for this if you want to help review and verify. By creating a new 2.0 version that uses node content type instead of a custom entity, you can use any of the existing node RBAC modules that already exist for nodes.

[arlina-espinoza]

Closed by #84 , which implements the API Catalog functionality using a node type, making it possible to use permissions by term or other node access control modules from contrib to implement RBAC.