Document SAML Provider Objects

Added the following:
.. _ref-attribute-mapping:

Attribute Statement Mapping Rules
"""""""""""""""""""""""""""""""""

This is an collection of rules. Each of these rules maps an SAML attribute passed by the SAML Identity Provider to one or more Stormpath Account or Account customData attributes. For more detailed information about how these rules are configured, see :ref:`the Authentication chapter <saml-mapping>`,

**Attribute Statement Mapping Rules URL**

``/v1/attributeStatementMappingRules/$ATTRIBUTE_STATEMENT_MAPPING_RULES_ID``

**Attribute Statement Mapping Rules Attributes**

.. list-table::
  :widths: 20 10 70
  :header-rows: 1

  * - Attribute
    - Type
    - Description

  * - ``name``
    - String
    - The SAML Attribute name that will be passed from your Identity Provider.

  * - ``nameFormat``
    - String
    - (Optional) The name format for the above-specified SAML Attribute, expressed as a Uniform Resource Name (URN).

  * - ``accountAttributes``
    - Array
    - This is an array of Stormpath Account or customData (``customData.$KEY_NAME``) attributes that will map to this SAML Attribute.

**Attribute Statement Mapping Rules Example**

.. code-block:: json

  {
    "href": "https://api.stormpath.com/v1/attributeStatementMappingRules/PybI8DObmohmOIexample",
    "createdAt": "2016-01-21T17:47:34.980Z",
    "modifiedAt": "2016-01-28T21:58:47.839Z",
    "items": [
        {
            "name": "User.FirstName",
            "nameFormat": null,
            "accountAttributes": [
                "givenName"
            ]
        },
        {
            "name": "User.LastName",
            "nameFormat": null,
            "accountAttributes": [
                "surname"
            ]
        }
    ]
  }

.. _ref-sp-metadata:

Service Provider Metadata
"""""""""""""""""""""""""

This object contains the SAML Service Provider information about Stormpath that is required for the Service Provider-initiated SAML flow. The object by default returns as XML, but it is possible to get JSON by adding an ``Accept: application/json`` header to your request. For more information about how to use this, please see :ref:`the Authentication chapter <configure-sp-in-idp>`.

**Service Provider Metadata URL**

``/v1/samlServiceProviderMetadatas/$SERVICE_PROVIDER_METADATA_ID``

**Service Provider Metadata Elements**

.. list-table::
  :widths: 15 10 20 60
  :header-rows: 1

  * - Attribute
    - Type
    - Valid Value(s)
    - Description

  * - ``href``
    - String
    - N/A
    - The resource's fully qualified location URL.

  * - ``createdAt``
    - String
    - ISO-8601 Datetime
    - Indicates when this resource was created.

  * - ``modifiedAt``
    - String
    - ISO-8601 Datetime
    - Indicates when this resource’s attributes were last modified.

  * - ``entityId``
    - String
    - URN-formatted
    - The entity ID of the Stormpath SAML Directory in URN-format.

  * - ``assertionConsumerServicePostEndpoint``
    - Link
    - N/A
    - The ACS Endpoint required by your Identity Provider.

  * - ``x509SigningCert``
    - Link
    - N/A
    - An XML x509 Signing Certificate that will return with ``Content-Type: application/pkix-cert``. If you retrieve XML instead of JSON, the certificate will be embedded in the response.

**Service Provider Metadata JSON Example**

.. code-block:: json

  {
    "href": "https://api.stormpath.com/v1/samlServiceProviderMetadatas/QLoznDKpnXuX77example",
    "createdAt": "2016-01-21T17:47:35.313Z",
    "modifiedAt": "2016-01-21T17:47:35.313Z",
    "entityId": "urn:stormpath:directory:PwrCmDmJisz3uDexample:provider:sp",
    "assertionConsumerServicePostEndpoint": {
        "href": "https://api.stormpath.com/v1/directories/PwrCmDmJisz3uDexample/saml/sso/post"
    },
    "x509SigningCert": {
        "href": "https://api.stormpath.com/v1/x509certificates/QLXha2bQ9f4d1Rexample"
    }
  }

**Service Provider Metadata XML Example**

.. code-block:: xml

  <?xml version="1.0" encoding="UTF-8"?>
  <md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" entityID="urn:stormpath:directory:PwrCmDmJisz3uDexample:provider:sp">
    <md:SPSSODescriptor protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
      <md:KeyDescriptor use="signing">
        <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
          <ds:X509Data>
            <ds:X509Certificate>MIIC1zCCAb+TRUNACATED</ds:X509Certificate>
          </ds:X509Data>
        </ds:KeyInfo>
      </md:KeyDescriptor>
      <md:NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress</md:NameIDFormat>
      <md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://api.stormpath.com/v1/directories/PwrCmDmJisz3uDexample/saml/sso/post" index="0" />
    </md:SPSSODescriptor>
  </md:EntityDescriptor>
stormpath / stormpath-documentation

Document SAML Provider Objects #129
