Merge "Trusted Attributes Policy for External Identity Providers"

v3/src/markdown/identity-api-v3-os-federation-ext.md

@@ -18,6 +18,8 @@ Definitions
   may not align 1:1 with the Identity API concepts. To help overcome such
   mismatches, a mapping can be done either on the sending side (third party
   identity provider), on the consuming side (Identity API service), or both.
+- *Trusted Attribute*: An attribute trusted to be issued by a Trusted Identity
+  Provider.
 
 API Resources
 -------------
@@ -136,6 +138,23 @@ Required attributes::
       expression](http://docs.python.org/2/library/re.html) search against the
       remote attribute `type`.
 
+### Trusted Attribute: `/OS-FEDERATION/identity_providers/{idp_id}/trusted_attributes`
+
+A trusted attributes policy defines which attributes an Identity provider is
+trusted to issue. When a policy is created for a Identity provider, the
+attributes received in assertions from this provider are automatically filtered.
+In order to maintain backwards compatibility, all attributes are accepted from
+this provider if no policy is defined. If the policy is empty, no attributes are
+accepted.
+
+Attributes:
+
+    - `attributes` (list)
+
+      A list of trusted attributes. Each attribute is specified as a
+      type and an optional set of values. A list of zero values denotes that
+      any value should be accepted.
+
 Identity Provider API
 ---------------------
 
@@ -161,7 +180,8 @@ Response:
             "id": "ACME",
             "links": {
                 "protocols": "http://identity:35357/v3/OS-FEDERATION/identity_providers/ACME/protocols",
-                "self": "http://identity:35357/v3/OS-FEDERATION/identity_providers/ACME"
+                "self": "http://identity:35357/v3/OS-FEDERATION/identity_providers/ACME",
+                "trusted_attributes": "http://identity:35357/v3/OS-FEDERATION/identity_providers/ACME/trusted_attributes"
             }
         }
     }
@@ -180,7 +200,8 @@ Response:
                 "id": "ACME",
                 "links": {
                     "protocols": "http://identity:35357/v3/OS-FEDERATION/identity_providers/ACME/protocols",
-                    "self": "http://identity:35357/v3/OS-FEDERATION/identity_providers/ACME"
+                    "self": "http://identity:35357/v3/OS-FEDERATION/identity_providers/ACME",
+                    "trusted_attributes": "http://identity:35357/v3/OS-FEDERATION/identity_providers/ACME/trusted_attributes"
                 }
             },
             {
@@ -189,7 +210,8 @@ Response:
                 "id": "ACME-contractors",
                 "links": {
                     "protocols": "http://identity:35357/v3/OS-FEDERATION/identity_providers/ACME-contractors/protocols",
-                    "self": "http://identity:35357/v3/OS-FEDERATION/identity_providers/ACME-contractors"
+                    "self": "http://identity:35357/v3/OS-FEDERATION/identity_providers/ACME-contractors",
+                    "trusted_attributes": "http://identity:35357/v3/OS-FEDERATION/identity_providers/ACME/trusted_attributes"
                 }
             }
         ],
@@ -213,7 +235,8 @@ Response:
             "id": "ACME",
             "links": {
                 "protocols": "http://identity:35357/v3/OS-FEDERATION/identity_providers/ACME/protocols",
-                "self": "http://identity:35357/v3/OS-FEDERATION/identity_providers/ACME"
+                "self": "http://identity:35357/v3/OS-FEDERATION/identity_providers/ACME",
+                "trusted_attributes": "http://identity:35357/v3/OS-FEDERATION/identity_providers/ACME/trusted_attributes"
             }
         }
     }
@@ -248,7 +271,8 @@ Response:
             "id": "ACME",
             "links": {
                 "protocols": "http://identity:35357/v3/OS-FEDERATION/identity_providers/ACME/protocols",
-                "self": "http://identity:35357/v3/OS-FEDERATION/identity_providers/ACME"
+                "self": "http://identity:35357/v3/OS-FEDERATION/identity_providers/ACME",
+                "trusted_attributes": "http://identity:35357/v3/OS-FEDERATION/identity_providers/ACME/trusted_attributes"
             }
         }
     }
@@ -560,6 +584,132 @@ Response:
 
     Status: 204 No Content
 
+Trusted Attribute API
+---------------------
+
+### Get an Identity Provider's set of trusted attributes: `GET /OS-FEDERATION/identity_providers/{idp_id}/trusted_attributes`
+
+Response:
+
+    Status: 200 OK
+
+    {
+        "trusted_attributes": [
+            {
+                "type": "email",
+                "values": []
+            },
+            {
+                "type": "orgPersonType",
+                "values": ["staff", "contractor", "guest"]
+            },
+            {
+                "type": "uid",
+                "values": []
+            }
+        ],
+        "links": {
+            "identity_provider": "http://identity:35357/v3/OS-FEDERATION/identity_providers/7e23a6",
+            "self": "http://identity:35357/v3/OS-FEDERATION/identity_providers/7e23a6/trusted_attributes"
+        }
+    }
+
+### Create an Identity Provider's Trusted Attributes Policy: `PUT /OS-FEDERATION/identity_providers/{idp_id}/trusted_attributes`
+
+Request:
+    {
+        "trusted_attributes": [
+            {
+                "type": "email",
+                "values": []
+            },
+            {
+                "type": "orgPersonType",
+                "values": ["staff", "contractor", "guest"]
+            },
+            {
+                "type": "uid",
+                "values": []
+            }
+        ]
+    }
+
+Response:
+
+    Status: 201 Created
+
+    {
+        "trusted_attributes": [
+            {
+                "type": "email",
+                "values": []
+            },
+            {
+                "type": "orgPersonType",
+                "values": ["staff", "contractor", "guest"]
+            },
+            {
+                "type": "uid",
+                "values": []
+            }
+        ],
+        "links": {
+            "identity_provider": "http://identity:35357/v3/OS-FEDERATION/identity_providers/7e23a6",
+            "self": "http://identity:35357/v3/OS-FEDERATION/identity_providers/7e23a6/trusted_attributes"
+        }
+    }
+
+### Update an Identity Provider's Trusted Attributes Policy: `PATCH /OS-FEDERATION/identity_providers/{idp_id}/trusted_attributes`
+
+Request:
+    {
+        "trusted_attributes": [
+            {
+                "type": "email",
+                "values": []
+            },
+            {
+                "type": "orgPersonType",
+                "values": ["contractor", "guest"]
+            },
+            {
+                "type": "uid",
+                "values": []
+            }
+        ]
+    }
+
+Response:
+
+    Status: 200 OK
+
+    {
+        "trusted_attributes": [
+            {
+                "type": "email",
+                "values": []
+            },
+            {
+                "type": "orgPersonType",
+                "values": ["contractor", "guest"]
+            },
+            {
+                "type": "uid",
+                "values": []
+            }
+        ],
+        "links": {
+            "identity_provider": "http://identity:35357/v3/OS-FEDERATION/identity_providers/7e23a6",
+            "self": "http://identity:35357/v3/OS-FEDERATION/identity_providers/7e23a6/trusted_attributes"
+        }
+    }
+
+### Delete a trusted attributes policy for an Identity provider: `DELETE /OS-FEDERATION/identity_providers/{idp_id}/trusted_attributes`
+
+Response:
+
+    Status: 204 Deleted
+
 Listing projects and domains
 ----------------------------