Integrating Describo Online into another service - Arkisto-Platform/describo-online GitHub Wiki

Configuring Describo to allow another service to setup a user session

Describo Online can function in a mode where authentication is effectively delegated to another service. In this mode, all authentication is bypassed for a given session.

Setting up the configuration for the external service

The describo configuration to allow another service to instrument it is as follows:

{
    api: {
        "applications": [
            {
                "name": "{ the name of your application }",
                "secret": "{ a secret shared between describo and your application",
                "postCrateTo": {
                    "url": "https://{your url}",
                    "headers": { "Authorization": "Bearer yyy", "Content-Type": "application/json" }
                }
            }
        ]
    }
}
  • Set up an entry for your service in the configuration file under api/applications. This must be an array of objects each with a property name set to the full qualified domain name of the service and a property secret set to some long, random string.

Setting up the external service to call describo

  • In order to bypass okta, your service must first POST to https://{describo-online}/api/session/application a JSON object containing at minimum a name and an email.

    • The POST must set the headers:
      • Authorization: Bearer {your secret as defined in the configuration}
      • "Content-Type": "application/json"

The form of the POST is:

req.headers = {
    Authorization: "Bearer xxx",
    "Content-Type": "application/json",
}
req.body = JSON.stringify({
    email: "[email protected]",
    name: "John Citizen",
    service: {
        // s3: {
        //     provider: "Minio",
        //     url: "https://{your s3 endpoint}",
        //     folder: "development",
        //     awsAccessKeyId: "set key here",
        //     awsSecretAccessKey: "set secret here",
        //     region: "us-east-1",
        // },
        local: {
            folder: "{{ /path/to/folder/on/api }}",
        },
    },
    configuration: {
        allowProfileChange: false,
        allowServiceChange: false,
    },
    profile: {
        file: "schema.org",
    },
}),


In this example we're setting up a localhost backend session.

Specifically, we're also turning off profile changes and service changes in the session for this user.
  • The file test-iframe-mode.html is a good starting point to work from.
  • Also, see the test it should be able to create a session and login - bypassing okta auth @ api/src/routes/index.spec.js for an example.
  • If successful, a session identifier will be returned from describo online. Call describo-online inside an iframe as https://{describo-online}/application?sid={sessionId}. From that point on the session id will be used to identify the currently logged in user bypassing all okta authentication.
  • The application secret is not stored in the DB so it can be changed at anytime by changing in the configuration file and restarting describo online.

Instrumenting describo to automatically select a profile

If your service also includes the profile key in the body describo will try to load that profile for the session. The form is:

req.body = {
    email: "[email protected]",
    name: "John Citizen",
    ...
    profile: {
        file: "nyingarn-profile.json",
    },
}),

Ensure you have the profile installed on the API server.

Again, see test-iframe-mode.html for an example to work from.

Passing a profile to describo during session setup

You can also pass a profile to describo directly - that is, rather than loading one from the describo api server. The form is as follows

req.body = {
    email: "[email protected]",
    name: "John Citizen",
    ...
    profile: {
        inline: {
            // the profile goes here
        },
    },
}),

Again, see test-iframe-mode.html for an example to work from.

If your session setup has both file and inline defined in the profile key then inline is used in preference.

Instrumenting describo to disable resource and profile changes

If you want to prevent the user from changing the selected resource or profile that your application has set then add the configuration object as defined above ensuring that you set allowProfileChange and allowServiceChange to false.

Getting data back from Describo into your application

Describo can POST the crate back to your application whenever it saves the data back to disk. To configure this capability add a section postCrateTo into your application configuration as per the example. Set the headers section as your service requires them - Describo will use them as is.

Testing this out

There is a file called test-iframe-mode.html that you can use to test out this capability. Configure describo to allow an external party to create a session then copy the session id into line 10 of the file (update the value of the Authorization header). Be sure to change the host in line 7 to the URL of your service. Then, start an nginx container in this folder viz:

docker run -it  --rm  -v $PWD:/usr/share/nginx/html:ro -p 8080:80 nginx:latest

Finally, open http://localhost:8080/test-iframe-mode.html in your browser. If all is well describo should load into an iframe.