Skip to content

Commit 7959d4a

Browse files
eunsoopeunsoop
authored
Merge pull request #1 from sunrin-ana/feat/anaccount
Feat/anaccount
2 parents 070de25 + 435d191 commit 7959d4a

11 files changed

Lines changed: 257 additions & 3 deletions

File tree

‎src/assets/docs/anaccount/development/sro.png‎

1.24 MB
Loading

‎src/assets/docs/anaccount/development/tuple.png‎

888 KB
Loading

‎src/content/docs/anaccount/Development/API/getting-started.mdx‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
---
2+
title: An Account API 사용 시작하기
3+
description: An Account API 사용을 시작하는 방법에 대한 문서
4+
---
5+
6+
An Account API를 사용하기 위해서는 먼저 [OAuth2란 무엇인가?](/reference/oauth2)와 [OIDC란 무엇인가?](/reference/oauth2/oidc) 문서를 숙지하는 것이 중요해요.<br/>
7+
이 문서들은 An Account가 따르는 인증 표준에 대한 기본적인 이해를 제공해줄 거예요.
8+
9+
## [OAuth 2.0](/reference/oauth2) 및 [OIDC](/reference/oauth2/oidc), [SAML](/reference/saml)으로 AnA 서비스와 연동하기
10+
11+
An Account는 OAuth 2.0 및 OIDC, SAML 표준을 지원하여 다양한 서비스와의 연동이 가능해요.<br/>
12+
이를 통해 여러분의 애플리케이션에서 안전하게 사용자 인증 및 권한 부여를 처리할 수 있어요.
13+
An Account와 연동하는 방법에 대한 자세한 내용은 다음 문서들을 참고해주세요:
14+
- [OAuth 2.0으로 AnA 서비스와 연동하기](./api/oauth2-integration)
15+
- [OIDC로 AnA 서비스와 연동하기](./api/oidc-integration)
16+
- [SAML로 AnA 서비스와 연동하기](./api/saml-integration)
17+
18+
## An Account API
19+
20+
## Normal API
21+
An Account는 OAuth2 및 OIDC 표준을 따르는 다양한 API 엔드포인트를 제공해요.<br/>
22+
이 API들을 사용하면 사용자 인증, 토큰 발급, 권한 부여 등 다양한 기능을 구현할 수 있어요.<br/>
23+
자세한 내용은 [An Account Normal API 문서](./api/normal-api)를 참고해주세요.
24+
25+
### Admin API
26+
An Account는 관리자를 위한 Admin API를 제공해요.<br/>
27+
이 API를 사용하면 사용자 관리, 권한 설정, 애플리케이션 등록 등 다양한 관리 작업을 자동화할 수 있어요.<br/>
28+
Admin API에 대한 자세한 내용은 [An Account Admin API 문서](./api/admin-api)를 참고해주세요.

‎src/content/docs/anaccount/Development/API/oauth2-integration.mdx‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
---
2+
title: OAuth 2.0와 An Account
3+
description: OAuth 2.0 으로 AnA 서비스와 연동하기
4+
---
5+
6+
TBD

‎src/content/docs/anaccount/Development/Accounts/structure.mdx‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
---
2+
title: An Account의 구조
3+
description: An Account의 구조에 대한 문서
4+
---
5+
6+
An Account는 기본적인 OAuth2.0 및 OIDC 계정 서버 구조를 따르고 있어요.<br/>
7+
8+
TBD: An Account의 구조에 대한 자세한 설명을 여기에 작성할 예정이에요.

‎src/content/docs/anaccount/Development/An Americano/API/golang.mdx‎

Lines changed: 118 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,118 @@
1+
---
2+
title: Golang Wrapper
3+
description: An Americano의 Golang Wrapper 사용법에 대한 문서
4+
---
5+
An Americano는 Golang Wrapper API를 제공하고 있어요.<br/>
6+
Golang Wrapper API를 사용하면 Golang 애플리케이션에서 An Americano의 기능을 쉽게 활용할 수 있어요.<br/>
7+
## 설치하기
8+
Golang Wrapper API를 사용하려면, 먼저 Go 모듈을 설치해야해요.<br/>
9+
다음 명령어를 사용하여 Go 모듈을 설치할 수 있어요:<br/>
10+
```bash
11+
go get github.com/sunrin-ana/anamericano-golang
12+
```
13+
14+
## 사용법
15+
Golang Wrapper API를 사용하려면, 먼저 패키지를 임포트해야해요.<br/>
16+
```go
17+
import "github.com/sunrin-ana/anamericano-golang"
18+
```
19+
그 다음, An Americano 클라이언트를 생성할 수 있어요.<br/>
20+
```go
21+
var permissionClient = anamericano.NewClient(&anamericano.ContextTokenAuth{}, nil)
22+
```
23+
24+
이제 클라이언트를 사용하여 An Americano의 기능을 호출할 수 있어요.<br/>
25+
26+
### 권한 확인하기
27+
다음은 특정 주체가 객체에 대해 특정 관계를 가지고 있는지 확인하는 예제 코드에요:<br/>
28+
```go
29+
userToken := ... // 사용자 토근 받아오기
30+
31+
ctx := anamericano.WithToken(r.Context(), userToken)
32+
33+
resp, err := permissionClient.CheckPermission(ctx, &anamericano.PermissionCheckRequest{
34+
SubjectType: "user", // 주체 타입
35+
SubjectID: "아나줘요", // 주체 ID
36+
Relation: "viewer", // 관계
37+
ObjectNamespace: "document", // 객체 네임스페이스
38+
ObjectID: "eungyolee-teukcom", // 객체 ID
39+
})
40+
```
41+
42+
### 권한 업데이트하기
43+
44+
#### 사용자 권한 업데이트
45+
```go
46+
resp, err := permissionClient.WritePermission(ctx, &anamericano.PermissionWriteRequest{
47+
SubjectType: "user", // 주체 타입
48+
SubjectID: "아나줘요", // 주체 ID
49+
Relation: "viewer", // 관계
50+
ObjectNamespace: "document", // 객체 네임스페이스
51+
ObjectID: "eungyolee-teukcom", // 객체 ID
52+
})
53+
```
54+
55+
#### 그룹 권한 업데이트
56+
```go
57+
perm, err := client.WritePermission(ctx, &anamericano.PermissionWriteRequest{
58+
SubjectType: "group", // 주체 타입
59+
SubjectID: "ana", // 주체 ID
60+
SubjectRelation: stringPtr("member"), // 주체 관계
61+
ObjectNamespace: "document", // 객체 네임스페이스
62+
ObjectID: "eungyolee-teukcom", // 객체 ID
63+
Relation: "viewer", // 관계
64+
})
65+
```
66+
67+
### 권한 삭제하기
68+
```go
69+
err := client.DeletePermission(ctx, &anamericano.PermissionDeleteRequest{
70+
ObjectNamespace: "document",
71+
ObjectID: "eungyolee-teukcom",
72+
Relation: "viewer",
73+
SubjectType: "user",
74+
SubjectID: "아나줘요",
75+
})
76+
```
77+
78+
### 권한 읽기
79+
```go
80+
perms, err := client.ReadPermissions(ctx, &anamericano.PermissionReadRequest{
81+
ObjectNameSpace: "document",
82+
ObjectID: "eungyolee-teukcom",
83+
})
84+
for _, p := range perms {
85+
fmt.Printf("%s can %s\n", p.SubjectID, p.Relation)
86+
}
87+
```
88+
89+
### 특정 권한 읽기
90+
다음은 특정 권한을 가진 모든 주체를 가져오는 예제에요:<br/>
91+
```go
92+
subjects, err := client.ExpandPermissions(ctx, &anamericano.PermissionExpendRequest{
93+
ObjectNameSpace: "document",
94+
ObjectID: "eungyolee-teukcom",
95+
Relation: "viewer",
96+
})
97+
// 반환: ["user:아나줘요", "user:hanul", "group:ana#member"]
98+
99+
for _, subject := range subjects {
100+
fmt.Println(subject)
101+
}
102+
```
103+
104+
### 주체가 접근할 수 있는 모든 객체 읽기
105+
```go
106+
docs, err := client.ListObjects(ctx, &anamericano.ListObjectsRequest{
107+
ObjectNameSpace: "document",
108+
Relation: "viewer",
109+
SubjectType: "user",
110+
SubjectID: "eungyolee",
111+
})
112+
// Returns: ["eungyolee-teukcom", "eungyolee-babo", "eungyolee-kimanjja"]
113+
114+
for _, docID := range docs {
115+
fmt.Printf("Eungyolee can view: %s\n", docID)
116+
}
117+
```
118+

‎src/content/docs/anaccount/Development/An Americano/index.mdx‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
---
2+
title: An Americano 개발 시작하기
3+
description: An Americano의 개발 문서
4+
---
5+
6+
## An Americano란?
7+
An Americano는 An Account에 탑재된 관계 기반 권한 관리 시스템이에요.<br/>
8+
An Americano는 다양한 권한을 유연하게 관리할 수 있도록 도와주는 시스템이에요.<br/>
9+
Google의 Zanzibar 논문을 참고하여 설계되었어요.<br/>
10+
An Americano를 사용하기 전, - [An Americano의 구조와 권한](./structure)에 대해 먼저 숙지해주세요.
11+
12+
## An Americano API 사용하기
13+
An Americano는 다음과 같은 언어로 Wrapper API를 제공하고 있어요.<br/>
14+
15+
- Golang Wrapper
16+
- [pkg.go.dev](https://pkg.go.dev/github.com/sunrin-ana/anamericano-golang)
17+
- [Github](https://github.com/sunrin-ana/anamericano-golang)
18+
- [개발 문서](./api/golang)
19+
- (향후 추가 예정)
20+
21+
## An Americano 개발에 기여하기
22+
An Americano 개발에 기여하고 싶으신가요?<br/>
23+
An Americano는 AnA ISDT에 참여해야지만 기여할 수 있어요!<br/>
24+
만약 자신이 신입생이라면 [이곳을 클릭하여](https://apply.ana.st/) AnA 동아리에 지원 후에 임원진과 소통을 통하여 ISDT에 참여할 수 있어요! 👍 <br/>
25+
만약 자신이 AnA 부원이라면, 현재 임원진과 소통 후에 An Americano 개발에 기여할 수 있어요! 👍 👍 <br/>
26+
만약 자신이 AnA 동문회 회원이라면, AnA 동아리 임원진과 소통 후 Github에 소속되어 An Americano 개발에 기여할 수 있어요! 👍 👍 👍 <br/>
27+
<br/>
28+
임원진의 동의를 얻었다면, 마지막으로 [AnA ISDT 개발자 가이드](/guide/start)를 모두 숙지해야해요!<br/>
29+
<br/>
30+
이와 같은 과정을 모두 마치셨다면,,,,,<br/>
31+
AnA ISDT에 참여하여 An Americano 개발에 기여하는 것을 진심으로 환영해요! ~~(자발적 춘식이가 된 것을 정말 환영합니다)~~ 🎉🎉🎉 <br/>
32+

‎src/content/docs/anaccount/Development/An Americano/structure.mdx‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
---
2+
title: An Americano의 구조와 권한
3+
description: An Americano의 구조와 권한에 대한 문서
4+
---
5+
An Americano는 An Account에서 권한 관리를 쉽게 할 수 있도록 도와주는 관계 기반 권한 관리 시스템이에요.
6+
7+
## An Americano가 채택하는 모델
8+
An Americano는 [Google의 Zanzibar 논문](https://research.google/pubs/zanzibar-googles-consistent-global-authorization-system/)을 참고하여 설계되었어요.<br/>
9+
Zanzibar 모델은 관계 기반 접근 제어 모델(RBAC, Relationship-Based Access Control Model)의 일종이에요.<br/>
10+
11+
Zanzibar 모델은 객체(Object), 관계(Relationship), 주체(Subject)라는 세 가지 주요 개념을 중심으로 권한을 부여해요.<br/>
12+
### 권한의 3요소
13+
![객체와 관계 그리고 주체를 표현한 이미지](../../../../../assets/docs/anaccount/development/sro.png)
14+
15+
- 객체(Object): 보호해야할 대상? 보호 당할 대상이에요. 예를 들어, 파일, 폴더, 과제, 게시물, 데이터베이스 레코드 등이 객체가 될 수 있어요.
16+
- 주체(Subject): 객체에 접근하려는 사용자나 시스템이에요. 객체의 접근 권한을 가진 대상?이라고 이해하면 쉬워요. 예를 들어, 사용자 계정, 서비스 계정 등이 주체가 될 수 있어요.
17+
- 관계(Relationship): 객체와 주체 간의 관계를 나타내요. 예를 들어, 소유자(owner), 편집자(editor), 뷰어(viewer) 등이 관계가 될 수 있어요.
18+
19+
### 관계 튜플
20+
Zanzibar 모델에서는 객체, 관계, 주체 간의 관계를 '관계 튜플(Relationship Tuple)'이라는 형태로 표현해요.<br/>
21+
관계 튜플은 다음과 같은 형식을 가져요:<br/>
22+
![관계 튜플을 표현한 이미지 (문서1#소유자@아나줘요)](../../../../../assets/docs/anaccount/development/tuple.png)
23+
예를 들어, 'file1'의 'owner'가 '아나줘요'인 경우, 다음과 같은 관계 튜플로 표현할 수 있어요:<br/>
24+
`file1#owner@아나줘요`
25+
26+
## An Americano가 이를 구현한 방식
27+
사실 An Americano는 Zanzibar 모델을 완벽하게 구현하지는 않았어요.<br/>
28+
An Account의 빠른 출시를 위하여 현재는 일반적인 RDBMS를 사용하여 관계 튜플을 저장하고 관리하고 있어요.<br/>
29+
하지만 An Americano는 Zanzibar 모델의 핵심 개념을 따르고 있어요.<br/>
30+
따라서 An Americano를 사용하면 객체, 관계, 주체 간의 복잡한 권한 구조를 효과적으로 관리할 수 있어요.<br/>
31+
향후 An Americano는 Zanzibar 모델을 더욱 충실히 구현할 예정이에요.

‎src/content/docs/anaccount/Development/index.mdx‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
---
2+
title: An Account 개발 시작하기
3+
description: An Account의 개발 문서
4+
---
5+
6+
## An Account API 사용하기
7+
An Account는 OAuth2 표준을 따르는 인증 서버에요. 또한 OIDC도 지원해요!<br/>
8+
그렇기 때문에 다음과 같은 문서들을 먼저 숙지해주세요:
9+
- [OAuth2란 무엇인가?](/reference/oauth2)
10+
- [OIDC란 무엇인가?](/reference/oauth2/oidc)
11+
- [An Account API 사용 시작하기](./api/getting-started)
12+
- [An Account API 개발 문서](./api/full-api)
13+
14+
15+
## An Account 유지 보수
16+
An Account 개발자~~(a.k.a 춘식이)~~로 지정된 것을 진심으로 축하드려요!<br/>
17+
An Account를 개발하기 전, 숙지해야하는 필수 문서들은 다음과 같아요:
18+
- [AnA ISDT 개발자 가이드](/guide/start)
19+
- [OAuth2란 무엇인가?](/reference/oauth2)
20+
- [An Account의 구조](./accounts/structure)
21+
- [An Americano의 구조와 권한](./an-americano/structure)
22+
23+
## An Americano API 사용하기
24+
An Americano는 An Account에 탑재된 관계 기반 권한 관리 시스템이에요.<br/>
25+
An Americano를 사용하기 전, [An Americano의 구조와 권한](./an-americano/structure) 문서를 먼저 숙지해주세요.<br/>
26+
An Americano는 다양한 언어로 Wrapper API를 제공하고 있어요.<br/>
27+
자세한 내용은 [An Americano 개발 시작하기](./an-americano) 문서를 참고해주세요 😀

‎src/content/docs/anaccount/Management/index.mdx‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
---
2+
title: An Account 관리 시작하기
3+
description: An Account의 관리 문서 입니다.
4+
---

0 commit comments

Comments
 (0)