X-Git-Url: https://gerrit.onap.org/r/gitweb?a=blobdiff_plain;f=docs%2FAAF-API-Documentation%2FAAF-API-Documentation.rst;h=408e4a399652f51ce8a286086a844ab809f82a1f;hb=443034182c2b9c6b53081a31b8c4ef1e15eb89de;hp=4594d010db49ce880396ed21a77e86552ab52088;hpb=352ed747897655097983945fe059dd9ac84e0efe;p=aaf%2Fauthz.git diff --git a/docs/AAF-API-Documentation/AAF-API-Documentation.rst b/docs/AAF-API-Documentation/AAF-API-Documentation.rst index 4594d010..408e4a39 100644 --- a/docs/AAF-API-Documentation/AAF-API-Documentation.rst +++ b/docs/AAF-API-Documentation/AAF-API-Documentation.rst @@ -1,235 +1,234 @@ -AAF 2.0 RESTful interface -========================= - -Accessing RESTful ------------------ - --AAF RESTful service is secured by the following: --The Client must utilize HTTP/S. Non Secure HTTP is not acceptable --The Client MUST supply an Identity validated by one of the following mechanisms - - - Valid Global Login Cookie (CSP) - - BASIC AUTH protocol using CSO Registered MechID, provisioned in AAF - - BASIC AUTH protocol using ATTUID@csp.att.com, Global Login Password - - (Available 3rd Qtr 2015) Valid tGuard Login Cookie - - (Near Future) Application level Certificate - -Responses - -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. - -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 - -XSDs for Versions - -AAF can support multiple Versions of the API. Choose the ContentType/Accept that has the appropriate version=?.? - -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) - -Character Restrictions - -- Character Restrictions must depend on the Enforcement Point used -- Most AAF usage will be AAF Enforcement Point Characters for Instance and Action are: - *a-zA-Z0-9,.()\_-=%* - For Instance, you may declare a multi-dimensional key with : (colon) separator, example: - -Ask for a Consultation on how these are typically used, or, if your tool is the only Enforcement Point, if set may be expanded - -+--------------------+--------------------+--------------------+---------------------------------------------------+ -| Entity | Method | Path Info | Description | -+====================+====================+====================+===================================================+ -| PERMISSION | POST | /authz/perm | Create a Permission | -| | | | Permission consists of: | -| | | | - type - a Namespace qualified identifier | -| | | | specifying what kind of resource is being | -| | | | protected | -| | | | - instance - a key, possibly multi-dimensional | -| | | | that identifies a specific instance of the | -| | | | type | -| | | | - action - what kind of action is allowed | -| | | | Note: instance and action can be an \* | -| | | | Expected HTTP Code | -| | | | 201 | -| | | | Explicit HTTP Error Codes | -| | | | 403, 404, 406, 409 | -+--------------------+--------------------+--------------------+---------------------------------------------------+ -| | PUT | /authz/perm | Set Description for Permission | -| | | | Add Description Data to Perm | -| | | | Expected HTTP Code | -| | | | 200 | -| | | | Explicit HTTP Error Codes | -| | | | 404, 406 | -+--------------------+--------------------+--------------------+---------------------------------------------------+ -| | DELETE | /authz/perm | Delete a Permission | -| | | | Delete the Permission referenced by PermKey. | -| | | | You cannot normally delete a permission which | -| | | | is still granted to roles, however the | -| | | | "force" property allows you to do just that. To | -| | | | do this: Add | -| | | | 'force=true' as a query parameter. | -| | | | **WARNING**: Using force will ungrant this | -| | | | permission from all roles. Use with care. | -| | | | Expected HTTP Code | -| | | | 200 | -| | | | Explicit HTTP Error Codes | -| | | | 404, 406 | -+--------------------+--------------------+--------------------+---------------------------------------------------+ -| | DELETE | /authz/perm/:name/ | Delete a Permission | -| | | :type/:action | Delete the Permission referenced by :type | -| | | | :instance: action | -| | | | You cannot normally delete a permission which | -| | | | is still granted to roles, however the | -| | | | "force" property allows you to do | -| | | | just that. To do this: Add 'force=true' as a | -| | | | query parameter | -| | | | | -| | | | WARNING: Using force will ungrant this permission | -| | | | from all roles. Use with care. | -| | | | ------------------------------------------------- | -| | | | Parameters | -| | | | type : string (Required) | -| | | | instance : string (Required) | -| | | | action : string (Required) | -| | | | Expected HTTP Code | -| | | | 200 | -| | | | Explicit HTTP Error Codes | -| | | | 404, 406 | -+--------------------+--------------------+--------------------+---------------------------------------------------+ -| | PUT | /authz/perm/:type/ | Update a Permission | -| | | :instance/:action | Rename the Permission referenced | -| | | | by :type :instance :action, and rename | -| | | | (copy/delete) to the Permission described in | -| | | | PermRequest | -| | | | | -| | | |---------------------------------------------------| -| | | | Parameters | -| | | | type : string (Required) | -| | | | instance : string (Required) | -| | | | action : string (Required) | -| | | | Expected HTTP Code | -| | | | 200 | -| | | | Explicit HTTP Error Codes | -| | | | 404, 406 ,409 | -+--------------------+--------------------+--------------------+---------------------------------------------------+ -| | GET | /authz/perms/:type | Get Permissions by Type | -| | | | | -| | | | List All Permissions that match the :type | -| | | | element of the key | -| | | | ------------------------------------------------- | -| | | | Parameters | -| | | | type : string (Required) | -| | | | Expected HTTP Code | -| | | | 200 | -| | | | Explicit HTTP Error Codes | -| | | | 404, 406 | -+--------------------+--------------------+--------------------+---------------------------------------------------+ -| | GET | /authz/perms/:type | Get Permissions by Key | -| | | /:instance/:action | List Permissions that match key; | -| | | | :type, :instance and :action | -| | | | | -| | | | --------------------------------------------------| -| | | | Parameters | -| | | | type : string (Required) | -| | | | instance : string (Required) | -| | | | action : string (Required) | -| | | | Expected HTTP Code | -| | | | 200 | -| | | | Explicit HTTP Error Codes | -| | | | 404, 406 | -+--------------------+--------------------+--------------------+---------------------------------------------------+ -| | GET | /authz/perms/ns/:n | Get PermsByNS | -| | | s | List All Permissions that are in Namespace :ns | -| | | | --------------------------------------------------| -| | | | Parameters | -| | | | type : ns (Required) | -| | | | Expected HTTP Code | -| | | | 200 | -| | | | Explicit HTTP Error Codes | -| | | | 404, 406 | -+--------------------+--------------------+--------------------+---------------------------------------------------+ -| | GET | /authz/perms/role/ | Get Permissions by Role | -| | | :role | List All Permissions that are granted to :role | -| | | | --------------------------------------------------| -| | | | Parameters | -| | | | role : string (Required) | -| | | | Expected HTTP Code | -| | | | 200 | -| | | | Explicit HTTP Error Codes | -| | | | 404, 406 | -+--------------------+--------------------+--------------------+---------------------------------------------------+ -| | POST | /authz/perms/user/ | Get Permissions by User, Query AAF Perms | -| | | :user | | -| | | | List All Permissions that match user :user | -| | | | | -| | | | 'user' must be expressed as full | -| | | | identity (ex: id@full.domain.com) | -| | | | Present Queries as one or more Permissions (see | -| | | | ContentType Links below for format). If the | -| | | | Caller is Granted this specific Permission, and | -| | | | the Permission is valid for the User, it will be | -| | | | included in response permissions,along with all | -| | | | the normal permissions on the 'GET' version of | -| | | | this call. If it is not valid,or caller does not | -| | | | permission to see, it will be removed from the | -| | | | list. | -| | | | **Note**: This design allows you to make one | -| | | | call for all expected permissions | -| | | | | -| | | | The permission to be included MUST be: | -| | | | .access\|:[:key]\| | -| | | | | -| | | | examples: | -| | | | | -| | | | com.att.myns.access|:ns|write | -| | | | com.att.myns.access\|:role:myrole\|create | -| | | | com.att.myns.access\|:perm:mytype:myinstance: | -| | | | myaction\|read | -| | | | --------------------------------------------------| -| | | | Parameters | -| | | | user:string(Required) | -| | | | Expected HTTP Code | -| | | | 200 | -| | | | Explicit HTTP Error Codes | -| | | | 404, 406 | -+--------------------+--------------------+--------------------+---------------------------------------------------+ -| | GET | /authz/perms/user/ | Get Permissions by User | -| | | :user | | -| | | | List All Permissions that match user :user | -| | | | 'user' must be expressed as full | -| | | | identity (ex:id@full.domain.com) | -| | | | --------------------------------------------------| -| | | | Parameters | -| | | | user:string(Required) | -| | | | Expected HTTP Code | -| | | | 200 | -| | | | Explicit HTTP Error Codes | -| | | | 404, 406 | -+--------------------+--------------------+--------------------+---------------------------------------------------+ -| ROLE | POST | /authz/role | Create Role | -| | | | | -| | | | Roles are part of Namespaces | -| | | | Examples: | -| | | | | -| | | | - com.att.aaf - The team that created and | -| | | | maintains AAF | -| | | | | -| | | | Roles do not include implied permissions for an | -| | | | App. Instead, they contain explicit Granted | -| | | | Permissions by any Namespace in AAF | -| | | | Restrictions on Role Names: | -| | | | - Must start with valid Namespace name, | -| | | | terminated by .(dot/period) | -| | | | - Allowed Characters are a-zA-Z0-9._- | -| | | | - role names are Case Sensitive | -| | | | Expected HTTP Code | -| | | | 201 | -| | | | Explicit HTTP Error Codes | -| | | | 403, 404, 406, 409 | -+--------------------+--------------------+--------------------+---------------------------------------------------+ -| | PUT | /authz/role | Set Description for role | -| | | | Add Description Data to a Role | -| | | | Expected HTTP Code | -| | | | 200 | -| | | | Explicit HTTP Error Codes | -| | | | 404, 406 | -+--------------------+--------------------+--------------------+---------------------------------------------------+ +AAF 2.0 RESTful interface +========================= + +Accessing RESTful +----------------- + +AAF RESTful service is secured by the following: + + * The Client must utilize HTTP/S. Non Secure HTTP is not acceptable + * The Client MUST supply an Identity validated by one of the following mechanisms: + + * Valid Global Login Cookie (CSP) + * BASIC AUTH protocol using CSO Registered MechID, provisioned in AAF + * BASIC AUTH protocol using ATTUID@csp.att.com, Global Login Password + * (Available 3rd Qtr 2015) Valid tGuard Login Cookie + * (Near Future) Application level Certificate + +Responses + +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. + +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 + +XSDs for Versions + +AAF can support multiple Versions of the API. Choose the ContentType/Accept that has the appropriate version=?.? + +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) + +Character Restrictions + +- Character Restrictions must depend on the Enforcement Point used +- Most AAF usage will be AAF Enforcement Point Characters for Instance and Action are: + *a-zA-Z0-9,.()\_-=%* + For Instance, you may declare a multi-dimensional key with : (colon) separator, example: + +Ask for a Consultation on how these are typically used, or, if your tool is the only Enforcement Point, if set may be expanded + ++--------------------+--------------------+--------------------+---------------------------------------------------+ +| Entity | Method | Path Info | Description | ++====================+====================+====================+===================================================+ +| PERMISSION | POST | /authz/perm | Create a Permission | +| | | | Permission consists of: | +| | | | - type - a Namespace qualified identifier | +| | | | specifying what kind of resource is being | +| | | | protected | +| | | | - instance - a key, possibly multi-dimensional | +| | | | that identifies a specific instance of the | +| | | | type | +| | | | - action - what kind of action is allowed | +| | | | Note: instance and action can be an \* | +| | | | Expected HTTP Code | +| | | | 201 | +| | | | Explicit HTTP Error Codes | +| | | | 403, 404, 406, 409 | ++--------------------+--------------------+--------------------+---------------------------------------------------+ +| | PUT | /authz/perm | Set Description for Permission | +| | | | Add Description Data to Perm | +| | | | Expected HTTP Code | +| | | | 200 | +| | | | Explicit HTTP Error Codes | +| | | | 404, 406 | ++--------------------+--------------------+--------------------+---------------------------------------------------+ +| | DELETE | /authz/perm | Delete a Permission | +| | | | Delete the Permission referenced by PermKey. | +| | | | You cannot normally delete a permission which | +| | | | is still granted to roles, however the | +| | | | "force" property allows you to do just that. To | +| | | | do this: Add | +| | | | 'force=true' as a query parameter. | +| | | | **WARNING**: Using force will ungrant this | +| | | | permission from all roles. Use with care. | +| | | | Expected HTTP Code | +| | | | 200 | +| | | | Explicit HTTP Error Codes | +| | | | 404, 406 | ++--------------------+--------------------+--------------------+---------------------------------------------------+ +| | DELETE | /authz/perm/:name/ | Delete a Permission | +| | | :type/:action | Delete the Permission referenced by :type | +| | | | :instance: action | +| | | | You cannot normally delete a permission which | +| | | | is still granted to roles, however the | +| | | | "force" property allows you to do | +| | | | just that. To do this: Add 'force=true' as a | +| | | | query parameter | +| | | | | +| | | | WARNING: Using force will ungrant this permission | +| | | | from all roles. Use with care. | +| | | | --------------------------------------------------| +| | | | Parameters | +| | | | type : string (Required) | +| | | | instance : string (Required) | +| | | | action : string (Required) | +| | | | Expected HTTP Code | +| | | | 200 | +| | | | Explicit HTTP Error Codes | +| | | | 404, 406 | ++--------------------+--------------------+--------------------+---------------------------------------------------+ +| | PUT | /authz/perm/:type/ | Update a Permission | +| | | :instance/:action | Rename the Permission referenced | +| | | | by :type :instance :action, and rename | +| | | | (copy/delete) to the Permission described in | +| | | | PermRequest | +| | | | --------------------------------------------------| +| | | | Parameters | +| | | | type : string (Required) | +| | | | instance : string (Required) | +| | | | action : string (Required) | +| | | | Expected HTTP Code | +| | | | 200 | +| | | | Explicit HTTP Error Codes | +| | | | 404, 406 ,409 | ++--------------------+--------------------+--------------------+---------------------------------------------------+ +| | GET | /authz/perms/:type | Get Permissions by Type | +| | | | | +| | | | List All Permissions that match the :type | +| | | | element of the key | +| | | | --------------------------------------------------| +| | | | Parameters | +| | | | type : string (Required) | +| | | | Expected HTTP Code | +| | | | 200 | +| | | | Explicit HTTP Error Codes | +| | | | 404, 406 | ++--------------------+--------------------+--------------------+---------------------------------------------------+ +| | GET | /authz/perms/:type | Get Permissions by Key | +| | | /:instance/:action | List Permissions that match key; | +| | | | :type, :instance and :action | +| | | | --------------------------------------------------| +| | | | Parameters | +| | | | type : string (Required) | +| | | | instance : string (Required) | +| | | | action : string (Required) | +| | | | Expected HTTP Code | +| | | | 200 | +| | | | Explicit HTTP Error Codes | +| | | | 404, 406 | ++--------------------+--------------------+--------------------+---------------------------------------------------+ +| | GET | /authz/perms/ns/:n | Get PermsByNS | +| | | s | List All Permissions that are in Namespace :ns | +| | | | --------------------------------------------------| +| | | | Parameters | +| | | | type : ns (Required) | +| | | | Expected HTTP Code | +| | | | 200 | +| | | | Explicit HTTP Error Codes | +| | | | 404, 406 | ++--------------------+--------------------+--------------------+---------------------------------------------------+ +| | GET | /authz/perms/role/ | Get Permissions by Role | +| | | :role | List All Permissions that are granted to :role | +| | | | --------------------------------------------------| +| | | | Parameters | +| | | | role : string (Required) | +| | | | Expected HTTP Code | +| | | | 200 | +| | | | Explicit HTTP Error Codes | +| | | | 404, 406 | ++--------------------+--------------------+--------------------+---------------------------------------------------+ +| | POST | /authz/perms/user/ | Get Permissions by User, Query AAF Perms | +| | | :user | | +| | | | List All Permissions that match user :user | +| | | | | +| | | | 'user' must be expressed as full | +| | | | identity (ex: id@full.domain.com) | +| | | | Present Queries as one or more Permissions (see | +| | | | ContentType Links below for format). If the | +| | | | Caller is Granted this specific Permission, and | +| | | | the Permission is valid for the User, it will be | +| | | | included in response permissions,along with all | +| | | | the normal permissions on the 'GET' version of | +| | | | this call. If it is not valid,or caller does not | +| | | | permission to see, it will be removed from the | +| | | | list. | +| | | | **Note**: This design allows you to make one | +| | | | call for all expected permissions | +| | | | | +| | | | The permission to be included MUST be: | +| | | | .access\|:[:key]\| | +| | | | | +| | | | examples: | +| | | | | +| | | | com.att.myns.access|:ns|write | +| | | | com.att.myns.access\|:role:myrole\|create | +| | | | com.att.myns.access\|:perm:mytype:myinstance: | +| | | | myaction\|read | +| | | | --------------------------------------------------| +| | | | Parameters | +| | | | user:string(Required) | +| | | | Expected HTTP Code | +| | | | 200 | +| | | | Explicit HTTP Error Codes | +| | | | 404, 406 | ++--------------------+--------------------+--------------------+---------------------------------------------------+ +| | GET | /authz/perms/user/ | Get Permissions by User | +| | | :user | | +| | | | List All Permissions that match user :user | +| | | | 'user' must be expressed as full | +| | | | identity (ex:id@full.domain.com) | +| | | | --------------------------------------------------| +| | | | Parameters | +| | | | user:string(Required) | +| | | | Expected HTTP Code | +| | | | 200 | +| | | | Explicit HTTP Error Codes | +| | | | 404, 406 | ++--------------------+--------------------+--------------------+---------------------------------------------------+ +| ROLE | POST | /authz/role | Create Role | +| | | | | +| | | | Roles are part of Namespaces | +| | | | Examples: | +| | | | - com.att.aaf | +| | | | - The team that created andmaintains AAF | +| | | | | +| | | | Roles do not include implied permissions for an | +| | | | App. Instead, they contain explicit Granted | +| | | | Permissions by any Namespace in AAF | +| | | | Restrictions on Role Names: | +| | | | - Must start with valid Namespace name, | +| | | | terminated by .(dot/period) | +| | | | - Allowed Characters are a-zA-Z0-9._- | +| | | | - role names are Case Sensitive | +| | | | | +| | | | Expected HTTP Code | +| | | | 201 | +| | | | Explicit HTTP Error Codes | +| | | | 403, 404, 406, 409 | ++--------------------+--------------------+--------------------+---------------------------------------------------+ +| | PUT | /authz/role | Set Description for role | +| | | | Add Description Data to a Role | +| | | | Expected HTTP Code | +| | | | 200 | +| | | | Explicit HTTP Error Codes | +| | | | 404, 406 | ++--------------------+--------------------+--------------------+---------------------------------------------------+