1 AAF 2.0 RESTful interface
\r
2 =========================
\r
7 -AAF RESTful service is secured by the following:
\r
8 -The Client must utilize HTTP/S. Non Secure HTTP is not acceptable
\r
9 -The Client MUST supply an Identity validated by one of the following mechanisms
\r
11 - Valid Global Login Cookie (CSP)
\r
12 - BASIC AUTH protocol using CSO Registered MechID, provisioned in AAF
\r
13 - BASIC AUTH protocol using ATTUID@csp.att.com, Global Login Password
\r
14 - (Available 3rd Qtr 2015) Valid tGuard Login Cookie
\r
15 - (Near Future) Application level Certificate
\r
19 Each API Entity listed shows what structure will be accepted by service (ContentType) or responded with by service (Accept). Therefore, use these in making your call. Critical for PUT/POST.
\r
21 Each API call may respond with JSON or XML. Choose the ContentType/Accept that has +json after the type for JSON or +xml after the Type for XML
\r
25 AAF can support multiple Versions of the API. Choose the ContentType/Accept that has the appropriate version=?.?
\r
27 All Errors coming from AAF return AT&T Standard Error Message as a String: `JSON <./example/YXBwbGljYXRpb24vRXJyb3IranNvbg==>`__ `XML <./example/YXBwbGljYXRpb24vRXJyb3IreG1s>`__ (does not apply to errors from Container)
\r
29 Character Restrictions
\r
31 - Character Restrictions must depend on the Enforcement Point used
\r
32 - Most AAF usage will be AAF Enforcement Point Characters for Instance and Action are:
\r
33 *a-zA-Z0-9,.()\_-=%*
\r
34 For Instance, you may declare a multi-dimensional key with : (colon) separator, example:
\r
36 Ask for a Consultation on how these are typically used, or, if your tool is the only Enforcement Point, if set may be expanded
\r
38 +--------------------+--------------------+--------------------+---------------------------------------------------+
\r
39 | Entity | Method | Path Info | Description |
\r
40 +====================+====================+====================+===================================================+
\r
41 | PERMISSION | POST | /authz/perm | Create a Permission |
\r
42 | | | | Permission consists of: |
\r
43 | | | | - type - a Namespace qualified identifier |
\r
44 | | | | specifying what kind of resource is being |
\r
46 | | | | - instance - a key, possibly multi-dimensional |
\r
47 | | | | that identifies a specific instance of the |
\r
49 | | | | - action - what kind of action is allowed |
\r
50 | | | | Note: instance and action can be an \* |
\r
51 | | | | Expected HTTP Code |
\r
53 | | | | Explicit HTTP Error Codes |
\r
54 | | | | 403, 404, 406, 409 |
\r
55 +--------------------+--------------------+--------------------+---------------------------------------------------+
\r
56 | | PUT | /authz/perm | Set Description for Permission |
\r
57 | | | | Add Description Data to Perm |
\r
58 | | | | Expected HTTP Code |
\r
60 | | | | Explicit HTTP Error Codes |
\r
62 +--------------------+--------------------+--------------------+---------------------------------------------------+
\r
63 | | DELETE | /authz/perm | Delete a Permission |
\r
64 | | | | Delete the Permission referenced by PermKey. |
\r
65 | | | | You cannot normally delete a permission which |
\r
66 | | | | is still granted to roles, however the |
\r
67 | | | | "force" property allows you to do just that. To |
\r
68 | | | | do this: Add |
\r
69 | | | | 'force=true' as a query parameter. |
\r
70 | | | | **WARNING**: Using force will ungrant this |
\r
71 | | | | permission from all roles. Use with care. |
\r
72 | | | | Expected HTTP Code |
\r
74 | | | | Explicit HTTP Error Codes |
\r
76 +--------------------+--------------------+--------------------+---------------------------------------------------+
\r
77 | | DELETE | /authz/perm/:name/ | Delete a Permission |
\r
78 | | | :type/:action | Delete the Permission referenced by :type |
\r
79 | | | | :instance: action |
\r
80 | | | | You cannot normally delete a permission which |
\r
81 | | | | is still granted to roles, however the |
\r
82 | | | | "force" property allows you to do |
\r
83 | | | | just that. To do this: Add 'force=true' as a |
\r
84 | | | | query parameter |
\r
86 | | | | WARNING: Using force will ungrant this permission |
\r
87 | | | | from all roles. Use with care. |
\r
88 | | | | ------------------------------------------------- |
\r
89 | | | | Parameters |
\r
90 | | | | type : string (Required) |
\r
91 | | | | instance : string (Required) |
\r
92 | | | | action : string (Required) |
\r
93 | | | | Expected HTTP Code |
\r
95 | | | | Explicit HTTP Error Codes |
\r
97 +--------------------+--------------------+--------------------+---------------------------------------------------+
\r
98 | | PUT | /authz/perm/:type/ | Update a Permission |
\r
99 | | | :instance/:action | Rename the Permission referenced |
\r
100 | | | | by :type :instance :action, and rename |
\r
101 | | | | (copy/delete) to the Permission described in |
\r
102 | | | | PermRequest |
\r
104 | | | |---------------------------------------------------|
\r
105 | | | | Parameters |
\r
106 | | | | type : string (Required) |
\r
107 | | | | instance : string (Required) |
\r
108 | | | | action : string (Required) |
\r
109 | | | | Expected HTTP Code |
\r
111 | | | | Explicit HTTP Error Codes |
\r
112 | | | | 404, 406 ,409 |
\r
113 +--------------------+--------------------+--------------------+---------------------------------------------------+
\r
114 | | GET | /authz/perms/:type | Get Permissions by Type |
\r
116 | | | | List All Permissions that match the :type |
\r
117 | | | | element of the key |
\r
118 | | | | ------------------------------------------------- |
\r
119 | | | | Parameters |
\r
120 | | | | type : string (Required) |
\r
121 | | | | Expected HTTP Code |
\r
123 | | | | Explicit HTTP Error Codes |
\r
125 +--------------------+--------------------+--------------------+---------------------------------------------------+
\r
126 | | GET | /authz/perms/:type | Get Permissions by Key |
\r
127 | | | /:instance/:action | List Permissions that match key; |
\r
128 | | | | :type, :instance and :action |
\r
130 | | | | --------------------------------------------------|
\r
131 | | | | Parameters |
\r
132 | | | | type : string (Required) |
\r
133 | | | | instance : string (Required) |
\r
134 | | | | action : string (Required) |
\r
135 | | | | Expected HTTP Code |
\r
137 | | | | Explicit HTTP Error Codes |
\r
139 +--------------------+--------------------+--------------------+---------------------------------------------------+
\r
140 | | GET | /authz/perms/ns/:n | Get PermsByNS |
\r
141 | | | s | List All Permissions that are in Namespace :ns |
\r
142 | | | | --------------------------------------------------|
\r
143 | | | | Parameters |
\r
144 | | | | type : ns (Required) |
\r
145 | | | | Expected HTTP Code |
\r
147 | | | | Explicit HTTP Error Codes |
\r
149 +--------------------+--------------------+--------------------+---------------------------------------------------+
\r
150 | | GET | /authz/perms/role/ | Get Permissions by Role |
\r
151 | | | :role | List All Permissions that are granted to :role |
\r
152 | | | | --------------------------------------------------|
\r
153 | | | | Parameters |
\r
154 | | | | role : string (Required) |
\r
155 | | | | Expected HTTP Code |
\r
157 | | | | Explicit HTTP Error Codes |
\r
159 +--------------------+--------------------+--------------------+---------------------------------------------------+
\r
160 | | POST | /authz/perms/user/ | Get Permissions by User, Query AAF Perms |
\r
162 | | | | List All Permissions that match user :user |
\r
164 | | | | 'user' must be expressed as full |
\r
165 | | | | identity (ex: id@full.domain.com) |
\r
166 | | | | Present Queries as one or more Permissions (see |
\r
167 | | | | ContentType Links below for format). If the |
\r
168 | | | | Caller is Granted this specific Permission, and |
\r
169 | | | | the Permission is valid for the User, it will be |
\r
170 | | | | included in response permissions,along with all |
\r
171 | | | | the normal permissions on the 'GET' version of |
\r
172 | | | | this call. If it is not valid,or caller does not |
\r
173 | | | | permission to see, it will be removed from the |
\r
175 | | | | **Note**: This design allows you to make one |
\r
176 | | | | call for all expected permissions |
\r
178 | | | | The permission to be included MUST be: |
\r
179 | | | | .access\|:[:key]\| |
\r
181 | | | | examples: |
\r
183 | | | | com.att.myns.access|:ns|write |
\r
184 | | | | com.att.myns.access\|:role:myrole\|create |
\r
185 | | | | com.att.myns.access\|:perm:mytype:myinstance: |
\r
186 | | | | myaction\|read |
\r
187 | | | | --------------------------------------------------|
\r
188 | | | | Parameters |
\r
189 | | | | user:string(Required) |
\r
190 | | | | Expected HTTP Code |
\r
192 | | | | Explicit HTTP Error Codes |
\r
194 +--------------------+--------------------+--------------------+---------------------------------------------------+
\r
195 | | GET | /authz/perms/user/ | Get Permissions by User |
\r
197 | | | | List All Permissions that match user :user |
\r
198 | | | | 'user' must be expressed as full |
\r
199 | | | | identity (ex:id@full.domain.com) |
\r
200 | | | | --------------------------------------------------|
\r
201 | | | | Parameters |
\r
202 | | | | user:string(Required) |
\r
203 | | | | Expected HTTP Code |
\r
205 | | | | Explicit HTTP Error Codes |
\r
207 +--------------------+--------------------+--------------------+---------------------------------------------------+
\r
208 | ROLE | POST | /authz/role | Create Role |
\r
210 | | | | Roles are part of Namespaces |
\r
211 | | | | Examples: |
\r
213 | | | | - com.att.aaf - The team that created and |
\r
214 | | | | maintains AAF |
\r
216 | | | | Roles do not include implied permissions for an |
\r
217 | | | | App. Instead, they contain explicit Granted |
\r
218 | | | | Permissions by any Namespace in AAF |
\r
219 | | | | Restrictions on Role Names: |
\r
220 | | | | - Must start with valid Namespace name, |
\r
221 | | | | terminated by .(dot/period) |
\r
222 | | | | - Allowed Characters are a-zA-Z0-9._- |
\r
223 | | | | - role names are Case Sensitive |
\r
224 | | | | Expected HTTP Code |
\r
226 | | | | Explicit HTTP Error Codes |
\r
227 | | | | 403, 404, 406, 409 |
\r
228 +--------------------+--------------------+--------------------+---------------------------------------------------+
\r
229 | | PUT | /authz/role | Set Description for role |
\r
230 | | | | Add Description Data to a Role |
\r
231 | | | | Expected HTTP Code |
\r
233 | | | | Explicit HTTP Error Codes |
\r
235 +--------------------+--------------------+--------------------+---------------------------------------------------+
\r
Code Review / aaf / authz.git / blob