JarCastingOAuth authorization
Contains a library and custom elements to perform OAuth2 authorization. The main library is the OAuth2Authorization class that has the logic to perform OAuth 2 authorization. The <oauth2-authorization> element is used only to handle the DOM event to start the authorization flow.
API change
In version 5.0.0 the API surface has changed. The custom element for OAuth 2 authorization only handles the authorization event and uns the authorize function on the OAuth2Authorization class. Also configuration has been redefined and declared in its own TS declaration files.
Types
Types are defined in the @advanced-rest-client/arc-types package.
Usage
Installation
npm install --save @advanced-rest-client/oauth-authorization
Example
import { OAuth2Authorization } from '@advanced-rest-client/oauth-authorization';
const settings = {
grantType: 'implicit',
clientId: 'CLIENT ID',
redirectUri: 'https://example.com/auth-popup.html',
authorizationUri: 'https://auth.example.com/token',
scopes: ['email'],
state: 'Optional string',
};
const factory = new OAuth2Authorization(settings);
const tokenInfo = await factory.authorize(settings)
Popup in authorization flow
This package contains the oauth-popup.html that can be used to exchange token / code data with hosting page. Other page can be used as well. The popup page must use the window.postMessage() to report back to the library the parameters returned by the authorization server. It expect to return the part of the URL that contains the authorization result. For example, for the popup url having values like this: https://redirect.domain.com/popup.html#code=1234&state=5678 the popup window should post message with code=1234&state=5678.
The state parameter and security
This element is intend to be used in debug applications where confidentially is already compromised because users may be asked to provide client secret parameter (depending on the flow). It should not be used in client applications that don't serve debugging purposes. Client secret should never be used on the client side.
To have at least minimum of protection (in already compromised environment) this library generates a state parameter as a series of alphanumeric characters and append them to the request. It is expected to return the same string in the response (as defined in rfc6749). Though this parameter is optional, it will reject the response if the state parameter is not the same as the one generated before the request.
The state parameter is generated automatically by the element if non provided in settings. It is a good idea to use this property to check if the event response (either token or error) are coming from your request for token. The app can support different OAuth clients so you can check later with the token response if this is a response for the same client.
Non-interactive authorization
For implicit and authorization_code token requests you can set the interactive configuration property to false to request the token in the background without rendering any UI related to authorization to the user. It can be used to request an access token after the user authorized the application. Server should return the token which will be passed back to the application.
OAuth 1
The OAuth1 element is deprecated and no longer maintained. The tests for the element has been removed. After consulting with other teams at MuleSoft this element will be removed.
An element to perform OAuth1 authorization and to sign auth requests.
Note that the OAuth1 authorization wasn't designed for browser. Most existing OAuth1 implementation disallow browsers to perform the authorization by not allowing POST requests to authorization server. Therefore receiving token may not be possible without using browser extensions to alter HTTP request to enable CORS. If the server disallow obtaining authorization token and secret from clients then your application has to listen for oauth1-token-requested custom event and perform authorization on the server side.
When auth token and secret is available and the user is to perform a HTTP request, the request panel sends before-request custom event. This element handles the event and applies authorization header with generated signature to the request.
OAuth 1 configuration object
Both authorization or request signing requires detailed configuration object. This is handled by the request panel. It sets OAuth1 configuration in the request.auth property.
| Property | Type | Description |
|---|---|---|
signatureMethod |
String |
One of PLAINTEXT, HMAC-SHA1, RSA-SHA1 |
requestTokenUri |
String |
Token request URI. Optional for before request. Required for authorization |
accessTokenUri |
String |
Access token request URI. Optional for before request. Required for authorization |
authorizationUri |
String |
User dialog URL. |
consumerKey |
String |
Consumer key to be used to generate the signature. Optional for before request. |
consumerSecret |
String |
Consumer secret to be used to generate the signature. Optional for before request. |
redirectUri |
String |
Redirect URI for the authorization. Optional for before request. |
authParamsLocation |
String |
Location of the authorization parameters. Default to authorization header |
authTokenMethod |
String |
Token request HTTP method. Default to POST. Optional for before request. |
version |
String |
Oauth1 protocol version. Default to 1.0 |
nonceSize |
Number |
Size of the nonce word to generate. Default to 32. Unused if nonce is set. |
nonce |
String |
Nonce to be used to generate signature. |
timestamp |
Number |
Request timestamp. If not set it sets current timestamp |
customHeaders |
Object |
Map of custom headers to set with authorization request |
type |
String |
Must be set to oauth1 or during before-request this object will be ignored. |
token |
String |
Required for signing requests. Received OAuth token |
tokenSecret |
String |
Required for signing requests. Received OAuth token secret |
Error codes
params-errorOauth1 parameters are invalidoauth1-errorOAuth popup is blocked.token-request-errorHTTP request to the authorization server failedno-responseNo response recorded.
Acknowledgements
- This element uses jsrsasign library distributed under MIT licence.
- This element uses crypto-js library distributed under BSD license.
Development
git clone https://github.com/advanced-rest-client/oauth-authorization
cd oauth-authorization
npm install
Running the tests
npm test
Required dependencies
The CryptoJS and RSAKey libraries are not included into the element sources. If your project do not use this libraries already include it into your project.
npm i cryptojslib jsrsasign
<script src="../../../cryptojslib/components/core.js"></script>
<script src="../../../cryptojslib/rollups/sha1.js"></script>
<script src="../../../cryptojslib/components/enc-base64-min.js"></script>
<script src="../../../cryptojslib/rollups/md5.js"></script>
<script src="../../../cryptojslib/rollups/hmac-sha1.js"></script>
<script src="../../../jsrsasign/lib/jsrsasign-rsa-min.js"></script>
Also OAuth1 element uses URL class with searchParams properties. If targeting old browsers include polyfill for this too.
