useCreateBotConsumptionPageWithAuth()

Learn about the useCreateBotConsumptionPageWithAuth() hook and how to enhance your embedded MicroStrategy Bot interactions with authentication in your React applications using the `embed-dossier-mstr-react` package.

Import

import { useCreateBotConsumptionPageWithAuth } from "embed-dossier-mstr-react"

Parameters

The hook accepts a single object parameter with the following properties:

Parameter	Type	Required	Description
`serverUrlLibrary`	`string`	Yes	The base URL of the MicroStrategy Library server
`placeholder`	`HTMLDivElement \| null`	Yes	DOM element where the bot interface will be rendered
`projectId`	`string`	Yes	The ID of the MicroStrategy project to connect to
`objectId`	`string`	Yes	The ID of the MicroStrategy bot object to embed
`config`	`Omit<EmbedBotConsumptionPageConfig, "placeholder" \| "serverUrl" \| "projectId" \| "objectId">`	Yes	Configuration options for the bot consumption page
`loginMode`	`"guest" \| "standard" \| "saml" \| "oidc" \| "ldap"`	Yes	The authentication method to use
`username`	`string`	For 'standard' and 'ldap'	Username for authentication (required for standard and LDAP authentication)
`password`	`string`	For 'standard' and 'ldap'	Password for authentication (required for standard and LDAP authentication)

Return Values

The hook returns an object with the following properties:

Return Value	Type	Description
`botConsumptionPage`	`EmbedBotConsumptionPage \| null`	The instantiated bot page object, which can be used to interact with the bot programmatically, or `null` if not yet created
`isAuthenticated`	`boolean`	Whether authentication was successful
`isAuthenticating`	`boolean`	Whether authentication is currently in progress
`error`	`string \| null`	Error message if authentication failed, or `null` if no error

Authentication Methods

The hook supports multiple authentication methods:

Guest Authentication

Uses MicroStrategy's guest access feature without requiring credentials. Ideal for public bot interfaces.

Standard Authentication

Uses MicroStrategy's standard username/password authentication. Requires both username and password parameters.

LDAP Authentication

Similar to standard authentication but uses LDAP directory service. Requires both username and password parameters.

SAML Authentication

Implements Security Assertion Markup Language (SAML) single sign-on authentication. No additional parameters required, but will redirect the user to the identity provider's login page.

OIDC Authentication

Implements OpenID Connect (OIDC) authentication. No additional parameters required, but will redirect the user to the OIDC provider's login page.

How It Works

The useCreateBotConsumptionPageWithAuth hook:

Uses the useLoadMstrSDK hook to load the MicroStrategy SDK
Handles authentication based on the specified loginMode
Creates a bot consumption page instance with authentication configuration
Manages authentication and bot creation state
Returns the bot instance and authentication state

Basic Usage

Here's a simple example of using the useCreateBotConsumptionPageWithAuth hook directly:

import { useRef } from "react"
import { useCreateBotConsumptionPageWithAuth } from "embed-dossier-mstr-react"

const MyAuthenticatedBotInterface = () => {
  const divRef = useRef<HTMLDivElement>(null)

  const { botConsumptionPage, isAuthenticated, isAuthenticating, error } =
    useCreateBotConsumptionPageWithAuth({
      serverUrlLibrary: "https://demo.microstrategy.com/MicroStrategyLibrary",
      placeholder: divRef.current,
      projectId: "B19DEDCC11D4E0EFC000EB9495D0F44F",
      objectId: "D9AB3763ED4BAD952F57A586DC888758",
      config: {
        containerHeight: "600px",
        containerWidth: "100%",
      },
      loginMode: "standard",
      username: "jsmith",
      password: "password123",
    })

  if (isAuthenticating) {
    return <div>Authenticating and loading bot interface...</div>
  }

  if (error) {
    return <div className="error-container">{error}</div>
  }

  if (!isAuthenticated) {
    return <div>Authentication failed</div>
  }

  return (
    <div>
      {isAuthenticated && botConsumptionPage ? (
        <div>Bot interface loaded successfully!</div>
      ) : null}
      <div ref={divRef} style={{ height: "600px", width: "100%" }} />
    </div>
  )
}

Advanced Usage

Handling Different Authentication Methods

import { useRef, useState } from "react"
import { useCreateBotConsumptionPageWithAuth } from "embed-dossier-mstr-react"

const AuthMethodSelector = () => {
  const divRef = useRef<HTMLDivElement>(null)
  const [authMethod, setAuthMethod] = useState<
    "guest" | "standard" | "saml" | "oidc" | "ldap"
  >("guest")
  const [credentials, setCredentials] = useState({ username: "", password: "" })

  const { botConsumptionPage, isAuthenticated, isAuthenticating, error } =
    useCreateBotConsumptionPageWithAuth({
      serverUrlLibrary: "https://demo.microstrategy.com/MicroStrategyLibrary",
      placeholder: divRef.current,
      projectId: "B19DEDCC11D4E0EFC000EB9495D0F44F",
      objectId: "D9AB3763ED4BAD952F57A586DC888758",
      config: {
        containerHeight: "600px",
        containerWidth: "100%",
      },
      loginMode: authMethod,
      username: credentials.username,
      password: credentials.password,
    })

  const handleAuthMethodChange = (
    method: "guest" | "standard" | "saml" | "oidc" | "ldap"
  ) => {
    setAuthMethod(method)
  }

  const handleCredentialChange = (
    field: "username" | "password",
    value: string
  ) => {
    setCredentials((prev) => ({ ...prev, [field]: value }))
  }

  return (
    <div className="auth-bot-container">
      <div className="auth-controls">
        <h3>Authentication Method</h3>
        <div className="auth-method-buttons">
          <button onClick={() => handleAuthMethodChange("guest")}>Guest</button>
          <button onClick={() => handleAuthMethodChange("standard")}>
            Standard
          </button>
          <button onClick={() => handleAuthMethodChange("ldap")}>LDAP</button>
          <button onClick={() => handleAuthMethodChange("saml")}>SAML</button>
          <button onClick={() => handleAuthMethodChange("oidc")}>OIDC</button>
        </div>

        {(authMethod === "standard" || authMethod === "ldap") && (
          <div className="credentials-form">
            <input
              type="text"
              placeholder="Username"
              value={credentials.username}
              onChange={(e) =>
                handleCredentialChange("username", e.target.value)
              }
            />
            <input
              type="password"
              placeholder="Password"
              value={credentials.password}
              onChange={(e) =>
                handleCredentialChange("password", e.target.value)
              }
            />
          </div>
        )}
      </div>

      <div className="status-display">
        {isAuthenticating && <div className="loading">Authenticating...</div>}
        {error && <div className="error">{error}</div>}
        {isAuthenticated && (
          <div className="success">Authentication successful!</div>
        )}
      </div>

      <div ref={divRef} style={{ height: "600px", width: "100%" }} />
    </div>
  )
}

Using Bot Methods After Authentication

import { useEffect, useRef } from "react"
import { useCreateBotConsumptionPageWithAuth } from "embed-dossier-mstr-react"

const InteractiveAuthenticatedBot = () => {
  const divRef = useRef<HTMLDivElement>(null)

  const { botConsumptionPage, isAuthenticated } =
    useCreateBotConsumptionPageWithAuth({
      serverUrlLibrary: "https://demo.microstrategy.com/MicroStrategyLibrary",
      placeholder: divRef.current,
      projectId: "B19DEDCC11D4E0EFC000EB9495D0F44F",
      objectId: "D9AB3763ED4BAD952F57A586DC888758",
      config: {
        containerHeight: "600px",
        containerWidth: "100%",
      },
      loginMode: "guest",
    })

  // Example of using the bot page instance after authentication
  useEffect(() => {
    if (botConsumptionPage && isAuthenticated) {
      // Set up event listeners or perform initialization
      console.log("Bot consumption page authenticated and ready")
    }
  }, [botConsumptionPage, isAuthenticated])

  const handleSendQuestion = (question: string) => {
    if (
      botConsumptionPage &&
      isAuthenticated &&
      botConsumptionPage.sendMessage
    ) {
      botConsumptionPage.sendMessage(question)
    }
  }

  const predefinedQuestions = [
    "What were our top-selling products last quarter?",
    "Show me sales by region",
    "Compare this month's performance to last month",
  ]

  return (
    <div className="interactive-bot-container">
      <div className="question-buttons">
        {predefinedQuestions.map((question, index) => (
          <button
            key={index}
            onClick={() => handleSendQuestion(question)}
            disabled={!isAuthenticated || !botConsumptionPage}
          >
            {question}
          </button>
        ))}
      </div>

      <div ref={divRef} style={{ height: "600px", width: "100%" }} />
    </div>
  )
}

Error Handling

The hook provides comprehensive error handling for authentication failures:

import { useRef, useState } from "react"
import { useCreateBotConsumptionPageWithAuth } from "embed-dossier-mstr-react"

const BotWithErrorHandling = () => {
  const divRef = useRef<HTMLDivElement>(null)
  const [credentials, setCredentials] = useState({
    username: "jsmith",
    password: "password123",
  })

  const { isAuthenticating, error, isAuthenticated } =
    useCreateBotConsumptionPageWithAuth({
      serverUrlLibrary: "https://demo.microstrategy.com/MicroStrategyLibrary",
      placeholder: divRef.current,
      projectId: "B19DEDCC11D4E0EFC000EB9495D0F44F",
      objectId: "D9AB3763ED4BAD952F57A586DC888758",
      config: {
        containerHeight: "600px",
        containerWidth: "100%",
      },
      loginMode: "standard",
      username: credentials.username,
      password: credentials.password,
    })

  const handleRetry = () => {
    window.location.reload()
  }

  if (isAuthenticating) {
    return <div className="loading-state">Authenticating...</div>
  }

  if (error) {
    // Handle specific error cases
    if (error.includes("credentials")) {
      return (
        <div className="credential-error">
          <h3>Invalid Credentials</h3>
          <p>Please check your username and password and try again.</p>
          <button onClick={handleRetry}>Try Again</button>
        </div>
      )
    }

    // Handle SAML/OIDC popup blocker errors
    if (error.includes("popups")) {
      return (
        <div className="popup-error">
          <h3>Popup Blocked</h3>
          <p>
            Please enable popups in your browser to continue with
            authentication.
          </p>
          <button onClick={handleRetry}>Try Again</button>
        </div>
      )
    }

    // General error case
    return (
      <div className="general-error">
        <h3>Authentication Failed</h3>
        <p>{error}</p>
        <button onClick={handleRetry}>Try Again</button>
      </div>
    )
  }

  return (
    <div className="bot-container">
      {isAuthenticated ? (
        <div className="auth-success-banner">Authentication successful!</div>
      ) : null}
      <div ref={divRef} style={{ height: "700px", width: "100%" }} />
    </div>
  )
}

Implementation Details

Behind the scenes, the hook implements different authentication flows:

Standard/LDAP Authentication: Sends a POST request to the /api/auth/login endpoint with username and password
Guest Authentication: Sends a POST request to the /api/auth/login endpoint with guest login mode
SAML/OIDC Authentication: Uses the MicroStrategy SDK to initiate the single sign-on process
Token Management: Automatically fetches and refreshes authentication tokens as needed

After successful authentication, the hook configures the bot consumption page with enableCustomAuthentication: true and customAuthenticationType: AUTH_TOKEN for secure communication.

Security Best Practices

When using this hook, follow these security best practices:

Never hardcode credentials - Store sensitive information in environment variables or a secure credential store
Use HTTPS - Always use encrypted connections for bot embedding
Set appropriate timeouts - Configure session timeouts based on your security requirements
Consider SSO - Prefer SAML or OIDC for production environments to avoid handling credentials directly
Implement backend proxy - For maximum security, handle authentication on your backend server

BotConsumptionPageWithAuth - A component that uses this hook internally
BotConsumptionPage - A simpler component for unauthenticated bot interfaces

useCreateBotConsumptionPage - Basic bot creation hook without authentication
useCreateDashboardWithAuth - Similar hook for authenticated dashboards
useLoadMstrSDK - Used internally to load the MicroStrategy SDK

useCreateBotConsumptionPage()

Types and Interfaces

useCreateBotConsumptionPageWithAuth()

Import

Parameters

Return Values

Authentication Methods

Guest Authentication

Standard Authentication

LDAP Authentication

SAML Authentication

OIDC Authentication

How It Works

Basic Usage

Advanced Usage

Handling Different Authentication Methods

Using Bot Methods After Authentication

Error Handling

Implementation Details

Security Best Practices

On this page

This content

useCreateBotConsumptionPageWithAuth()

Import

Parameters

Return Values

Authentication Methods

Guest Authentication

Standard Authentication

LDAP Authentication

SAML Authentication

OIDC Authentication

How It Works

Basic Usage

Advanced Usage

Handling Different Authentication Methods

Using Bot Methods After Authentication

Error Handling

Implementation Details

Security Best Practices

Related Components

Related Hooks

On this page

This content