Tray Embedded / Core Topics / Authentications / Auth-only dialog

Auth-only dialog

It is possible to allow your users to complete the authentication step using an auth-only dialog, instead of the Configuration Wizard.

Note that you can use an iFrame to present this if you wish to 'whitelabel' and hide the https://embedded.tray.io url. If you wish to do this your domain will need to be added to our whitelist. Please contact us at support@tray.io to arrange this.

You can also whitelabel this using a custom domain as explained in our page on whitelabelling

You can see an example of this being put to use in our demo app with onCreateAuth at https://github.com/trayio/embedded-edition-sample-app/blob/master/src/components/Instance.js

In order to use an auth-only dialog you will need to:

  1. When editing your Solution, pick up the External ID for the authentication from the Configuration section:
  1. Use the Create Solution Instance mutation to generate a solutionInstanceId for the End User (this requires an access token for your End User as per Create User Token)

  2. When the End User clicks the relevant button in your app UI, the auth-only dialog is then initiated with a url which contains the externalAuthId and solutionInstanceId obtained in steps 1 and 2:

    https://embedded.tray.io/external/auth/create/partnerName/solutionInstanceId/externalAuthId?code={authorizationCode}

    Remember that partnerName is set in the Profile section of the dashboard, as explained here.

    {authorizationCode} is the one-time use code that must be generated as per Create Config Wizard Authorization Code

    An example url would then be:

    https://embedded.tray.io/external/auth/create/acme/8b4fc48f-9fcd-43dw-ufu1-1b7a788983c6/external_slack_authentication?code=37d1a4fa990fb412efuh232310ad44ddbc5caed5d

    The End User will then be presented with an authentication dialog for the service being authenticated with.

    You can remove the tray.io domain and whitelabel the Config Wizard url. If you have done so then embedded.tray.io will be replaced with e.g. acme.integration-configuration.com
  3. When the dialog is completed, the authid will then be returned by the window as a postMessage which can be received by your app.

    The postMessage events are:

    • tray.authpopup.finish - this will contain the returned authId
    • tray.authpopup.close
    • tray.authPopup.error - when there was an error while creating/updating the auth.

    You can subscribe to these events from your application with a window.addEventListener in a similar way to for events from the Configuration Wizard, as explained here

5) You can now update the solutionInstance with the returned authid using the updateSolutionInstance mutation:

mutation {
updateSolutionInstance(input: {
solutionInstanceId: "8b4fc48f-xxx-xxx-ufu1-1b7a788983c6",
authValues: [{ externalId: "external_slack_authentication", authId: "aaa67786-xxx-xxx-xxx-97dedd1519b3" }]
}) {
solutionInstance {
id
name
enabled
created
}
}
}
  1. Enable the Solution Instance

Don't forget that once a Solution Instance has been created, the final step in activating it for an End User is to use the updateSolutionInstance mutation to set the status to 'enabled'.

Allowing users to edit their Authentications

Please also see our page on Mapping and Editing Auths.

If an End User needs to edit their authentication you can allow them to do this with the following url which accepts the above returned authid:

https://embedded.tray.io/external/auth/edit/partnerName/authId?code={authorizationCode}

Again, {authorizationCode} is the one-time use code that must be generated as per Create Config Wizard Authorization Code

Note that, if you are testing this and are listing a user's authentications, the Authentication Id is the first id to appear in the node, not the id within the service object:

Skipping Auth naming and settings

You can skip the title field of the authentication (it will be automatically named for you) by adding the skipTitleField=true query parameter to the above url.

For OAuth services (i.e. non-token-based) you can also skip the auth settings (i.e. login details) and go straight to the scopes page by using the skipAuthSettings=true query parameter.