api-authorization-method

A web component that extends @advanced-rest-client/authorization-method to add ability to read API security configuration to apply to currently selected type. The component works with the AML model generated by AMF parser. After applying amf and security properties to the element it, if possible, determines what are the authorization settings for the method, and applies default values.

For example, OAuth 2 can be configured in a number of different ways. When the security model is applied to the element it renders only those properties that the API requires to authenticate the user.

This element adds support for the following security description:

OAuth 2
OAuth 2 with annotation (see RAML's docs)
OAuth 1
RAML's custom scheme
Pass Through

Not supported:

OAS' API key - AMF model does not produce correct model for union of two or more API Key methods. API Key will be implemented when AMF fixes this issue.

Usage

The component supports authorization methods defined in @advanced-rest-client/authorization-method package plus adds custom type which corresponds to RAML's custom authorization scheme.

Applying AMF model

First step is to pass the whole generated AMF model to the amf property. It is required to properly resolve internal model dependencies and to properly read keys in JSON+LD compact model.

Second step is to extract the correct security definition for a method. It is added to a http://a.ml/vocabularies/apiContract#supportedOperation object. The security setting that should be applied to the security property has type of http://a.ml/vocabularies/security#ParametrizedSecurityScheme.

An example script that applies the values can look like the following.

<api-authorization-method type="OAuth 2" id="auth"></api-authorization-method>
<script>
(async () => {
  const model = await getAmfModelSomehow();
  const security = readSecurityFor(model, '/endpoint', 'GET');
  const method = document.getElementById('auth');
  method.amf = model;
  method.security = security;
})();
</script>

The getAmfModelSomehow() function can download pre-generated model or run AMF parser directly from RAML or OAS specification. Then the readSecurityFor() function looks for security definition in /endpoint endpoint, inside GET method. When ready the values are applied to the element.

The order of setting type, amf, and security parameters doesn't matter as the data processing starts asynchronously. However, if the type does not match passed security the security settings is ignored.

A note on clearing settings property. When an undefined or any incompatible value is set to the settings property, the view won't change. Incompatible value is just ignored. Remove the element from the DOM if no longer applicable, change type property to something else, or apply new settings with the new values.

Installation

npm install --save @advanced-rest-client/api-authorization-method

In an html file

<html>
  <head>
    <script type="module">
      import '@advanced-rest-client/api-authorization-method/api-authorization-method.js';
    </script>
  </head>
  <body>
    <api-authorization-method></api-authorization-method>
  </body>
</html>

In a LitElement

import { LitElement, html } from 'lit-element';
import '@advanced-rest-client/api-authorization-method/api-authorization-method.js';

class SampleElement extends LitElement {
  static get properties() {
    return {
      amfModel: { type: Array },
      endpoint: { type: String },
      method: { type: String },
    };
  }

  get security() {
    const { amfModel, endpoint, method } = this;
    return this.readSecurityFor(amfModel, endpoint, method);
  }

  readSecurityFor(amf, endpoint, method) {
    // implement me
  }

  render() {
    const { amfModel, security } = this;
    return html`
    <api-authorization-method
      type="OAuth 2"
      .amf="${amfModel}"
      .security="${security}"
      @change="${this._securityChangeHandler}"></api-authorization-method>
    `;
  }

  _securityChangeHandler(e) {
    console.log('current authorization settings', e.target.serialize());
  }
}
customElements.define('sample-element', SampleElement);

Development

git clone https://github.com/advanced-rest-client/api-authorization-method
cd api-authorization-method
npm install

Running the demo locally

npm start

Running the tests

npm test

API components

This components is a part of API components ecosystem