The JS Connector consists of a set of methods and events along with a set of configuration parameters which are summarized below:
Methods
The JS Connector API has the following methods:
OIDC.doInit( { } )
Sets the global configuration used for any doConnect calls.
| Parameter | Description | Default | Required |
|---|---|---|---|
client_id | See parameter description in documentation of the Authorize endpoint. | Yes | |
redirect_uri | See parameter description in documentation of the Authorize endpoint. Read more about how the Connector can help with window/inline management. | Yes | |
oauth_url | Absolute URL to the OIDC Authorize endpoint. | (default authorize endpoint) | No. The OIDC Connector determines the correct URL value via the output from oidc_url |
oidc_url | Absolute URL to the OIDC Openid-configuration endpoint. | (default .well-known endpoint) | No. The OIDC Connector embeds the correct URL value |
scope | See parameter description in documentation of the Authorize endpoint. | 'openid' | No |
method | Specify the desired frame method, as explained here. How will the login dialogs be presented to the user? | 'redirect' | No |
response_type | See parameter description in documentation of the Authorize endpoint. | 'code' | No |
response_mode | See parameter description in documentation of the Authorize endpoint. | 'query' | No |
prompt | See parameter description in documentation of the Authorize endpoint. | '' | No |
acr | Corresponds to the acr_values parameter as described in documentation of the Authorize endpoint. | 4 | No |
login_hint | Corresponds to the login_hint parameter described in documentation of the Authorize endpoint. | '' | No |
state | See parameter description in documentation of the Authorize endpoint. | 'untouched' | No |
nonce | See parameter description in documentation of the Authorize endpoint. | '' | No |
ui_locales | See parameter description in documentation of the Authorize endpoint. | 'nb' | No |
id_token_hint | See parameter description in documentation of the Authorize endpoint. | '' | No |
| sign_id | See parameter description in documentation of the Authorize endpoint. | '' | No |
| sign_txt | See parameter description in documentation of the Authorize endpoint. | '' | No |
The doInit() optionally returns a Promise object if Promise is supported by the browser.
For increased security in a production environment, it is highly encouraged to use nonce and state parameters when interacting with the OIDC service.
OIDC.doConnect ( { callback: function(err, data), config: { }, inlineOnLoadCallback: function(), inlineElementID: ".." } )
Start authentication session with parameters given in an object of key-value pairs.
| Parameter | Description | Default | Required |
|---|---|---|---|
callback | Function callback that is called when JS Connector receives XDM events as explained here. Arguments are:
| null | No |
config | An object with key-value pairs of configuration parameters can be given that can override any parameters given in doInit. | {} | No |
inlineOnLoadCallback | Specify a callback function that will attach to the onload event for the injected iframe when using inline method. | null | No |
inlineElementID | A string containing the ID of a DOM element that will have the OIDC login iframe injected into. | null | Required when using inline method |
The doConnect() method returns a reference to the window object if method=window and the iframe element if method=inline.
Events
The following custom events are relevant for the JS Connector.
Event for loading JS Connector
| Name | Description |
|---|---|
oidc-connector-loaded | Triggered on document.body element when JS Connect is loaded and ready to receive API calls |
XDM in redirect_uri communication for window/inline method
When using method window or inline, you can use Cross-domain messaging (postMessage) or XDM in the callback page on redirect_uri.
This way you can trigger the following types of messages to seamlessly integrate with the JS Connector on the parent page:
Type | When | Example |
|---|---|---|
| oidc-connector-response-data | Authentication success, provide an optional data object | windowParent.postMessage( JSON.stringify( { type: 'oidc-connector-response-data', data: {} } ), '*' ) |
| oidc-connector-error | Authentication error, provide optional error information | windowParent.postMessage( JSON.stringify( { type: 'oidc-connector-error', error: "Some error" } ), '*' ); |