Where can I find the credentials I will have to use?
When registering your application on Maestranomaestrano.com, as an application provider, you will be given an access to a Maestrano App Provider Dashboard. The technical aspects of the integration can be found in your API portal on Maestrano where the credentials of your application can be found. Simply navigate to the Maestrano dashboard page and click on the API tab.You (API tab in the menu). From there, you will be able to: find your application credentials, fetch or update your metadata endpoint, and launch sandboxes of your app in one of your maestrano organizations.
Table of Contents
1 Where can I find the credentials I will have to use?
In your API portal, you will find the Production application credentials (to be used once the application goes live) and the Sandbox credentials (to be used during the integration phase) which can be configured with different endpoints, and for all non-production environment). Several Sandbox environments can be set up (with different credentials for every sandbox) if you need to manage several test environments; just ask our team if your need more sandboxes.
How to link my application to Maestrano.com?
Your application configuration must be exposed via the metadata endpoint. This defines the endpoints to use during the SSO process as well as the endpoint for the webhooks for the data-sharing.
To link your application to maestrano.com, put your metadata URL in the appropriate section and click on Update/Fetch
2 How does the metadata endpoint work?
In order to understand your application and configure webhooks properly, Maestrano expects you to create a special "metadata" endpoint exposing the configuration of your application preferences in terms of Single Sign-On, data sharing subscriptions, webhooks etc.
| Info | ||
|---|---|---|
| ||
| We believe that this kind of configuration manifest should belong to your application which is why we ask for a special endpoint on your side. The other approach would be to make you fill a long and boring form inside your App Provider dashboard on maestrano.com... but that wouldn't help you keeping your code/configuration easy to read and maintain. |
Once setup, enter the URL of your metadata endpoint into your Maestrano App Provider dashboard then click on 'Update/Fetch'.
3 What to include in my metadata endpoint?
The metadata endpoint should return a JSON document describing your configuration. Note that the call initiated by Maestrano to retrieve your metadata is authenticated via HTTP Basic authentication using your own API credentials (shared secret).
The main fields of your metadata for those using an SDK are:
| Field | Required for OpenID | Required for SAML | Change with the tenant and the environment | Defaults fields | Description |
|---|---|---|---|---|---|
| environment | - | - | - | - | The environment of the platform your are integrated to; accepted values: |
| app.host | Yes | Yes | - | - | Your application host |
| api.id | Yes | Yes | Yes | - | The id of your app |
| api.host | Yes | Yes | Yes | The platform host | |
| sso.idm | - | - | - | same as config.app.host | Your Identity Domain Manager |
| sso.init_path | - | Yes | - | Your application path that allows users to initiate | |
| sso.consume_path | - | Yes | - | Your application path to the SAML endpoint that allows | |
| sso.idp | Yes | Yes | Yes | only if "environment" is set: | The platform host |
| sso.x509_fingerprint | - | Yes | Yes | only if "environment" is set: | |
| sso.x509_certificate | - | Yes | Yes | only if "environment" is set: | |
| connec.host | Yes | Yes | Yes | only if "environment" is set: | The Connec! endpoint used to fetch data from |
| webhook.account.group_path | Yes | Yes | Your application path where a notification will be posted | ||
| webhook.account.group_users_path | Yes | Yes | Your application path where a notification will be posted | ||
| webhook.connec.notifications_path | Yes | Yes | Your application path where notifications | ||
| wenhook.connec.subscriptions | Yes | Yes | false for all entities | The list of entities (organizations, people, invoices etc.) |
4 How to test my integration?
The sandbox application should be used during the integration phase. You can add the application to your dashboard easily by clicking on the Start Sandbox App button and then choosing the appropriate company.
Once added to your dashboard, you can initiate the SSO process by starting the application, clicking on the application tile.
...