Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

Code Block
languageruby
{
  # ===> 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:

 

FieldTypeRequired for
OpenID SSO
Required for
SAML SSO
Change with the tenant
and the environment
Description
environmentstring - -Yes (with the env. only)
The environment of the platform your are integrated to; accepted values:
- "test" (for the sandbox)
- "uat"
- "production"
app.hoststringYesYes

Yes (with the env. only)

Your application host
api.idstringYesYesYes
The id of your app
api.hoststringYesYesYes
The platform host
sso.idmstring - --
Your Identity Domain Manager
sso.init_pathstring -Yesyour choice
Your application path that allows users to initiate 
the Single Sign-On handshake
sso.consume_pathstringYesyour choice
Your application path to the SAML endpoint that allows 
users to finalize SSO authentication
sso.idpstringYesYesYes
The platform host
sso.x509_fingerprintstring -YesYes 
sso.x509_certificatestring -YesYes 
connec.hoststringYesYesYes
The Connec! endpoint used to fetch data from
webhook.account.group_pathstringYesYesyour choice
Your application path where a notification will be posted 
when an instance of your application is deleted
webhook.account.group_users_pathstringYesYesyour choice
Your application path where a notification will be posted 
when a user is removed from an instance of your application
webhook.connec.notifications_pathstringYesYesyour choice
Your application path where notifications 
(created/updated entities) will be POSTed to
wenhook.connec.subscriptions

hash
keys: predefined entities
values: boolean

YesYesNo
The list of entities (organizations, people, invoices etc.) 
for which you want to be notified upon creation/update in Connec!™

...



2 - Single Sign-On 
Status
subtletrue
colourRed
titleRequired

...