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 | A string specifying the client ID given when registering to the OIDC central service. | Yes | |
| redirect_uri | Absolute URL to the HTTP(S) endpoint receiving the authentication response from OIDC. Read more about how the Connector can help with window/inline management. | Yes | |
| oauth_url | Absolute URL to the OIDC Authorize endpoint. | (standard authorize endpoint) | Yes, but default value is shipped |
| scope | A string of resource types (dataset) belonging to the user to request access to. Each scope / resource type must be separated by space. | 'openid' | |
| method | Specify the desired frame method, as explained here. How will the login dialogs be presented to the user? | 'redirect' | |
| response_type | The chosen authentication response type, explained here. Ex. | 'code' | |
| response_mode | Set the format used when returning parameters from the Authorization Endpoint via | 'query' | |
| user_profile | Set the use of any particularly named Identity Provider along with any pre-configuration for the designated provider. Read more about the login_hint parameter. | '' | |
| state | Increase security towards cross-site request forgery by verifying this value in the requests and responses | 'untouched' | |
| nonce | Provide a nonce value for securing the integrity of the id_token
| '' | |
| ui_locales | Provide the desired locale for the session (nb: Norwegian Bokmål, en: English) | 'nb' |
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 |
OIDC.doGetUserInfo ( callback(err, user), [accessToken, tokenType, responseType] ) (experimental)
| Parameter | Description | Default | Required |
|---|---|---|---|
| callback | Function to handle response from userinfo call. Arguments are:
| Yes | |
| accessToken | Optionally provide own accessToken. | null | |
| tokenType | Optionally provide own tokenType. | null | |
| responseType | Set to token if userInfo request should go directly to oauth endpoint instead of through the middleware. | 'code' |
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 Events for redirect_uri communication
When using method window or inline, you can use Cross-domain messaging (postMessage) or XDM in the callback page.
This way you can trigger the following events to seamlessly integrate with the JS Connector on the parent page.
| Name | Description |
|---|---|
| oidc-connector-response-data | Authentication success, returns an Object with the authentication response data given. |
| oidc-connector-error | Authentication error, returns an Object with error information. |