View source for Implementation:Langgenius Dify Service Access Control

{{PageInfo|type=Implementation|title=Langgenius_Dify_Service_Access_Control}}
{| class="wikitable" style="float:right; margin-left:1em; width:300px;"
|-
! Knowledge Sources
|
* [https://github.com/langgenius/dify Langgenius_Dify]
|-
! Domains
| [[domain::Frontend]], [[domain::API_Service]]
|-
! Last Updated
| [[last_updated::2026-02-12 07:00 GMT]]
|}

== Overview ==

React Query hooks for managing webapp access control, including whitelist subject management, candidate search with infinite scrolling, access mode updates, and user access verification.

=== Description ===

'''access-control.ts''' provides React Query hooks for the enterprise '''webapp access control''' system. It defines four hooks: '''useAppWhiteListSubjects''' fetches the groups and members currently whitelisted for a specific app; '''useSearchForWhiteListCandidates''' uses '''useInfiniteQuery''' to provide paginated search results for candidate subjects (users and groups) that can be added to a whitelist, supporting '''infinite scrolling''' via the '''getNextPageParam''' callback; '''useUpdateAccessMode''' is a '''useMutation''' hook that updates an app's access mode (e.g., public, whitelist-only) and automatically invalidates the whitelist subjects query cache on success; and '''useGetUserCanAccessApp''' checks whether the current user has permission to access a specific app, conditionally calling '''getUserCanAccess''' from the share service only when '''systemFeatures.webapp_auth.enabled''' is true (otherwise returning '''{ result: true }'''). All hooks use the '''"access-control"''' namespace for query keys and set '''staleTime: 0''' and '''gcTime: 0''' where fresh data is critical.

=== Usage ===

Use these hooks in enterprise webapp access control settings pages. '''useAppWhiteListSubjects''' and '''useSearchForWhiteListCandidates''' are used in the whitelist management UI. '''useUpdateAccessMode''' is used when toggling between public and restricted access modes. '''useGetUserCanAccessApp''' is used as a guard to verify user permissions before rendering app content.

== Code Reference ==

=== Source Location ===
* '''Repository:''' [https://github.com/langgenius/dify Langgenius_Dify]
* '''File:''' [https://github.com/langgenius/dify/blob/main/web/service/access-control.ts web/service/access-control.ts]
* '''Lines:''' 1-87

=== Signature ===
<syntaxhighlight lang="typescript">
export const useAppWhiteListSubjects = (
  appId: string | undefined,
  enabled: boolean
) => UseQueryResult<{ groups: AccessControlGroup[], members: AccessControlAccount[] }>

export const useSearchForWhiteListCandidates = (
  query: { keyword?: string, groupId?: AccessControlGroup['id'], resultsPerPage?: number },
  enabled: boolean
) => UseInfiniteQueryResult<SearchResults>

export const useUpdateAccessMode = () => UseMutationResult<
  unknown,
  unknown,
  UpdateAccessModeParams
>

export const useGetUserCanAccessApp = (params: {
  appId?: string,
  isInstalledApp?: boolean,
  enabled?: boolean
}) => UseQueryResult<{ result: boolean }>
</syntaxhighlight>

=== Import ===
<syntaxhighlight lang="typescript">
import {
  useAppWhiteListSubjects,
  useSearchForWhiteListCandidates,
  useUpdateAccessMode,
  useGetUserCanAccessApp,
} from '@/service/access-control'
</syntaxhighlight>

== I/O Contract ==

=== Inputs ===
{| class="wikitable"
|-
! Name !! Type !! Required !! Description
|-
| appId || string or undefined || Varies || Application ID to query whitelist or access permissions for
|-
| enabled || boolean || Yes || Controls whether the query is active
|-
| query.keyword || string || No || Search keyword for filtering whitelist candidates
|-
| query.groupId || string || No || Group ID to filter candidates within a specific group
|-
| query.resultsPerPage || number || No || Number of results per page for paginated search
|-
| isInstalledApp || boolean || No || Whether the app is an installed app (defaults to true)
|-
| params.subjects || Array || No || Subjects to add/remove in access mode update
|-
| params.accessMode || AccessMode || Yes (mutation) || The access mode to set (e.g., public, whitelist)
|}

=== Outputs ===
{| class="wikitable"
|-
! Name !! Type !! Description
|-
| groups || AccessControlGroup[] || Array of groups in the app whitelist
|-
| members || AccessControlAccount[] || Array of member accounts in the app whitelist
|-
| SearchResults || { currPage, totalPages, subjects, hasMore } || Paginated search results for whitelist candidates
|-
| result || boolean || Whether the current user can access the app
|}

== Usage Examples ==

=== Fetch Whitelist Subjects ===
<syntaxhighlight lang="typescript">
import { useAppWhiteListSubjects } from '@/service/access-control'

function WhitelistPanel({ appId }: { appId: string }) {
  const { data, isLoading } = useAppWhiteListSubjects(appId, true)

  if (isLoading) return <Spinner />

  return (
    <div>
      <h3>Groups: {data?.groups.length}</h3>
      <h3>Members: {data?.members.length}</h3>
    </div>
  )
}
</syntaxhighlight>

=== Update Access Mode ===
<syntaxhighlight lang="typescript">
import { useUpdateAccessMode } from '@/service/access-control'

function AccessModeToggle({ appId }: { appId: string }) {
  const { mutate } = useUpdateAccessMode()

  const handleToggle = (mode: AccessMode) => {
    mutate({ appId, accessMode: mode })
  }

  return <button onClick={() => handleToggle('whitelist')}>Restrict Access</button>
}
</syntaxhighlight>

== Related Pages ==

* [[implemented_by_principle::Principle:Langgenius_Dify_Access_Control]]
* [[Langgenius_Dify_Service_Base]] - HTTP wrappers used by query functions
* [[Langgenius_Dify_Service_Explore]] - getAppAccessModeByAppId used for installed app access checks

[[Category:Implementations]]