I am hoping someone may have some guidance about something I have been stuck with for a long while. That is, to define a central definition for an OAuth 2.0 security scheme using our corporate IdP, but allow each API to define the specific scopes and grant types supported by the API. We use Anypoint to design & publish RAML specifications, and we use the API specifications as the source of truth for validating the configuration of instances (along with automating generation of tests etc). I want to do this in a way that leverages as much standard RAML as possible without compromising the developer documentation and console generated from the RAML.
The main mechanism I’d expect would be to:
- Publish a security scheme fragment with the invariable elements (IdP URIs, describedBy etc).
- Define a ‘local’ security scheme within each API that includes the externally-defined security scheme fragment, but override the scopes and authorizationGrants nodes (in order to communicate which of those supported by the IdP are used by this API).
- Use parameters within securedBy nodes to specify the scopes and grant types supported by each endpoint.
The issue is that 2. does not seem to be possible (or I don’t know how?), whilst 3. does not work unless the scope is already defined in the security scheme. This means that to do this we’d have to put every scope supported by every API in one file and publish a new version of the security scheme fragment every time one is added, which is not feasible. It’s also compounded by UX problems in the way Anypoint renders security scheme documentation: it relies on the security scheme definition to be relevant at the API-level context (i.e. it ignores any info about scopes at endpoint-level, but requires scopes to be specified there in order for the user to know which scopes to put).
Perhaps someone can give me an idea that I have not thought about?