advanced-rest-client
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-methodIn 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 installRunning the demo locally
npm startRunning the tests
npm testAPI components
This components is a part of API components ecosystem