@curity/oauth-assistant/README.md

Curity JS OAuth Assistant

# Curity OAuth Assistant

## Add to project
Add to your project using npm 

```
npm install @curity/oauth-assistant
```

or yarn

```
yarn add @curity/oauth-assistant
```

## How to use in your project

### Initialize Assistant
You need to pass in the settings object in order to initialize Assistant.

Here is an example settings object.

```
const settings = {
    flow_type      : "code", // Possible values : (code, implicit, assisted_token)
    base_url       : "http://localhost:8443",
    client_id      : "test_client_id",
    issuer         : "https://localhost:8443/oauth/v2/oauth-anonymous",
    redirect_uri   : "http://localhost:8080/assisted.html", // Basic version of assisted.html is available in example/assisted.html but it can be customized as needed.
    for_origin     : "http://localhost:8080",
    iframe         : { // Optional: Passing in null would take default values
        targetElement: null, // targetElement querySelector , default: 'body'
        width   : null, // take default value : 400
        height  : null, // take default value : 700
        style   : null, // take default value
        backdrop: {
            visible      : true, // default is true
            style        : null, // take default value
            backdropClass: ""
        },
        closeButton: {
            visible: true, // default is true
            style  : null, // style for wrapper div of close button
            class  : "",
            button : null
        },
    },
    "popup": {
        "width" :  null,  // take default value : 400
        "height": null   // take default value : 600
    },
    allowed_origins: ["http://localhost:8443", "http://localhost:8080"], // default is [window.origin]
    disable_session_management: false, // Optional: if set to true, session management will be disabled
    check_session_iframe: null, // Optional url, if not provided then it will be resolved from metadata
    session_polling_interval: 5, // Optional: polling interval in seconds, default is 5
    check_session_iframe_events: { // Optional
            onStateChanging: () => {},
            onStateChanged: () => {},
            onLogout: () => {},
            onConsent: () => {},
            onError: () => {},
            onUnchanged: () => {},
    },
    allowed_jwt_algorithms: ['RS256'], // Optional: algorithms to trust for JWT validation
    jwt_sig_public_key: { // allowed formats are jwk | jwks_uri | pem | issuer | metadata_url | raw
        format: 'issuer', // in case of issuer, the issuer value will be taken from jwt payload
        value: null
    },
    ignore_not_before: false, // Optional: controls whether to skip the validation of the nbf claim when validating the ID Token, default is false
    ignore_expiration: false, // Optional: controls whether to skip the validation of the exp claim when validating the ID Token, default is false
    clock_tolerance: 0, // Optional: controls the clock tolerance when validating the ID Token to accomodate drifting clocks, default is 0
    debug: false,  // Optional: Enabling debug to true will display console logs of assistant, default is false
    openid_configuration_url: "https://example.com/path/.well-known/openid-configuration", // Optional: set if the OpenID Configuration URL uses different host or base path than the issuer 
};
```
More details on settings object is available in the [settings](#settings) section.

Import Assistant into your project and initialize it using settings object.

```
import Assistant from "@curity/oauth-assistant";
// OR using require 
// const Assistant = require("@curity/oauth-assistant");


const assistant = new Assistant(settings);

assistant.init()
    .then(() => {
        console.log("assistant loaded");
        // Start the authorize flow
    });
```

### Available methods 

```
1. authorize(parameters)
2. authorizeFrame(parameters)
3. authorizeHiddenFrame(parameters)
4. authorizeHiddenFallbackToVisible(parameters)
5. authorizePopup(parameters)
6. authorizeHiddenFallbackToPopup(parameters)
7. getToken()
8. getIDToken()
9. revoke()
10. logout(postLogoutRedirectUri, global)
11. getScope()
12. getExpiresIn()
13. getAdditionalFieds()
```

After initializing the Assistant, you can start authorize flow using any of the 4 methods available.

To each authorize flow, you can pass in any number of optional parameters like below.
```
const parameters = {
    scope: "openid",
    state: "state-value",
    response_type: "token id_token",
   ...
};
```

1. **Login with redirect**

    ```
    assistant.authorize(parameters); 
    ```

2. **Login with visible iframe**

    ```
    assistant.authorizeFrame(parameters)
     .then((token) => {})
     .catch((err) => {});
    ```

3. **Login with hidden iframe**

    ```
    assistant.authorizeHiddenFrame(parameters)
     .then((token) => {})
     .catch((err) => {});    
    ```

4. **Login with hidden iframe (fallback to visible iframe if login is required)**

    ```
    assistant.authorizeHiddenFallbackToVisible(parameters)
     .then((token) => {})
     .catch((err) => {});    
    ```

5. **Login with visible popup**

    ```
    assistant.authorizePopup(parameters)
     .then((token) => {})
     .catch((err) => {});
    ```

6. **Login with hidden flow (fallback to visible popup if login is required)**

    ```
    assistant.authorizeHiddenFallbackToPopup(parameters)
     .then((token) => {})
     .catch((err) => {});    
    ```

Once the authorize flow is complete, you can get the `token`, `id_token` or revoke tokens using the Assistant.


**Get Token**
```
assistant.getToken();
```


**Get ID Token**
```
assistant.getIDToken();
```


**Revoke Tokens**
```
assistant.revoke()
    .then(() => {})
    .catch((err) => {});
```


**Refresh Tokens**
If the AS issued a refresh token, use it to obtain new tokens. 
```
assistant.refresh()
    .then(() => {})
    .catch((err) => {});
```


**Logout**     
Logout the user from server and revoke tokens.    
Default value of `postLogoutRedirectUri` is `window.location.href`.
Default value of `global` is `false`, if set to `true` then it will be sent during logout as an extra query parameter, causing logout to happen globally across all logged in clients.
```
assistant.logout(postLogoutRedirectUri, global)
    .then(() => {})
    .catch((err) => {});
```

**Get scopes**

Get the space-delimited list of scope tokens associated with the last authorization response.

```javascript
assistant.getScope();
```

**Get expires in**

Get the `expires_in` value associated with the last authorization response.

```javascript
assisstant.getExpiresIn();
```

**Get additional fields**

Get a map of any additional fields associated with the last authorization response. Fields other than `access_token`,
`scope`, `expires_in` or `id_token`.

```javascript
assistant.getAdditionalFields();
```

### Settings

While initializing Assistant, you need to pass in a settings object which contain some mandatory and optional values.

```
{
    flow_type      : "code", // Possible values : (code, implicit, assisted_token)
    base_url       : "http://localhost:8443",
    client_id      : "test_client_id",
    issuer         : "https://localhost:8443/oauth/v2/oauth-anonymous",
    redirect_uri   : "http://localhost:8080/assisted.html", // Basic version of assisted.html is available in example/assisted.html but it can be customized as needed.
    for_origin     : "http://localhost:8080",
    iframe         : { // Optional: Passing in null would take default values
        targetElement: null, // targetElement querySelector , default: 'body'
        width   : null, // take default value : 400
        height  : null, // take default value : 700
        style   : null, // take default value
        backdrop: {
            visible      : true, // default is true
            style        : null, // take default value
            backdropClass: ""
        }
    },
    "popup": {
        "width":  null,  // take default value : 400
        "height": null   // take default value : 600
    },
    allowed_origins: ["http://localhost:8443", "http://localhost:8080"], // default is [window.origin]
    disable_session_management: false,
    check_session_iframe: null, // Optional url, if not provided then it will be resolved from metadata
    session_polling_interval: 5, // Optional: polling interval in seconds, default is 5
    check_session_iframe_events: { // Optional
            onStateChanging: () => {},
            onStateChanged: () => {},
            onLogout: () => {},
            onConsent: () => {},
            onError: () => {},
            onUnchanged: () => {},
    },
    allowed_jwt_algorithms: ['RS256'], // Optional: algorithms to trust for JWT validation
    jwt_sig_public_key: { // allowed formats are jwk | jwks_uri | pem | issuer | metadata_url | raw
        format: 'issuer', // in case of issuer, the issuer value will be taken from jwt payload
        value: null
    },
   ignore_not_before: true,
   ignore_expiration: false,
   clock_tolerance: 10,
   debug: false,  // Enabling debug to true will display console logs of assistant
   openid_configuration_url: "https://example.com/path/.well-known/openid-configuration", // Set if the OpenID Configuration URL uses different host or base path than the issuer
};
```

All fields marked with `*` are mandatory.

* **flow_type***
Flow type determines the authorize flow to be used. It can be any of the three flows (code, implicit, assisted_token).  


* **base_url*** Base url of Curity Identity server.


* **client_id*** App client id


* **issuer*** Issuer endpoint


* **redirect_uri*** In case of `framed flow`, it will be something like assisted.html which is provided in example, 
you can provide any redirect uri and handle the response accordingly like it is done in assisted.html,
 you need to either host assisted.html on your server or implement the same thing in yourself and provide the redirect uri accordingly.
In case of `login with redirect`, redirect uri will be probably your host application or wherever you will handle the response.


* **iframe** You can optionally customize the iframe `height`, `width`, `style` and `backdrop` as shown in example object above.

* **popup** You can optionally customize the popup `height` and `width` as shown in example object above.

* **allowed_origins*** Allowed origins: default is [window.origin]. For assisted token flow, this should include the origin of the token server or the origin of where the script is hosted. If the server is behind a reverse proxy, then the proxy's origin should be used.

* **disable_session_management** Set to true to disable session management
 
* **check_session_iframe** Url for the check session iframe, default will be resolved from metadata


* **session_polling_interval** Polling interval to post message to check session iframe to check for session, default is 5 seconds


* **check_session_iframe_events**

    Callback events which will be called in response to check session iframe polling.
    
    1. `onStateChanging` is called right before the `prompt=none` is sent when session has changed.
    2. `onStateChanged` is called right after the `prompt=none` re-authorization is received back to the client.
    3. `onLogout` is called when the the prompt returns an error of `login_required`.
    4. `onConsent` is called when the the prompt returns an error of `consent_required`.
    5. `onError` is called when an error is thrown by IP iframe
    6. `onUnchanged` is called whenever the login state does not change.
    

* **allowed_jwt_algorithms** Optional: Algorithms to trust for JWT validation
   
* **jwt_sig_public_key**  [More details](https://www.npmjs.com/package/@curity/jwt-validation#allowed-public-key-formats)
    
    An optional parameter which specify the format and value of public key to be used to verify the jwt signature.    
    Default format is `issuer`.     
    Allowed formats are `jwk` | `jwks_uri` | `pem` | `issuer` | `metadata_url` | `raw`
    
       1. **jwk**   
          A jwk can directly be passed as an object (and not a string), when format specified is `jwk`.    
          
       2. **jwks_uri**     
          A list of jwks can be retrieved from a specified `jwks_uri`.
       
       3. **pem**    
          A pem key string can be provided using public key format `pem`. 
       
       4. **issuer**   
          If the format specified is `issuer`, then jwt issuer is used to retrieve metadata which in turn, is resolved to retrieve jwk from corresponding jwks_uri. 
         
       5. **metadata_url**   
          If the format specified is `metadata_url`, then jwk is retrieved from corresponding jwks_uri of resolved metadata.
        
       6. **raw**       
          You can provide HMAC secret keys using `raw` format.           
    

     
* **ignore_not_before** Set to true to ignore not before (`nbf`) on ID Token validity check, default is false

* **ignore_expiration** Set to true to expiration (`exp`) on ID Token validity check, default is false

* **clock_tolerance** Controls the clock skew of the `nbf` and `exp` claim on ID Token validity check

* **debug** Debug mode set to true will enable the assistant to display console logs in order to help for debugging.

* **openid_configuration_url** URL of the OpenID Configuration well-known endpoint. By default this URL equals to the issuer value plus the path `/.well-known/openid-configuration`

Follow https://curity.io/resources/learn/test-using-oauth-assistant/ to try out the OAuth Assistant using the example app