...
Code Block | ||
---|---|---|
| ||
{ # ===> App Configuration # # => environment # The environment of your application. Common values are: # - "production", for your integration on a platform in a Production environment or UAT environment # - "production-sandbox", for the sandbox you use for your tests during the integration on maestrano.com # - "test", for the SSO test on the Sandbox "environment": "test", # => host (required) # This is your application host. For UAT and Production environments, it must be a publicly resolvable URL, you cannot use "http://localhost:3000" for instance. "app": { "host": "http://my-app.com" }, # "api": { # => id (required) # The id of your app. # For maestrano.com integration, it corresponds to the App ID of your Maestrano App Provider API Dashboard. # For other platform, we will send it to you with your API key. "id": "app-19op", # => host (required) # It corresponds to the platform host. # It changes with the tenant and the environment. We will provide you the correct host for the platform you are being connected to. "host": "http://api-sandbox.maestrano.io" }, # ===> 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 (required) # 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", # This value can be changed on a per-tenant basis: # "init_path": "/maestrano/auth/saml/init.php?tenant=mytenant" # => consume_path (required) # 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", # This value can be changed on a per-tenant basis: # "consume_path": "/maestrano/auth/saml/consume.php?tenant=mytenant" # => idp (required) # It corresponds to the platform host. # It changes with the tenant and the environment. We will provide you the correct host for the platform you are being connected to. "idp": "https://maestrano.com", # => x509_fingerprint and x509_certificate # It changes with the tenant and the environment. We will provide you the correct host for the platform you are being connected to. "x509_fingerprint": "8a:1e:2e:76:c4:67:80:68:6c:81:18:f7:d3:29:5d:77:f8:79:54:2f" "x509_certificate": "-----BEGIN CERTIFICATE-----MIIDezCCAuSgAwIBAgIJAMzy+weDPp7qMA0GCSqGSIb3DQEBBQUAMIGGMQswCQYDVQQGEwJBVTEMMAoGA1UECBMDTlNXMQ8wDQYDVQQHEwZTeWRuZXkxGjAYBgNVBAoTEU1hZXN0cmFubyBQdHkgTHRkMRYwFAYDVQQDEw1tYWVzdHJhbm8uY29tMSQwIgYJKoZIhvcNAQkBFhVzdXBwb3J0QG1hZXN0cmFuby5jb20wHhcNMTQwMTA0MDUyMzE0WhcNMzMxMjMwMDUyMzE0WjCBhjELMAkGA1UEBhMCQVUxDDAKBgNVBAgTA05TVzEPMA0GA1UEBxMGU3lkbmV5MRowGAYDVQQKExFNYWVzdHJhbm8gUHR5IEx0ZDEWMBQGA1UEAxMNbWFlc3RyYW5vLmNvbTEkMCIGCSqGSIb3DQEJARYVc3VwcG9ydEBtYWVzdHJhbm8uY29tMIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQC+2uyQeAOc/irohCyT33RkkWfTGeJ8E/mu9F5ORWoCZ/h2J+QDuzuc69Rf1LoO4wZVQ8LBeWOqMBYzotYFUIPlPfIBXDNL/stHkpg28WLDpoJM+46WpTAgp89YKgwdAoYODHiUOcO/uXOO2i9Ekoa+kxbvBzDJf7uuR/io6GERXwIDAQABo4HuMIHrMB0GA1UdDgQWBBTGRDBTie5+fHkB0+SZ5g3WY/D2RTCBuwYDVR0jBIGzMIGwgBTGRDBTie5+fHkB0+SZ5g3WY/D2RaGBjKSBiTCBhjELMAkGA1UEBhMCQVUxDDAKBgNVBAgTA05TVzEPMA0GA1UEBxMGU3lkbmV5MRowGAYDVQQKExFNYWVzdHJhbm8gUHR5IEx0ZDEWMBQGA1UEAxMNbWFlc3RyYW5vLmNvbTEkMCIGCSqGSIb3DQEJARYVc3VwcG9ydEBtYWVzdHJhbm8uY29tggkAzPL7B4M+nuowDAYDVR0TBAUwAwEB/zANBgkqhkiG9w0BAQUFAAOBgQAwRxg3rZrML//xbsS3FFXguzXiiNQAvA4KrMWhGh3jVrtzAlN1/okFNy6zuN8gzdKDYw2n0c/u3cSpUutIVZOkwQuPCMC1hoP7Ilat6icVewNcHayLBxKgRxpBhr5Sc4av3HOW5Bi/eyC7IjeBTbTnpziApEC7uUsBou2rlKmTGw==-----END CERTIFICATE-----" }, # ===> Data Sharing # This section describes how to configure the Account and Connec!™ webhooks # => connec.host (required) # It corresponds to the endpoint used to fetch data from. # It changes with the tenant and the environment. We will provide you the correct host for the platform you are being connected to. "connec": { "host": "https://api-connec.maestrano.com" } "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. # => groups_path (required) # => group_users_path (required) "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": { # => notifications_path (required) # 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 (required) # 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 } } } } |
1.3 What are the required fields in my metadata?
Required fields in your metadata, depending on the SSO protocol you have chosen:
Field | Type | Required for OpenID SSO | Required for SAML SSO | Change with the tenant and the environment | Description |
---|---|---|---|---|---|
environment | string | - | - | Yes (with the env. only) | The environment of the platform your are integrated to; accepted values: |
app.host | string | Yes | Yes | Yes (with the env. only) | Your application host |
api.id | string | Yes | Yes | Yes | The id of your app |
api.host | string | Yes | Yes | Yes | The platform host |
sso.idm | string | - | - | - | Your Identity Domain Manager |
sso.init_path | string | - | Yes | your choice | Your application path that allows users to initiate |
sso.consume_path | string | - | Yes | your choice | Your application path to the SAML endpoint that allows |
sso.idp | string | Yes | Yes | Yes | The platform host |
sso.x509_fingerprint | string | - | Yes | Yes | |
sso.x509_certificate | string | - | Yes | Yes | |
connec.host | string | Yes | Yes | Yes | The Connec! endpoint used to fetch data from |
webhook.account.group_path | string | Yes | Yes | your choice | Your application path where a notification will be posted |
webhook.account.group_users_path | string | Yes | Yes | your choice | Your application path where a notification will be posted |
webhook.connec.notifications_path | string | Yes | Yes | your choice | Your application path where notifications |
wenhook.connec.subscriptions | hash | Yes | Yes | No | The list of entities (organizations, people, invoices etc.) |
...
2 - Single Sign-On
Status | ||||||||
---|---|---|---|---|---|---|---|---|
|
...