]> mj.ucw.cz Git - subauth.git/blob - PROTOCOL
Account management using password authentication
[subauth.git] / PROTOCOL
1 Protocol between the server and the clients
2 ===========================================
3
4 Messages are sent through a UNIX-domain sequential packet socket
5 and authenticated by automatic passing of user credentials.
6 For every request, a reply is sent through the same connection.
7 Pipelining of requests is currently not supported.
8
9 All requests and replies are serialized as JSON objects. Requests
10 have always the "cmd" attribute set to the name of the command.
11 Replies always have the "error" attribute set; it contains an error
12 message or an empty string to indicate success.
13
14 Some operations require root privileges. Other operations are
15 unprivileged if no login name present, or if the correct "auth-passwd"
16 is provided and target user has allowed administration of their
17 account using a password authentication. Only regular password can be
18 used for such authentication, tokens are not accepted.
19
20 # No operation (unprivileged)
21 {
22         "cmd": "nop"
23 }
24
25 # Create an account (privileged)
26 {
27         "cmd": "create-acct",
28         "login": "login name",
29         "zone": "auth zone"
30 }
31
32 # Delete an account (privileged)
33 {
34         "cmd": "delete-acct",
35         "login": "login name",
36         "zone": "auth zone"             # "*" to delete accounts in all zones
37 }
38
39 # Create an authentication token
40 {
41         "cmd": "create-token",
42         "login": "login name",
43         "auth-passwd": "current password",
44         "zone": "auth zone",
45         "comment": "optional comment"
46 }
47 {
48         "error": "",
49         "token": "new token",
50         "ident": "token id"
51 }
52
53 # Delete an authentication token
54 {
55         "cmd": "delete-token",
56         "login": "login name",
57         "auth-passwd": "current password",
58         "zone": "auth zone",
59         "ident": "token id"                     # "*" for all tokens for the login+zone
60 }
61
62 # Change parameters of a token
63 {
64         "cmd": "change-token"
65         "login": "login name",
66         "auth-passwd": "current password",
67         "zone": "auth zone",
68         "ident": "token id",
69         "comment": "new comment"                # optional
70 }
71
72 # Set password for an account
73 {
74         "cmd": "set-passwd",
75         "login": "login name",
76         "auth-passwd": "current password",
77         "zone": "auth zone",
78         "passwd": "new password"
79 }
80
81 # Delete password for an account
82 {
83         "cmd": "delete-passwd",
84         "login": "login name",
85         "auth-passwd": "current password",
86         "zone": "auth zone"
87 }
88
89 # Create a temporary token
90 {
91         "cmd": "create-temp",
92         "login": "login name",
93         "auth-passwd": "current password",
94         "zone": "auth zone",
95         "validity": seconds             # Requested token validity
96 }
97 {
98         "error": "",
99         "token": "new token"
100 }
101
102 # Authenticate a user
103 {
104         "cmd": "login",
105         "login": "login name",
106         "zone": "auth zone",
107         "passwd": "password or token"
108 }
109
110 # Allow/disallow management of selected account using password
111 {
112         "cmd": "allow-passwd-auth",
113         "login": "login name",
114         "auth-passwd": "current password",
115         "zone": "auth zone",
116         "allow": integer
117 }
118
119 # List user's accounts and tokens
120 {
121         "cmd": "list-accts",
122         "login": "login name",
123 }
124 {
125         "error": "",
126         "login: "login name",
127         "accounts": [
128                 {
129                         "zone": "auth zone",
130                         "allow-passwd-auth": integer,           # Can anybody manage this account using its password?
131                         "tokens": [
132                                 {
133                                         "type": "token type",   # passwd/token
134                                         "ident": "token id",
135                                         "lastmod": timestamp    # UNIX timestamp of last modification
136                                 }
137                                 ...
138                         ]
139                 }
140                 ...
141         ]
142 }
143
144 # List known authentication zones
145 {
146         "cmd": "list-zones"
147 }
148 {
149         "error": "",
150         "zones": [
151                 {
152                         "name": "auth zone",
153                         "desc": "human-readable description",
154                         "allow-passwd": integer,                # Does the zone support passwords?
155                         "allow-tokens": integer,                # Does the zone support auth tokens?
156                         "allow-passwd-auth": integer,           # Does the zone support password authentication for account management?
157                         "max-temp-validity": seconds            # Maximum validity of temp tokens
158                                                                 # (if no temp tokens supported)
159                 }
160                 ...
161         ]
162 }