improve documentation

website/docs/r/me_identity_provider.html.markdown

@@ -4,7 +4,7 @@ subcategory : "Account Management"
 
 # ovh_me_identity_provider
 
-Configure SAML Fedration (SSO) to an identity provider.
+Configure SAML Federation (SSO) to an identity provider.
 
 ## Example Usage
 
@@ -29,19 +29,25 @@ resource "ovh_me_identity_provider" "sso" {
 </EntityDescriptor>
 EOT
 
+    # Local users will still be able to login if set to false.
+    # Administrator can always login regardless of this value.
     disable_users = false
 
+    # The assertion must contain the attribute "https://example.org/attributes/role"
+    # with the allowed values being "user" or "administrator"
     requested_attributes {
-      is_required = false
-      name = "group"
-      name_format = "urn:oasis:names:tc:SAML:2.0:attrname-format:basic"
-      values = ["test"]
+      is_required = true
+      name = "https://example.org/attributes/role"
+      name_format = "urn:oasis:names:tc:SAML:2.0:attrname-format:uri"
+      values = ["user", administrator]
     }
+    # If the attribute "https://example.org/attributes/group" is available,
+    # we want the IdP to provide it
     requested_attributes {
       is_required = false
-      name = "email"
-      name_format = "urn:oasis:names:tc:SAML:2.0:attrname-format:basic"
-      values = ["test@example.org"]
+      name = "https://example.org/attributes/group"
+      name_format = "urn:oasis:names:tc:SAML:2.0:attrname-format:uri"
+      values = []
     }
 }
 ```
@@ -50,12 +56,12 @@ EOT
 
 * `group_attribute_name` - The name of the attribute containing the information of which group the connecting users belong to.
 * `metadata` - The SAML xml metadata of the Identity Provider to federate to.
-* `disable_users` - Whether account users should still be usable as a login method or not (optional, defaults to true).
-* `requested_attributes` A SAML 2.0 requested attribute that should be added to SAML requests when using this provider (optional).
-  * `is_required` Expresses that this RequestedAttribute is mandatory.
-  * `name` Name of the SAML RequestedAttribute.
+* `disable_users` - Whether local users should still be usable as a login method or not (optional, defaults to true). Administrator will always be able to login, regardless of this value.
+* `requested_attributes` A SAML 2.0 requested attribute as defined in [SAML-ReqAttrExt-v1.0](http://docs.oasis-open.org/security/saml-protoc-req-attr-req/v1.0/cs01/saml-protoc-req-attr-req-v1.0-cs01.pdf). A RequestedAttribute object will indicate that the Identity Provider should add the described attribute to the SAML assertions that will be given to the Service Provider (OVH).
+  * `is_required` Expresses that this Attribute is mandatory. If the requested attribute is not present in the assertion, the user won't be allowed to log in.
+  * `name` Name of the SAML Attribute that is required.
   * `name_format` NameFormat of the SAML RequestedAttribute.
-  * `values`  List of AttributeValues allowed for this RequestedAttribute
+  * `values`  List of AttributeValues allowed for this RequestedAttribute.
 
 ## Attributes Reference