> For the complete documentation index, see [llms.txt](https://docs.panther.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.panther.com/ko/panther/api/graphql/user-management.md).

# 사용자 및 역할 관리

## 개요

Panther API는 다음 사용자 및 역할 작업을 지원합니다:

* 사용자 목록
* ID 또는 이메일 주소로 사용자 가져오기
* 새 사용자 초대
* 사용자의 정보 및 역할 업데이트
* 사용자 삭제
* 역할 목록
* ID 또는 이름으로 역할 가져오기
* 새 역할 생성
* 역할의 정보 및 권한 업데이트
* 역할 삭제

Console의 API Playground 또는 GraphQL-over-HTTP API를 사용하여 Panther의 API를 호출할 수 있습니다. 이러한 방법에 대해 자세히 알아보려면 [Panther API](/ko/panther/api.md#step-1-choose-a-method-for-invoking-the-api).

핵심 사용자 및 역할 관리 작업에 대한 GraphQL 쿼리, 뮤테이션, 엔드투엔드 워크플로 예시는 아래 섹션을 참조하세요.

## 일반적인 사용자 및 역할 관리 작업

아래는 Panther에서 가장 일반적인 GraphQL 사용자 및 역할 관리 작업 중 일부입니다. 이 예시는 GraphQL 클라이언트(또는 `curl`)를 사용하여 Panther의 GraphQL API를 호출할 때 보내야 하는 문서를 보여줍니다.

참고:  `createdAt` 필드는 ISO 8601 날짜 및 시간 표준을 따릅니다.

#### 사용자 목록 조회

```graphql
query users {
  users {
    id
    givenName
    familyName
    email
    status
    createdAt
    lastLoggedInAt
    role {
      name
      id
      권한
    }
  }
}
```

#### 사용자 가져오기

{% tabs %}
{% tab title="이메일 주소로 사용자" %}

```graphql
query user {
  userByEmail(email: "example@domain.com") {
    id
    givenName
    familyName
    email
    role {
      name
      id
      권한
    }
    status
    createdAt
  }
}
```

{% endtab %}

{% tab title="ID로 사용자" %}

```graphql
query user {
  userById(id: "8h81hfh-ij828db") {
    id
    givenName
    familyName
    email
    role {
      name
      id
      권한
    }
    status
    createdAt
  }
}
```

{% endtab %}
{% endtabs %}

#### 새 사용자 초대

```graphql
mutation inviteUser {
    inviteUser(input: {
        email: "example@domain.com"
        givenName: "firstname"
        familyName: "lastname"
        role: {
            kind: NAME
            value: "Analyst"
        }
    })
    {
        user {
            id
            status
        }
    }
  }
```

#### 사용자 업데이트

```graphql
mutation updateUser {
    updateUser(input: {
        id: "8h81hfh-ij828db"
        familyName: "newName"
    })
    {
        user {
            email
            givenName
            familyName
        }
    }
}
```

#### 사용자 삭제

```graphql
mutation deleteUser{
  deleteUser(input: {
    id: "8h81hfh-ij828db"
  })
  {
    id # 삭제 작업은 `user` 객체를 반환하지 않습니다. ID만 반환합니다.
  }
}
```

#### 역할 목록 조회

```graphql
query roles {
  roles( 
    # 이 입력은 선택 사항입니다. 입력이 없으면 쿼리는 모든 역할을 반환합니다.
    input: {
      nameContains: "admin",
      sortDir: ascending
    }) 
  {
    createdAt
    id
    name
    권한
    updatedAt
    updatedBy {
      ... on User {
        email
        id
      }
      ... on APIToken {
        id
        name
      }
    }
    # 로그 유형별 RBAC가 활성화된 경우에만 사용됩니다.
    logTypeAccess 
    logTypeAccessKind
  }
}
```

#### 역할 가져오기

{% tabs %}
{% tab title="이름으로 역할" %}

```graphql
query adminRole {
  roleByName(
   name: "admin"
   ) {
    createdAt
    id
    name
    권한
    updatedAt
    updatedBy {
      ... on User {
        email
        id
      }
      ... on APIToken {
        id
        name
      }
    }
    # 로그 유형별 RBAC가 활성화된 경우에만 사용됩니다.
    logTypeAccess 
    logTypeAccessKind
  }
}
```

{% endtab %}

{% tab title="ID로 역할" %}

```graphql
query adminRole {
  roleById(
   id: "feeafade-c545"
   ) {
    createdAt
    id
    logTypeAccess
    logTypeAccessKind
    name
    권한
    updatedAt
    updatedBy {
      ... on User {
        email
        id
      }
      ... on APIToken {
        id
        name
      }
    }
    # 로그 유형별 RBAC가 활성화된 경우에만 사용됩니다.
    logTypeAccess 
    logTypeAccessKind
  }
}
```

{% endtab %}
{% endtabs %}

#### 새 역할 생성

{% hint style="warning" %}
**참고:** 권한 `UserModify` Panther 플랫폼에 대한 전체 관리자 액세스를 제공합니다. 이 권한을 새 역할에 할당할 때는 신중하게 사용하세요.
{% endhint %}

{% tabs %}
{% tab title="기본" %}

```graphql
mutation createRole {
  createRole(input: {
    name: "new-role"
    permissions: [
      UserRead
      AlertRead
    ]
  })
  {  
    role {
      name
      id
      권한
    }
  }
}
```

{% endtab %}

{% tab title="로그 유형별 RBAC 활성화" %}

```graphql
mutation createRole {
  createRole(input: {
    name: "new-role"
    permissions: [
      UserRead
      AlertRead
    ]
    # 로그 유형별 RBAC 기능이 활성화된 경우에만 사용됩니다.
    logTypeAccess:["AWS.ALB"]
    logTypeAccessKind: ALLOW
  })
  {  
    role {
      name
      id
      권한
      logTypeAccess
      logTypeAccessKind
    }
  }
}
```

{% endtab %}
{% endtabs %}

#### 역할 업데이트

{% hint style="warning" %}
**참고:** updateRole 입력의 권한에는 **모든** 역할에 대한 원하는 권한.
{% endhint %}

{% tabs %}
{% tab title="기본" %}

```graphql
mutation updateRole {
  updateRole(input: {
    id: "fea8sje-92jdnhc"
    name: "updated-role-name"
    permissions: [
      UserRead
      AlertRead
      AlertModify
    ]
  })
  {
    role {
      name
      id
      권한
    }
  }
}
```

{% endtab %}

{% tab title="로그 유형별 RBAC 활성화" %}

```graphql
mutation updateRole {
  updateRole(input: {
    id: "fea8sje-92jdnhc"
    name: "updated-role-name"
    permissions: [
      UserRead
      AlertRead
      AlertModify
    ]
    # 로그 유형별 RBAC 기능이 활성화된 경우에만 사용됩니다.
    logTypeAccess:["AWS.ALB"]
    logTypeAccessKind: DENY
  })
  {
    role {
      name
      id
      권한
      logTypeAccess 
      logTypeAccessKind
    }
  }
}
```

{% endtab %}
{% endtabs %}

#### 역할 삭제

```graphql
mutation deleteRole {
  deleteRole(input: {
    id: "e146c8d8-c6a5"
  })
    {
      id # 삭제 작업은 `role` 객체를 반환하지 않습니다. ID만 반환합니다.
    }
}
```

## 엔드투엔드 예시

아래에서는 다음을 기반으로 설명하겠습니다: [일반 작업](#common-operations) 엔드투엔드 흐름을 보여주는 예시.

#### **새 사용자 관리자 역할을 만들고 그 역할에 사용자를 초대합니다.**

{% tabs %}
{% tab title="Python" %}

```python
# pip install gql aiohttp

from gql import gql, Client
from gql.transport.aiohttp import AIOHTTPTransport

transport = AIOHTTPTransport(
  url="YOUR_PANTHER_API_URL",
  headers={"X-API-Key": "YOUR_API_KEY"},
)

client = Client(transport=transport, fetch_schema_from_transport=True)

create_user_admin = gql(
  """
  mutation newAdminRole {
    createRole (input: {
      name: "user-admin"
      permissions: [
        UserRead
        UserModify
        OrganizationAPITokenRead
        GeneralSettingsRead
      ]
    }) 
    {
      role {
        name
        id
      }
    }
  }
  """
)

invite_user = gql(
  """
  mutation inviteUser($input: InviteUserInput!) {
    inviteUser (input: $input) {
      user {
        id
        email
      }
    }
  }
  """
)

new_role_data = client.execute(
  create_user_admin
)

print(f'새 역할 ID는 {new_role_data["createRole"]["role"]["id"]}')

response_data = client.execute(
  invite_user,
  variable_values= {
    "input": {
      "email": "newAdmin@domain.local",
      "givenName": "user",
      "familyName": "admin",
      "role": {
        "kind": "ID",
        "value": new_role_data["createRole"]["role"]["id"],
      }
    }
  }
)

print(f'사용자 {response_data["inviteUser"]["user"]["email"]}를 역할 {new_role_data["createRole"]["role"]["name"]}로 성공적으로 초대했습니다.'
```

{% endtab %}

{% tab title="NodeJS" %}

```javascript
import { GraphQLClient, gql } from "graphql-request";

const client = new GraphQLClient(
  "YOUR_PANTHER_API_URL",
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);

// `createUserAdmin`는 쿼리의 별칭입니다. 완전히 생략할 수 있습니다.
const createUserAdmin = gql`
  mutation newAdminRole {
    createRole(
      input: {
        name: "user-admin"
        permissions: [
          UserRead
          UserModify
          OrganizationAPITokenRead
          GeneralSettingsRead
        ]
      }
    ) {
      role {
        name
        id
      }
    }
  }
`;

// `inviteUser`는 뮤테이션의 별칭입니다. 완전히 생략할 수 있습니다.
const inviteUser = gql`
  mutation inviteUser($input: InviteUserInput!) {
    inviteUser(input: $input) {
      user {
        id
        email
      }
    }
  }
`;

(async () => {
  try {
    const newRoleData = await client.request(createUserAdmin);

    const inviteUserOutput = await client.request(inviteUser, {
      input: {
        email: "newAdmin@domain.local",
        givenName: "user",
        familyName: "admin",
        role: {
          kind: "ID",
          value: newRoleData.createRole.role.id
        }
      }
    });

    console.log(
      `사용자 ${inviteUserOutput.inviteUser.user.email}를 역할 ${newRoleData.createRole.role.name}로 성공적으로 초대했습니다.`
    );
  } catch (err) {
    console.error(err);
  }
})();

```

{% endtab %}
{% endtabs %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.panther.com/ko/panther/api/graphql/user-management.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.