README

api-authorization-method

A web component that extends @advanced-rest-client/authorization-method to add ability to process API security configuration. 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 server 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
Api Key (OAS)
Bearer (OAS)

This component fully support OAS security schemes.

Usage

The component extends @advanced-rest-client/authorization-method package to add API model support. The base component renders basic authorization methods. The element requires to apply AML's JSON+LD model to the amf property and scheme definition to the security property.

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 type="OAuth 2" redirecturi="..."></api-authorization-method>
    <script>
    (async () => {
      const model = await getAmfModel();
      const oauthSecurity = getSecurity(model, '/endpoint', 'get');
      const element = document.querySelector('api-authorization-method');
      element.amf = model;
      element.security = oauthSecurity;
      element.onchange = (e) => {
        console.log(e.target.validate(), e.target.serialize());
      };
    })();
    </script>
  </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);

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.

Exception

OAS' Api Key method support logical AND operation. This means that in this case the security parameter should receive the array of defined for the operation security schemes. That is, the array of items that is under security.scheme property when accessing security definition in the AMF model.

See demo/index.js for an example of how this is handled (setData() function).

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

@api-components/api-authorization-methoddeprecated

Usage no npm install needed!