스튜디오 인증

구성할 때authenticationMastra 서버에서 Studio는 자동으로 로그인 화면을 표시하고 액세스 제어를 시행합니다. 하나의 구성으로 Studio UI와 API 경로를 모두 보호합니다.

인증이 없으면 Studio 및 모든 API 경로에 공개적으로 액세스할 수 있습니다.

Studio 인증을 사용하는 경우

• 여러 팀 구성원이 공유 Studio 배포를 통해 Agent, Workflow 및 Tool와 상호 작용해야 합니다.
• 권한은 Agent를 실행하거나 Workflow를 편집하거나 데이터세트를 삭제할 수 있는 사람을 제한해야 합니다.
• 로그인 화면(SSO, 이메일/비밀번호 또는 둘 다)을 통해 Studio 배포에 대한 액세스를 제어해야 합니다.

빠른 시작

Mastra 서버 구성에 인증 Provider를 추가합니다. 이 예제에서는 최소한의 설정을 위해 Simple Auth를 사용합니다.

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { SimpleAuth } from '@mastra/core/server'

export const mastra = new Mastra({
  server: {
    auth: new SimpleAuth({
      users: {
        'my-api-key': {
          id: 'user-1',
          name: 'Alice',
          role: 'admin',
        },
      },
    }),
  },
})

구성이 완료되면 Studio에 로그인 화면이 표시되고 모든 API 요청에 인증이 필요합니다. 지원되는 전체 Provider 목록은 인증 문서를 참조하세요.

작동 원리

server.auth를 설정하면 다음 두 가지가 동시에 적용됩니다.

• Studio UI: 로그인 화면을 표시합니다. Provider에 따라 사용자는 SSO, 이메일/비밀번호 또는 두 방식 모두로 로그인합니다.
• API 경로: 모든 내장 경로(/api/agents/*, /api/workflows/* 등)와 사용자 지정 경로에 인증이 필요합니다. Studio에서 보낸 요청이든 직접 API를 호출한 요청이든 동일하게 적용됩니다. Studio는 GET /api/auth/capabilities 엔드포인트를 호출하여 사용 가능한 기능을 감지합니다. 응답은 Studio에 렌더링할 로그인 방식을 알려주며, 사용자가 이미 인증된 경우 사용자 정보와 권한도 포함합니다.

URL을 통해 토큰 전달

Studio가 다른 애플리케이션에 삽입되거나 연결된 경우 auth_header URL 매개변수를 통해 인증 토큰을 전달할 수 있습니다. 외부 호스트가 이미 토큰을 보유하고 있고 로그인 화면을 표시하지 않은 채 인증된 Studio 세션을 열려는 경우 유용합니다. auth_header 값은 항상 Authorization 요청 헤더를 채웁니다. 이 매개변수는 해당 헤더 하나만 설정하므로 값에 Bearer처럼 서버에서 요구하는 스킴 접두사를 포함하세요. 쿼리 문자열에 토큰을 사용하여 Studio를 엽니다.

https://your-studio-host/?auth_header=Bearer%20your-token

Studio는 다음과 같이 토큰을 처리합니다.

• 로드할 때 auth_header를 한 번 읽고 해당 세션의 모든 API 요청에서 값을 Authorization 헤더로 전송합니다.
• 다른 쿼리 매개변수와 해시는 유지하면서 주소 표시줄에서 auth_header를 제거합니다.
• 토큰은 Memory에만 보관하고 로컬 스토리지에는 기록하지 않으므로 일시적이며 페이지를 다시 로드하면 유지되지 않습니다. 토큰은 URL 매개변수에 포함되므로 호스트 애플리케이션은 해당 URL이 생성되고 전송되는 방식을 담당합니다. URL 매개변수는 브라우저 기록, 리퍼러 헤더, 서버 액세스 로그를 통해 노출될 수 있습니다.

역할 기반 액세스 제어

RBAC를 사용하면 각 사용자가 Studio 내에서 보고 수행할 수 있는 작업을 제어할 수 있습니다. RBAC는 인증과 별개입니다. server.auth는 사용자가 누구인지 처리하고 server.rbac는 사용자가 무엇을 할 수 있는지 처리합니다.

기본 역할

Mastra에는 네 가지 기본 역할이 포함되어 있습니다. 다음에서 가져오세요.@mastra/core/auth/ee:

역할	권한
owner	전체 접근 권한(*)
admin	읽기, 쓰기 및 실행
member	읽기 및 실행
viewer	읽기 전용

RBAC 활성화

기본 역할과 함께 StaticRBACProvider를 사용하거나 자체 역할을 정의하세요.

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { SimpleAuth } from '@mastra/core/server'
import { StaticRBACProvider, DEFAULT_ROLES } from '@mastra/core/auth/ee'

export const mastra = new Mastra({
  server: {
    auth: new SimpleAuth({
      users: {
        'admin-key': { id: 'user-1', name: 'Alice', role: 'admin' },
        'viewer-key': { id: 'user-2', name: 'Bob', role: 'viewer' },
      },
    }),
    rbac: new StaticRBACProvider({
      roles: DEFAULT_ROLES,
      getUserRoles: user => [user.role],
    }),
  },
})

RBAC가 활성화되면 Studio는 사용자에게 권한이 없는 작업을 숨깁니다. 시청자에게는 삭제 버튼이 표시되지 않습니다. 구성원은 Agent 구성을 수정할 수 없습니다.

권한 형식

권한은 {resource}:{action} 패턴을 따르며, 선택적으로 리소스 수준 범위를 지정할 수 있습니다.

패턴	의미
*	모든 항목에 대한 전체 접근 권한
*:read	모든 리소스 읽기
agents:*	Agent에 대한 모든 작업
agents:execute	Agent 실행만 허용
agents:read:my-id	ID로 특정 Agent 읽기
리소스에는 agents, workflows, tools, datasets, memory, scores, observability 등이 포함됩니다. 작업은 read, write, execute, delete입니다.

외부 공급자 역할 매핑

ID 공급자가 이미 역할(예: 사무원 조직 또는 WorkOS 그룹)을 정의한 경우 이를 다음을 사용하여 Mastra 권한에 매핑합니다.roleMapping:

src/mastra/index.ts

import { StaticRBACProvider } from '@mastra/core/auth/ee'

const rbac = new StaticRBACProvider({
  roleMapping: {
    'org:admin': ['*'],
    'org:member': ['*:read', '*:execute'],
    'org:viewer': ['*:read'],
  },
  getUserRoles: user => user.providerRoles,
})

로그인 방법

Studio는 인증 공급자를 기반으로 로그인 화면을 조정합니다.

제공자 유형	로그인 UI
SSO 전용	SSO 버튼(예: "WorkOS로 로그인")
자격 증명만	이메일 및 비밀번호 양식
둘 다	SSO 버튼 및 이메일/비밀번호 양식

공급자별로 가입을 활성화하거나 비활성화할 수 있습니다. 비활성화되면 Studio는 가입 링크를 숨기고 로그인 양식을 강제로 표시합니다.

EE 라이선스

Studio 인증 기능(SSO 로그인, RBAC, 권한 기반 UI)은 Mastra Enterprise Edition의 일부입니다. 단순 인증을 사용하거나 로컬로 실행할 때 라이선스는 선택 사항입니다. 타사 공급자를 사용한 프로덕션 배포에는 유효한 EE 라이선스가 필요합니다.Mastra sales.

관련된

• 인증 개요: 지원되는 인증 Provider의 전체 목록입니다.
• 스튜디오 배포: Studio를 프로덕션에 배포합니다.
• 커스텀 API 경로: 개별 엔드포인트의 인증을 제어합니다.