MVP Architectural Design and Design Specs

[nicholas-gcc]

• Decide on whether to use DialogFlow Webhooks (https://cloud.google.com/dialogflow/es/docs/fulfillment-webhook?hl=en)
• Decide on supported Auth0 Management API endpoints (https://auth0.com/docs/api/management/v2)
• Draw sequence diagrams and API diagrams, class diagrams if necessary

[nicholas-gcc]

QueryBot for Auth0 - Functional Specification

1. Overview

• Summary: A querying tool that uses natural human language to retrieve data from an Auth0 tenant on-the-fly
• Objective: Non-technical staff can fetch Auth0 data without waiting for engineering support, saving time for both teams and minimizing interruptions. Data retrieval will be simpler and can be done on the fly, and teams can access Auth0 data where they already communicate - on Slack - avoiding the need to context-switch

2. Use Cases

• Use Case ID: [UC-001]

  • Name: User Queries for Information
  • Description: Administrative staff member enters a query in natural language (e.g., "user details for nicholasgcc@gmail.com") through Slack to retrieve user details.
  • Priority: High
  • Actors: Admin
  • Pre-Conditions: The user is logged into Slack and has access to the appropriate workspace/channel with proper authorization to Management API
  • Post-Conditions: The Slack bot sends a response with the requested user information.

• Use Case ID: [UC-002]

  • Name: Slack App must be authorized to use Management API
  • Description: Slack App must be able to securely store client credentials to make a client credentials request to an Auth0 Machine-to-Machine application and request for a Management API access token
  • Priority: High
  • Actors: Application
  • Pre-Conditions: The application must be able to securely store client credentials to forward to Auth0's /oauth/token endpoint
  • Post-Conditions: Slack App will have the necessary Management API token to make future Management API requests

• Use Case ID: [UC-003]

  • Name: Management API Requests via Prompts
  • Description: A user inputs various prompts to perform simple Auth0 Management API operations, such as "please get me details for auth0|1234" and must be matched by the application to the correct Management API call
  • Priority: High
  • Actors: Application and User
  • Pre-Conditions: Slack bot is integrated and operational
  • Post-Conditions: Appropriate Management API requests are issued, and data is returned via Slack.

• Use Case ID: [UC-004]

  • Name: User Guidance
  • Description: A user should be able to understand the scope of what queries and operations are and aren't supported
  • Priority: Normal
  • Actors: User
  • Pre-Conditions: Slack application must be functional and authorized to access the workspace
  • Post-Conditions: User has a means of querying or getting help on basic usage of the application

• Use Case ID: [UC-005]

  • Name: Gracefully handle invalid prompts
  • Description: A user inputs an invalid prompt or query
  • Priority: Normal
  • Actors: User
  • Pre-Conditions: DialogFlow must be able to recognise unmatchable intents and send a fallback message
  • Post-Conditions: User is informed of the error and is sent to a help/instructions prompt

• Use Case ID: [UC-006]

  • Name: Extending to more Management API requests
  • Description: Users can ask for other Auth0 Management API data like application details, connections, etc.
  • Priority: Low
  • Actors: User
  • Pre-Conditions: The Slack bot has appropriate scopes and permissions configured.
  • Post-Conditions: Relevant data is returned as requested.

3. Requirements

Functional Requirements

1. NLP Parsing

   • The system should interpret human-readable prompts and determine the appropriate Auth0 Management API request.
   • Examples: Detect variations in phrasing such as "Get user details for…" or "Show info about user…"

2. Slack Bot Integration

   • The system should integrate seamlessly with Slack and respond to user queries, specifically in Slack Direct Messages
   • The system should be able to handle, receive and listen for Slack events (in particular, messages and slash commands)

3. Authorization with Auth0

   • The bot should securely authorize itself with an Auth0 Machine-to-Machine application with permissions to the Management API to retrieve the appropriate access tokens
   • Auth0 access tokens should be refreshed automatically before expiry.

4. Execute Management API Requests

   • Depending on the parsed user request, the bot should execute the appropriate Management API call and return structured data.

5. Error Handling

   • Handle situations like insufficient permissions, invalid inputs, or API errors, and provide informative messages to users.

Non-Functional Requirements

1. Performance

   • Queries should be parsed and responded to within an acceptable time frame (e.g., <5 seconds, for a start).

2. Security

   • API tokens must be managed securely, ensuring they are refreshed regularly and not exposed in logs.
   • Communication between Slack, DialogFlow, and Auth0 should use secure channels.

3. Maintainability

   • The NLP models should be easily updatable to improve understanding of user prompts over time.
   • Code should be modular to accommodate changes, such as adding new Management API request types.

4. Usability

   • The system should provide simple and clear error messages and help instructions to non-technical users.
   • Responses should be easy to understand, avoiding technical jargon wherever possible.

6. Timeline & Priority

• See https://github.com/users/nicholas-gcc/projects/1

6. Additional Notes

• Dependencies: Python FastAPI, Auth0 Management API, DialogFlow ES, Slack Events API
• Out of Scope: Any query that corresponds to a POST/PUT/PATCH/DELETE Management API request. Those are sensitive operations and should be handled with proper adherence to Management API specifications