OData interface template
The template defines the parameters for connecting to a OData service.
Refer to the common template parameters.
Template parameters
| Parameter | Type | Description |
|---|---|---|
| IP | Internal | The IP or DNS name of the server where the Ometa Business Connector Slave Listener is installed. |
| Port | Internal | The port on which the BCSL service is running. |
| Service Url | External | The URL of the OData service to connect to. This is optional, if left empty the service URL must be specified in the interface script of the method. If both are filled the interface script is leading. |
| Global Custom Query Options | External | The custom query options to apply on each request made to the OData service. This is optional. There is also an option to specify this in the interface script. If both are specified, the options are appended. |
| Headers | External | Headers to apply on each request made to the OData service. This is optional. There is also an option to specify this in the interface script. If both are specified, the headers are appended. If the same headers are specified, the value from the interface script will be used. (e.g.:{"Accept":"application/json","Company":"100"}) |
| Enable Cross-Site Request Forgery Tokens | External | Enables the use of cross-site request forgery tokens (CSRF) by using the X-CSRF-Token header. The token will be fetched on GET requests and set on modification methods (e.g. POST, PATCH, ...). |
| Cross-Site Request Forgery Token Caching Time | External | Determines how long in seconds a request forgery token may be cached before it should be refreshed. Set to 0 to fetch a new token for every write request. Tokens are refreshed using the $metadata endpoint. |
| Username | External | The username of the user used to authenticate to the OData service with Basic Authentication. This is optional as a user is not always required when connecting to an OData service. |
| Password | External | The password of the user used to authenticate to the OData service with Basic Authentication. This is optional as a user is not always required when connecting to an OData service. |
| OAuth Url | External | The full url of where to fetch the access token to use. Optional. If both username, password and OAuth Url are provided, the request will be made with Basic Authentication in conjunction with the requested access token |
| OAuth Scope | External | The authentication scope for OAuth. Optional. By default, the scope is sent as scope in the body. This can be overridden by prefixing the value and separate it with a semicolon: resource;user.profile.read. |
| OAuth Client ID | External | The client id to send along with the OAuth token request. Optional but required when an OAuth Url is given. |
| OAuth Client Secret | External | The client secret to authenticate on the OAuth service. Required when an OAuth Url is given. |
| OAuth Username | External | The username to use for Basic Authentication when requesting a token from the OAuth token endpoint. |
| OAuth Password | External | The password of the user requesting a token from the OAuth token endpoint. |
| OAuth Grant Type | External | The grant type to use for requesting a token. The default parameter name which is send to the OAuth provider is grant_type. If this is different you can override this by separating it with a semicolon: my_grant_type;client_credentials" |
| OAuth Parameters | External | Custom parameters to send along with the request to the OAuth token endpoint. These must be in the format 'Parameter1Name=value1;Parameter2Name=value2'. |
| Force Ometa Client Id | External | The client id used to authenticate on the Ometa OAuth service. This will override any user access token. |
| Select Only Output Fields | External | Whether to select only the output fields when executing a GET request to the OData interface. This option can be disabled when the OData service doesn't support the $select for example. When this option is specified in the interface script, the value from the profile is ignored. |
Tip
When executing requests on the Ometa Core Service, use the corresponding Template and Profile. This ensures that authorization for the method execution is done using the same token the user used to authenticate. It is possible to add a client ID and secret to this profile as well. When filled in, these credentials will be used to retrieve a token to authorize the request.
OAuth & SAML 2.0 Assertions
Some OAuth token endpoints still use SAML 2.0 assertions to authenticate a user and provide you with an access token to access any resources on their behalf. If this is the case you'll need to fill in saml2-bearer or urn:ietf:params:oauth:grant-type:saml2-bearer as OAuth Grant Type in the profile.
The OData interface will detect this and request a SAML 2.0 assertion for the current user (or client) to send along with the OAuth token request. The Ometa Authority Service is responsible for creating the SAML 2.0 assertions.
Warning
If an access token cannot be found in the current request (e.g.: anonymous users), no SAML 2.0 assertion can be created and you'll receive an error.
Ensure that OData requests, which use SAML 2.0 assertions, are always made by an authenticated user. Another option is to have a Force Ometa Client Id configured in the profile to overrule the user token, or for system operations (e.g.: synchronizations, method jobs or case management).
Example
The following example shows the profile for connecting to the OData Trip Bin service
| Parameter | Value |
|---|---|
| IP | localhost |
| Port | 2002 |
| Service Url | http://services.odata.org/TripPinRESTierService/(S(bmm2vviqdtfumiwx0btwrurg))/ |
| Global Custom Query Options | language=en&country=UK |
| Username | |
| Password | |
| OAuth Url | |
| OAuth Scope | |
| OAuth Client ID | |
| OAuth Client Secret | |
| OAuth Username | |
| OAuth Password | |
| OAuth Grant Type | |
| OAuth Parameters | |
| Force Ometa Client Id | |
| Select Only Output Fields |