...
If no SDKs are available in the language you currently use, then it may be necessary to revert to a SDK-free integration using our REST APIs directly. This guide explains how to proceed in such case.
1 - Metadata Endpoint
Status | ||||||||
---|---|---|---|---|---|---|---|---|
|
1.1 How does it 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 'refresh metadata'.
1.2 What to include in the 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).
Below is a commented example of metadata document:
Code Block | ||
---|---|---|
| ||
{
# ===> App Configuration
#
# => environment (informational)
# The environment of your application. Common values are "production", "production-sandbox" and "test".
"environment": "test",
# => host
# This is your application host.
"app": {
"host": "http://my-app.com"
},
# ===> SSO Configuration
#
"sso": {
# => idm
# By default we consider that the domain managing user identification is the same as your application host (see above config.app.host parameter).
# If you have a dedicated domain managing user identification and therefore responsible for the single sign-on handshake (e.g: https://idp.my-app.com) then you can specify it below
"idm": "https://idp.myapp.com",
# => init_path
# This is the path in your application that allows users to initiate the Single Sign-On handshake.
# Upon reaching this endpoint users your application will automatically create a SSO request and redirect the user to Maestrano. Maestrano will then authenticate and authorize the user.
"init_path": "/maestrano/auth/saml/init.php"
# => consume_path (for SAML implementations only)
# This is your application path to the SAML endpoint that allows users to finalize SSO authentication.
# During the 'consume' action your application sets users (and associated group) up and/or log them in.
"consume_path": "/maestrano/auth/saml/consume.php"
},
# ===> Webhooks
# This section describe how to configure the Account and Connec!™ webhooks
"webhook": {
#
# Maestrano will issue a DELETE request to the following paths to notify you
# of any service cancellation (group deletion) or any user being removed from a group.
"account": {
"groups_path": "/maestrano/account/groups/:id",
"group_users_path": "/maestrano/account/groups/:group_id/users/:id"
},
# ==> Connec Subscriptions/Webhook
# The following section is used to configure the Connec!™ webhooks and which entities
# you should receive via webhook.
#
#
"connec": {
# == Notification Path
# This is the path of your application where notifications (created/updated entities) will
# be POSTed to.
# You should have a controller matching this path handling the update of your internal entities
# based on the Connec!™ entities you receive
#
"notifications_path": "/maestrano/connec/notifications",
# == Subscriptions
# This is the list of entities (organizations,people,invoices etc.) for which you want to be
# notified upon creation/update in Connec!™
#
"subscriptions": {
"accounts": true,
"company": true,
"events": false,
"event_orders": false,
"invoices": true,
"items": true,
"journals": false,
"organizations": true,
"payments": false,
"pay_items": false,
"pay_schedules": false,
"pay_stubs": false,
"pay_runs": false,
"people": true,
"projects": false,
"tax_codes": true,
"tax_rates": false,
"time_activities": false,
"time_sheets": false,
"venues": false,
"work_locations": false
}
}
}
} |
2 - Single Sign-On
Status | ||||||||
---|---|---|---|---|---|---|---|---|
|
Maestrano provides two different Single Sign-On protocols: SAML 2.0 and OpenID. OpenID has become fairly more popular than SAML and is also more supported by the community. Chances are you will find a library handling OpenID out-of-the-box for your language of choice. A few examples:
...
Our OpenID guide will give you all the details on the best way to integrate our OpenID provider into your application, just check it out here.
...
3 - Account Management API & Webhooks
Our account management API is a REST API allowing you to perform:
...