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 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",
...
};
-
Login with redirect
assistant.authorize(parameters);
-
Login with visible iframe
assistant.authorizeFrame(parameters) .then((token) => {}) .catch((err) => {});
-
Login with hidden iframe
assistant.authorizeHiddenFrame(parameters) .then((token) => {}) .catch((err) => {});
-
Login with hidden iframe (fallback to visible iframe if login is required)
assistant.authorizeHiddenFallbackToVisible(parameters) .then((token) => {}) .catch((err) => {});
-
Login with visible popup
assistant.authorizePopup(parameters) .then((token) => {}) .catch((err) => {});
-
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.
assistant.getScope();
Get expires in
Get the expires_in
value associated with the last authorization response.
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
.
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 oflogin 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
andbackdrop
as shown in example object above. -
popup You can optionally customize the popup
height
andwidth
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.
-
onStateChanging
is called right before theprompt=none
is sent when session has changed. -
onStateChanged
is called right after theprompt=none
re-authorization is received back to the client. -
onLogout
is called when the the prompt returns an error oflogin_required
. -
onConsent
is called when the the prompt returns an error ofconsent_required
. -
onError
is called when an error is thrown by IP iframe -
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
An optional parameter which specify the format and value of public key to be used to verify the jwt signature.
Default format isissuer
.
Allowed formats arejwk
|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
andexp
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