Prerequisite configuration for using the GraphQL playground is not documented

[seanthegeek]

Description

The prerequisite OpenCTI configuration for using the GraphQL Playground is not documented, which makes it difficult to learn GraphQL and build GraphQL queries. I didn't learn about the configuration requirements until I searched GitHub.

#6992
#6896

• Playground button should not be offered when the configuration environment variable called APP__GRAPHQL__PLAYGROUND__FORCE_DISABLED_INTROSPECTION is set to its default value of true.
• The Playground interface should fail gracefully and provide feedback about what is failing and why, rather than attempting to make queries and failing over and over with generic error messages
• The requirement to set APP__GRAPHQL__PLAYGROUND__FORCE_DISABLED_INTROSPECTION to false should be included in the [documentation for the playground[(https://docs.opencti.io/latest/development/api-usage/), and the security implications of making the change should be fully explained in the documentation
• The configuration documentation should use proper English grammar, and fully explain the impact of the configuration option

Environment

1. OS (where OpenCTI server runs): Debian 12
2. OpenCTI version: 6.3.4
3. OpenCTI client: Frontend

Reproducible Steps

Steps to create the smallest reproducible scenario:

Click on the Playground button at the bottom of your user profile settings page or navigate to the /graphql URI endpoint in a web browser.

Expected Output

The GraphQL Playground should function as described in the OpenCTI [documentation(https://docs.opencti.io/latest/development/api-usage/).

Actual Output

The output of the Playground is

{
  "error": "Response not successful: Received status code 500"
}

The result of the browser's POST request to /graphql is

{
    "errors": [
        {
            "message": "Internal server error",
            "extensions": {
                "code": "INTERNAL_SERVER_ERROR"
            },
            "name": "INTERNAL_SERVER_ERROR"
        }
    ]
}

The output of sudo docker logs opencti-opencti-1 is:

Unexpected error processing request: GraphQL introspection not authorized!

This error occurs even if the user is in the Administrators group and the Content-Type and Authorization headers are pasted into the HTTP headers section of the playground UI.

A search of the documentation for introspection shows a configuration environment variable called APP__GRAPHQL__PLAYGROUND__FORCE_DISABLED_INTROSPECTION with a default value of true. It has the description "Introspection is allowed to auth users but can be disabled in needed". This is not proper English grammar, so I'm not exactly sure what this option does, or the security impact is of setting it to false.

When APP__GRAPHQL__PLAYGROUND__FORCE_DISABLED_INTROSPECTION is set to false the errors disappear, but the code suggestion list after typing query is blank.

[nino-filigran]

@seanthegeek thank you for you request: so basically if I understand, this is less a bug, but rather a need for documentation.
The only fix we should provide is in UI, not to offer the possibility to click on Playground, if you have set it up (on the top of improving the documentation).

[seanthegeek]

Correct.

[seanthegeek]

This request may not be relevant anymore. @richard-julien said the Playground will be replaced.

#8600 (comment)

See #7363

That said, there is a need for much more detailed documentation about how to use GraphQL and how to build connectors.

[richard-julien]

I think this ask for documentation is still interesting. The playground will be replace but the introspection will still be disable by default to be "secure by default".