diff --git a/doc/appendix/examples.rst b/doc/appendix/examples.rst index 907137c..7dca05c 100644 --- a/doc/appendix/examples.rst +++ b/doc/appendix/examples.rst @@ -64,18 +64,44 @@ Working with defaults Default mapping: +XML Example: + +.. code-block:: XML + + + + + + + + + + + + + + + + + + +YAML Example: + .. code-block:: yaml - 1 mapping: - 2 version: RAX-1 - 3 rules: - 4 - local: - 5 user: - 6 domain: "{D}" - 7 name: "{D}" - 8 email: "{D}" - 9 roles: "{D}" - 10 expire: "{D}" + 1 mapping: + 2 version: RAX-1 + 3 rules: + 4 - local: + 5 user: + 6 domain: "{D}" + 7 name: "{D}" + 8 email: "{D}" + 9 roles: "{D}" + 10 expire: "{D}" Resulting attributes: @@ -95,18 +121,45 @@ Resulting attributes: Accessing default from a different field: ----------------------------------------- +XML Example: + +.. code-block:: XML + + + + + + + + + + + + + + + + + + +YAML Example: + .. code-block:: yaml - 1 mapping: - 2 version: RAX-1 - 3 rules: - 4 - local: - 5 user: - 6 domain: "{D}" - 7 name: "{D}" - 8 email: "{D(name)}@rackspace.com" - 9 roles: "{D}" - 10 expire: "{D}" + 1 mapping: + 2 version: RAX-1 + 3 rules: + 4 - local: + 5 user: + 6 domain: "{D}" + 7 name: "{D}" + 8 email: "{D(name)}@rackspace.com" + 9 roles: "{D}" + 10 expire: "{D}" + Resulting attributes: @@ -125,18 +178,47 @@ Resulting attributes: More complex example with multiple substitutions ------------------------------------------------ +XML Example: + +.. code-block:: XML + + + + + + + + + + + + + + + + + + + + +YAML Example: + .. code-block:: yaml - 1 mapping: - 2 version: RAX-1 - 3 rules: - 4 - local: - 5 user: - 6 domain: "{D}" - 7 name: "{D}" - 8 email: "{D(name)} <{D(name)}@{D(domain)}.rackspace.com>" - 9 roles: "{D}" - 10 expire: "{D}" + 1 mapping: + 2 version: RAX-1 + 3 rules: + 4 - local: + 5 user: + 6 domain: "{D}" + 7 name: "{D}" + 8 email: "{D(name)} <{D(name)}@{D(domain)}.rackspace.com>" + 9 roles: "{D}" + 10 expire: "{D}" + Resulting Attributes: @@ -155,18 +237,46 @@ Resulting Attributes: Mixing in non-default attributes -------------------------------- +XML Example: + +.. code-block:: XML + + + + + + + + + + + + + + + + + + + + +YAML Example: + .. code-block:: yaml - 1 mapping: - 2 version: RAX-1 - 3 rules: - 4 - local: - 5 user: - 6 domain: "{D}" - 7 name: "{D}" - 8 email: "{At(FirstName)} {At(LastName)} <{D(name)}@{D(domain)}.rackspace.com>" - 9 roles: "{D}" - 10 expire: "{D}" + 1 mapping: + 2 version: RAX-1 + 3 rules: + 4 - local: + 5 user: + 6 domain: "{D}" + 7 name: "{D}" + 8 email: "{At(FirstName)} {At(LastName)} <{D(name)}@{D(domain)}.rackspace.com>" + 9 roles: "{D}" + 10 expire: "{D}" Resulting Attributes: diff --git a/doc/appendix/intro.rst b/doc/appendix/intro.rst index eb56ab9..5497d20 100644 --- a/doc/appendix/intro.rst +++ b/doc/appendix/intro.rst @@ -27,6 +27,12 @@ a basic understanding of the following technologies: to be human friendly. YAML is very similar to JSON but allows for useful features such as comments and the ability to easily input multi-line data. Attribute mapping policies are written in YAML. + +- **XML 1.0**: Extensible Markup Language (XML) is a universal format, + maintained by the W3C, used for representation and transfer of structured + data on the web or between different applications. XML is a markup language + that defines set of rules for encoding documents in a format that is both + human-readable and machine-readable. What is Attribute Mapping? ========================== @@ -135,6 +141,67 @@ The following attribute mapping policy implements the rules described in the previous section. The rest of this document provides a guide for writing such polices. +XML Example: + +.. code-block:: XML + + + + The following is an attribute mapping for Widgets.com. + + + + + + + + + + + + + + + + + (: + The following describes the rules for assigning roles to + users. + :) + for $group in mapping:get-attributes('groups') return + (: + If a user is a manager they get ticketing:admin, + If they are not a contractor then they also get billing:observer + Managers become admin based on the project that they are working on + :) + if ($group = 'managers') then + ( + 'ticketing:admin', + if (not(mapping:get-attributes('groups')='contractors')) then 'billing:observer' else + (), + for $project in mapping:get-attributes('manager_projects') return + ( + if ($project = 'widgets_ui') then 'admin/777654' else + if ($project = 'widgets_mobile') then 'admin/887655' else + if ($project = 'widgets_platform') then 'admin/779956' else + () + ) + ) else + (: + If a user is a member of the linux_user group they get the + nova:observer role. + :) + if ($group = 'linux_user') then 'nova:observer' else + () + + + + +YAML Example: + .. code-block:: yaml 1 mapping: @@ -181,6 +248,4 @@ for writing such polices. 42 nova:observer role. 43 :) 44 if ($group = 'linux_user') then 'nova:observer' else - 45 () - - + 45 () \ No newline at end of file diff --git a/doc/appendix/map.rst b/doc/appendix/map.rst index cad27ca..9b8535c 100644 --- a/doc/appendix/map.rst +++ b/doc/appendix/map.rst @@ -310,6 +310,34 @@ assertion: You can turn this table into an attribute mapping policy, as shown in the following example: +XML Example: + +.. code-block:: XML + + + + Simple policy where we select required attributes via an XPath. + + + + + + + + + + + + + + + +YAML Example: + .. code-block:: yaml 1 mapping: @@ -331,7 +359,7 @@ examines how the code uses XPath to extract the attribute values. Parts of the mapping policy ~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The mapping policy is a **YAML** document that contains instructions to +The mapping policy is an **XML** or a **YAML** document that contains instructions to retrieve identity attributes from a SAML assertion. It is a simple script that executes every time a SAML assertion is presented to Rackspace Identity. @@ -409,6 +437,35 @@ simply shorthand for this URI. The following example replaces the element is the same as in the preceding example, the two mapping policies produce the exact same result. +XML Example: + +.. code-block:: XML + + + + Simple policy where we select required attributes via an XPath. + + + + + + + + + + + + + + + +YAML Example: + .. code-block:: yaml 1 mapping: @@ -446,6 +503,36 @@ off chance that the operation might return multiple values in a SAML assertion. Given this new substitution, you can rewrite the mapping policy like the following example: +XML Example: + +.. code-block:: XML + + + + Simple policy where we select required attributes via an XPath. + We use {Pt()} instead of {Pts()} in single value attributes to + avoid having to select the first attribute value in XPath. + + + + + + + + + + + + + + + +YAML Example: + .. code-block:: yaml 1 mapping: @@ -477,6 +564,34 @@ a string and returns the attribute values associated with that name. By using the ``mapping:get-attributes`` function, you could rewrite the mapping policy like the following example: +XML Example: + +.. code-block:: XML + + + + Simple policy where we select required attributes via an + XPath. Here we use the mapping:get-attributes call to return attribute values. + + + + + + + + + + + + + + + +YAML Example: + .. code-block:: yaml 1 mapping: @@ -508,6 +623,34 @@ substitution returns all values for a specific attribute name, and the Given these substitutions, you can rewrite the policy as follows: +XML Example: + +.. code-block:: XML + + + + Simple policy where we select required attributes. We use At + instead of Pts as a simple means of accessing an name SAML attribute. + + + + + + + + + + + + + + + +YAML Example: + .. code-block:: yaml 1 mapping: @@ -547,6 +690,34 @@ What are the default locations in a SAML assertion for the five attributes Rackspace Identity expects? The SAML assertion in the following example has all of the values in the default places: +XML Example: + +.. code-block:: XML + + + + The default policy. All attributes are in the expected location in + the SAML assertion. + + + + + + + + + + + + + + + +YAML Example: + .. code-block:: yaml 1 mapping: diff --git a/doc/common/common-front.rst b/doc/common/common-front.rst index 6bbe8a6..1b1c121 100644 --- a/doc/common/common-front.rst +++ b/doc/common/common-front.rst @@ -24,4 +24,4 @@ should have at least one of the following Rackspace accounts: You should also be familiar with the following technologies: - SAML 2.0 -- YAML +- XML or YAML diff --git a/doc/config-3p-saml/config-adfs/adfs-attribmapping.rst b/doc/config-3p-saml/config-adfs/adfs-attribmapping.rst index 395863f..fadbcbb 100644 --- a/doc/config-3p-saml/config-adfs/adfs-attribmapping.rst +++ b/doc/config-3p-saml/config-adfs/adfs-attribmapping.rst @@ -33,7 +33,7 @@ membership in your SAML attributes, see `https://msdn.microsoft.com/en-us/library/ff359101.aspx `_ -The following example shows a Rackspace YAML (``.yml``) Attribute Mapping +The following example shows both Rackspace XML (``.xml``) as well as YAML (``.yml``) Attribute Mapping Policy that you can use when you configure your Identity Provider with Rackspace. This example assumes that you have a group named ``rackspace-billing`` with users who you want to access Rackspace billing @@ -55,6 +55,43 @@ perform the following tasks: *path* (``"{Pt}"``) syntax in the |amp| language to point to the ``NameID`` attribute in the SAML assertion, as shown in the following example: +XML Example: + +.. code-block:: XML + + + + + + + + + + + + + + + + + + + + + + + + +YAML Example: .. code-block:: yaml @@ -84,8 +121,6 @@ perform the following tasks: ) # The groups specified here are examples. You should substitute your own groups. version: RAX-1 - - - Ensure that you validate and modify the following items in your own |amp|: - The ADFS groups that users belong to and to which you want to diff --git a/doc/config-3p-saml/config-okta/okta-attribmapping.rst b/doc/config-3p-saml/config-okta/okta-attribmapping.rst index 7ae6a5b..6415a19 100644 --- a/doc/config-3p-saml/config-okta/okta-attribmapping.rst +++ b/doc/config-3p-saml/config-okta/okta-attribmapping.rst @@ -51,7 +51,7 @@ This section details how to map Okta groups to specific Rackspace attribute mapping policies. Attribute mapping policies determine the Rackspace roles and permissions assigned to Okta groups. -Update your Rackspace YAML (``.yml``) attribute mapping policy by using the +Update your Rackspace XML (``.xml``) attribute mapping policy by using the following steps: 1. Log in to the `Rackspace Customer Portal `_. @@ -75,7 +75,7 @@ section for an attribute policy mapping example ``.yml`` configuration. Attribute policy mapping example -------------------------------- -The following example shows a Rackspace YAML (``.yml``) attribute mapping +The following example shows both Rackspace XML (``.xml``) and YAML (``.yml``) attribute mapping policy that you can use when you configure your identity provider with Rackspace. This example assumes that you have a group named ``rackspace-billing`` with users that you want to access Rackspace billing @@ -87,7 +87,7 @@ Notes: - Change the ``groups`` specified in the example to match your configured Okta groups. -- Any YAML group name must match your Okta group name exactly. +- Any XML or YAML group name must match your Okta group name exactly. - At a minimum, remember to update the example's ``domain`` value to your Identity domain on the |idp| details page. - Validate that any values mapped to ``email`` and ``expire`` are @@ -96,6 +96,42 @@ Notes: *path* (``"{Pt}"``) syntax in the |amp| language to point to the ``NameID`` attribute in the SAML assertion. +XML Example: + +.. code-block:: XML + + + + + + + + + + + + + + + + + + + + + + + + +YAML Example: .. code-block:: yaml @@ -129,7 +165,7 @@ Notes: # Substitute these example groups with your own groups. See :ref:`Required SAML attributes` for a detailed -breakdown of each section of the YAML configuration. +breakdown of each section of the XML configuration. Be sure to validate and modify the following items in your policy |amp|: diff --git a/doc/config-attribute-mapping/faws-mapping.rst b/doc/config-attribute-mapping/faws-mapping.rst index 9ce042c..1d92c51 100644 --- a/doc/config-attribute-mapping/faws-mapping.rst +++ b/doc/config-attribute-mapping/faws-mapping.rst @@ -14,6 +14,32 @@ of ``observer`` or ``admin`` or omit them from the mapping policy. Users with ``admin`` permissions have read and write access to the Control Panel. The following mapping policy assigns the ``admin`` role to all federated users: +XML Example: + +.. code:: XML + + + + + + + + + + + + + + + + + + +YAML Example: + .. code:: yaml mapping: @@ -28,11 +54,45 @@ following mapping policy assigns the ``admin`` role to all federated users: roles: - "admin" + It's common to assign roles based on a user's group membership. The following mapping policy example grants the ``admin`` role to users who belong to the ``mycompany.global.admin`` group, and the ``observer`` role to users who belong to the ``mycompany.global.observer`` group: +XML Example: + +.. code:: XML + + + + + + + + + + + + + + + + + + + + + +YAML Example: + .. code:: yaml mapping: @@ -54,12 +114,49 @@ role to users who belong to the ``mycompany.global.observer`` group: ) multiValue: true + You can limit the roles of ``admin`` and ``observer`` to specific Amazon Web Services® (AWS) accounts. The preceding policy example grants the FAWS ``admin`` role to members of the ``mycompany.scoped.admin`` group on multiple AWS accounts, and the ``observer`` role to members of ``mycompany.scoped.observer`` on the single account ``12345678012``: +XML Example: + +.. code:: XML + + + + + + + + + + + + + + + + + + + + + +YAML Example: + .. code:: yaml mapping: @@ -85,6 +182,7 @@ to members of the ``mycompany.scoped.admin`` group on multiple ) multiValue: true + In the preceding example, members of both the ``mycompany.scoped.admin`` group and the ``mycompany.scoped.observer`` group have the ``admin`` role on the single FAWS account ``12345678012``. @@ -94,6 +192,43 @@ only the ``observer`` role on that single account to any user in both groups. This assignment occurs because the first ``if`` condition matches, so the policy doesn't evaluate the second ``if`` condition. +XML Example: + +.. code:: XML + + + + + + + + + + + + + + + + + + + + + +YAML Example: + .. code:: yaml mapping: @@ -119,6 +254,7 @@ matches, so the policy doesn't evaluate the second ``if`` condition. ) multiValue: true + Visit the `User Management and Permissions `_ section of the Fanatical Support for AWS product guide for further details. @@ -130,6 +266,39 @@ features within the AWS Web Console. The following mapping policy assigns all users the "ViewOnlyAccess" IAM policy for all AWS accounts. It also assigns the "AdministratorAccess" IAM policy to all users for a single AWS account. +XML Example: + +.. code:: XML + + + + + + + + + + + + + + + + + + + + + +YAML Example: + .. code:: yaml mapping: @@ -147,6 +316,7 @@ users the "ViewOnlyAccess" IAM policy for all AWS accounts. It also assigns the iamPolicies:123456789012: - "arn:aws:iam::aws:policy/AdministratorAccess" + As with Fanatical Support for AWS permissions, it's much more common to assign IAM policies conditionally based on a user's group membership. The mapping policy assigns permissions as follows: @@ -158,6 +328,48 @@ policy assigns permissions as follows: * Users in the ``mycompany.12345678012.admin`` group are only assigned the ``AdministratorAccess`` IAM policy for AWS account ``123456789012``. +XML Example: + +.. code:: XML + + + + + + + + + + + + + + + + + + + + + + + + + +YAML Example: + .. code:: yaml mapping: @@ -187,6 +399,7 @@ policy assigns permissions as follows: ) multiValue: true + In the preceding example, members of the ``mycompany.global.security`` and the ``mycompany.123456789012.admin`` groups, have the``AdministratorAccess`` IAM policy. In this case, the @@ -212,6 +425,41 @@ through the Fanatical Support for AWS Control Panel. The following mapping policy grants users in the ``mycompany.global.admin`` group permission to create new AWS accounts: +XML Example: + +.. code:: XML + + + + + + + + + + + + + + + + + + + + + + + +YAML Example: + .. code:: yaml mapping: @@ -232,12 +480,90 @@ create new AWS accounts: ) multiValue: false + Complete mapping policy example ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The following example combines both Fanatical Support for AWS permissions and AWS Console and API permissions into a single mapping policy: +XML Example: + +.. code:: XML + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +YAML Example: + .. code:: yaml --- diff --git a/doc/config-attribute-mapping/index.rst b/doc/config-attribute-mapping/index.rst index 50a7c6b..917ca83 100644 --- a/doc/config-attribute-mapping/index.rst +++ b/doc/config-attribute-mapping/index.rst @@ -4,7 +4,7 @@ Configure Attribute Mapping =========================== -Attribute Mapping Policies are YAML-formatted files that are used +Attribute Mapping Policies are YAML or XML-formatted files that are used to map SAML attributes to Rackspace-required fields, such as roles and account permissions. diff --git a/doc/config-attribute-mapping/required-mapping.rst b/doc/config-attribute-mapping/required-mapping.rst index 977fb80..d4b307c 100644 --- a/doc/config-attribute-mapping/required-mapping.rst +++ b/doc/config-attribute-mapping/required-mapping.rst @@ -49,7 +49,7 @@ Your |amp| must contain: to assign to the user. - YAML array of alphanumeric strings - | **Example:** - | + | | ``roles:`` | ``- "nova:admin"`` | ``- "lbaas:observer"`` @@ -122,7 +122,33 @@ SAML providers, see :ref:`index-configuring-3p-saml-ug`. |ampref| - .. code-block:: yaml +XML Example: + +.. code-block:: XML + + + + + + + + + + + + + + + + + + +YAML Example: + +.. code-block:: yaml mapping: version: "RAX-1" diff --git a/doc/config-attribute-mapping/rscloud-mapping.rst b/doc/config-attribute-mapping/rscloud-mapping.rst index 93ebc65..6ad08dd 100644 --- a/doc/config-attribute-mapping/rscloud-mapping.rst +++ b/doc/config-attribute-mapping/rscloud-mapping.rst @@ -14,6 +14,32 @@ that you assign in the |amp|. The following code shows a basic example of an |amp| for Rackspace Cloud: +XML Example: + +.. code:: XML + + + + + + + + + + + + + + + + + + +YAML Example: + .. code:: yaml mapping: @@ -57,6 +83,41 @@ Permissions by groups example - Cloud The following code shows a complex example of an |amp| for Rackspace Cloud: +XML Example: + +.. code:: XML + + + + + + + + + + + + + + + + + + + + + +YAML Example: + .. code:: yaml mapping: @@ -79,6 +140,7 @@ The following code shows a complex example of an |amp| for Rackspace Cloud: multiValue: true version: RAX-1 + This example uses the substitution and piping features of the |amp|, in conjunction with XPath, to observe the SAML ``groups`` value and to assign values to the local ``role`` value based on any matching scenarios. (The @@ -95,6 +157,41 @@ Permissions by groups example - Dedicated Hosting The following code shows a complex example of an |amp| for Dedicated Hosting: +XML Example: + +.. code:: XML + + + + + + + + + + + + + + + + + + + + + +YAML Example: + .. code:: yaml mapping: @@ -114,4 +211,4 @@ Hosting: if (mapping:get-attributes('groups')='user_group') then ('user-group-user') else (), if (mapping:get-attributes('groups')='low_group') then ('user-group-low') else () ) - version: RAX-1 + version: RAX-1 \ No newline at end of file diff --git a/doc/gettingstarted/config-am-policy.rst b/doc/gettingstarted/config-am-policy.rst index c486407..0efd99f 100644 --- a/doc/gettingstarted/config-am-policy.rst +++ b/doc/gettingstarted/config-am-policy.rst @@ -4,7 +4,7 @@ Configure the Attribute Mapping Policy ====================================== -The |amp| is a YAML-formatted policy for managing the mapping of SAML +The |amp| is an XML or YAML-formatted policy for managing the mapping of SAML attributes to Rackspace required roles and permissions. A default |amp| is provided when your |idp| is created. This policy shows the @@ -13,6 +13,32 @@ shown in the following example. **Default Attribute Mapping Policy** +XML Example: + +.. code-block:: XML + + + + + + + + + + + + + + + + + + +YAML Example: + .. code-block:: yaml mapping: @@ -26,7 +52,6 @@ shown in the following example. expire: "{D}" version: "RAX-1" - The default |amp| **must** be customized to specific values before your users log in or are able to use Rackspace products and services. For more information on Attribute Mapping, see :ref:`config-attribute-mapping-ug`. To see examples diff --git a/doc/manage-idps/index.rst b/doc/manage-idps/index.rst index 831f3f2..0b015dd 100644 --- a/doc/manage-idps/index.rst +++ b/doc/manage-idps/index.rst @@ -59,9 +59,8 @@ that you have provided. Update the |amp| ~~~~~~~~~~~~~~~~ -To update the |amp| for your |idp|, upload a new YAML file by using the +To update the |amp| for your |idp|, upload a new XML or YAML file by using the **Update Policy File** link in the |idp| details page. -The file must be valid YAML, and the file extension should be ``.yml`` or -``.yaml``. To validate your YAML, you can use any YAML validation library or +The file must be valid XML or YAML, and the file extensions should be ``.xml`` or ``.yaml`` or ``.yml``. To validate your document, you can use any XML or YAML validation library or website. diff --git a/doc/overview/features.rst b/doc/overview/features.rst index af7adc0..ab2b683 100644 --- a/doc/overview/features.rst +++ b/doc/overview/features.rst @@ -20,5 +20,5 @@ The following table describes the main features of |service|: - Enables customers to connect to Rackspace with their own company credentials instead of requiring new credentials. * - Provides attribute mapping policy capability - - Uses a rich, YAML-based, policy language that enables you to dynamically + - Uses a rich, YAML-based or XML-based, policy language that enables you to dynamically configure the roles and permissions that users receive when they log in.