Create a Child Instance
The second part of the puzzle for embedding Platform Embed instances is connecting up child instances. So I will show you how to create and attach as many instances as you need for your clients.
You will need these right after you create your first child instance and will save the the time of navigating back to your main instance. These will always be the exact same values that every new child instance will require.
- Download the "Certificate to download"
- Copy to your clipboard the "Embed URL for identity broker"
ο»Ώ
- Return to your main Domo instance. You should still be at the instance management page inside of Domo everywhere.
- Click the new instance button in the top right corner
- you will see three inputs that need to be filled out instance name, service account email and key at tribute.
- Instance name: refers to both how you will reference this instance, but also it will create a domain β off of your base Domo domain.
- Refer to the Resulting domain text below the input to save yourself the headache of creating a domain with a name that you didn't want.
- Service account email refers to what email address will be added in as the first user inside of this account and will be able to access the instance
- I normally set this to a globally accessible account or to my own personal Domo account.
- Key attribute is the value both that the admin portal will use to differentiate which application it is trying to render, but can also be used when doing a publisher subscriber model to filter data in data sets based on this value.
- Inside of your Admin Portal, the Key attribute will be set to the value ofkeyAttribute.
- Domo has made it extremely easy to access individual child instances. Just click on the child instance's name/URL and the link will authorize you into your child instance in a new browser tab.
- Even if your email wasn't set up as the Service account email (and you are an admin) you will still be routed to the child instance.
- Now that we are inside, the child instance will want to navigate to admin settings.
- Inside of admin settings you will see the Authentication section with SAML (SSO) as a menu option.
- Click SAML (SSO).
- This will open up a full page Single Sign-On (SSO) wizard.
- Click on the Start Setup button at the bottom of the page.
- Then click the option Manual Setup - Manual entry for the SSO pro
- We have now made it to the step where we will use those values that I had you Save for later. We now need that certificate that we downloaded and that embed URL that we copied to our clipboard.
- Identity provider endpoint URL
- This is the Embed URL for Identity Broker value we copied to our clipboard in the parent (or "main") Domo instance
- Upload X.509 certificate to authenticate request
- This is the Certificate to download cert.pem file that you downloaded from the parent Domo instance.
- The only other value that we need a value for is the Entity ID.
- The Entity ID is just the domain/subdomain that will be hosting access this child instance.
- Keep in mind that you do need the https:// for this input.
- [Optional Step]
- This next step is not required, but definitely recommended.
- Toggle the screen to DIRECT SIGN ON LIST and click the + ADD USERS TO DIRECT SIGN-ON button.
- Search for the service account or your personal Domo account email and add it to the list.
- By creating a service account back door is a way to guarantee that if you set something up wrong that you will always be able to access this Domo child instance's via URL with whatever account you enter in here.
- With everything not set, toggle back to MANUAL SETUP and click the Save Config button.
- A warning modal should appear that says, "Save SSO Configuration?"
- The screen is just informing you that any other users that currently can access this page from the direct url (besides those added to the list) will lose access after saving.
- Click Save Anyway.
We have done everything that we need to do inside of Domo, but now we need to create a workspace in your Admin Portal and supply it with some details so that we can connect up and render a child instance.
- Step one click add workspace. Name the workspace and click advance details. Toggle the full JWT application embed, toggle and click save.
- On creation you will see it listed will all other workspaces.
- There will be a special icon and the text "Full Access" that denotes that this is a workspace using Domo's JWT Platform Embed.
ο»Ώ
- Click on the workspace that you just created toggle in the horizontal navigation to settings under click on the workspace that you just created.
- In the horizontal menu toggle to Settings.
- In the Settings tab you will see an Authentication Credentials section click the Edit button.
- It will expand to show an + Add Credential button. Click this button and a modal will open up.
- In the following steps, we will fill out each of these inputs.
- We can immediately fill out both the Subscriber instance URL and the Key Attribute Value
- Subscriber instance URL
- This is just the URL of the child instance
- You do NOT need to include https:// for this input.
- Key Attribute Value
- This value is either going to be keyAttribute or it will be the custom value that you entered in when editing the Key Attribute.
- But we have not yet created a Client ID and Client Secret.
ο»Ώ
In the next steps we will create a ClientId and ClientSecret credentials so that we cannot submit create or assign users, groups, and PDP from within your Admin Panel.
Let's complete this crucial next step.
- Navigate to the Domo developer portal at developer.domo.com and create a ClientID and ClientSecret.
- On the left side of the page you can find the link to the DEV PORTAL LOGIN which will navigate you to developer.domo.com/login.
- Enter in the same custom url that you use to access your Domo instance. It will likely look something like company-name.domo.com.
- You only need to enter in the subdomain portion.
- When you login you should see a view that resembles the image attached below.
ο»Ώ
- You will want to select the "Create a client Β»" button at the bottom of the page.
- Complete the form by entering in the Name, the Description (*optional), and by selecting the correct Application Scopes (i.e. Account, Audit, Data, Dashboard, User, Workflow) and click the Create button.
I recommend the Name to be "Clearsquare Portal | View Only". This way when you create more clients in the future and identify which client is tied to this particular portal.
In the case of basic Private Embed (directions are on the previous page) you do not need to select as many Application Scopes (i.e. you only need to select Audit, Data, Dashboard, User). NOTE: Selecting too many Application Scopes will not cause any issues, but is considered bad practice.
Congratulations π you have created a new ClientID and ClientSecret!
The credentials in the image are blurred out for security, but yours will be visible. You can now copy & paste these into your portal to access Domo Everywhere and distribute view only Domo dashboards and cards within your portal.
Note to Safari users | For Full App Embed users will need toΒ allow cross-site tracking. Depending on the browser, you may also run into issues when viewing embedded items in private/incognito tabs.
Learn more aboutΒ SameSite cookies.
ο»Ώ
Now that you have created a Client ID and Client Secret let's navigate back to the Admin Portal and enter those in so that we can submit the subscriber details and sync the portal with your Domo child instance.
You have officially connected and allowed for your Admin Portal to control and manage users, pages, groups, and PDP and now your User Portal(s) can host this Domo child instance!!
