From 237286d33e4b92ed884f4a5b3dbdb52f2688123f Mon Sep 17 00:00:00 2001 From: anuritjain Date: Thu, 30 Jul 2020 21:30:38 +0530 Subject: [PATCH 1/7] updated docs with XML examples --- doc/appendix/examples.rst | 114 +++++++- doc/appendix/intro.rst | 61 ++++- doc/appendix/map.rst | 153 ++++++++++- doc/common/common-front.rst | 2 +- .../config-adfs/adfs-attribmapping.rst | 37 ++- .../config-okta/okta-attribmapping.rst | 37 ++- doc/config-attribute-mapping/faws-mapping.rst | 254 ++++++++++++++++++ doc/config-attribute-mapping/index.rst | 2 +- .../required-mapping.rst | 34 ++- .../rscloud-mapping.rst | 127 +++++---- doc/gettingstarted/config-am-policy.rst | 25 +- doc/manage-idps/index.rst | 5 +- doc/overview/features.rst | 2 +- 13 files changed, 762 insertions(+), 91 deletions(-) diff --git a/doc/appendix/examples.rst b/doc/appendix/examples.rst index 907137c..4ef7046 100644 --- a/doc/appendix/examples.rst +++ b/doc/appendix/examples.rst @@ -64,18 +64,40 @@ Working with defaults Default mapping: +.. code-block:: xml + + + + + + + + + + + + + + + + + + .. 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,6 +117,28 @@ Resulting attributes: Accessing default from a different field: ----------------------------------------- +.. code-block:: xml + + + + + + + + + + + + + + + + + + .. code-block:: yaml 1 mapping: @@ -108,6 +152,7 @@ Accessing default from a different field: 9 roles: "{D}" 10 expire: "{D}" + Resulting attributes: +--------+--------------------------+ @@ -125,6 +170,30 @@ Resulting attributes: More complex example with multiple substitutions ------------------------------------------------ +.. code-block:: xml + + + + + + + + + + + + + + + + + + + + .. code-block:: yaml 1 mapping: @@ -138,6 +207,7 @@ More complex example with multiple substitutions 9 roles: "{D}" 10 expire: "{D}" + Resulting Attributes: +--------+------------------------------------------+ @@ -155,6 +225,30 @@ Resulting Attributes: Mixing in non-default attributes -------------------------------- +.. code-block:: xml + + + + + + + + + + + + + + + + + + + + .. code-block:: yaml 1 mapping: diff --git a/doc/appendix/intro.rst b/doc/appendix/intro.rst index eb56ab9..9796391 100644 --- a/doc/appendix/intro.rst +++ b/doc/appendix/intro.rst @@ -23,10 +23,6 @@ a basic understanding of the following technologies: information from structured data and is designed to be embedded in a host language. -- **YAML 1.1**: YAML is a simple data serialization language that is designed - 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. What is Attribute Mapping? ========================== @@ -135,6 +131,59 @@ 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. +.. 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 + () + + + .. code-block:: yaml 1 mapping: @@ -181,6 +230,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..28ed4d5 100644 --- a/doc/appendix/map.rst +++ b/doc/appendix/map.rst @@ -310,6 +310,31 @@ assertion: You can turn this table into an attribute mapping policy, as shown in the following example: +.. code-block:: xml + + + + Simple policy where we select required attributes via an XPath. + + + + + + + + + + + + + + + + .. code-block:: yaml 1 mapping: @@ -331,7 +356,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 a **XML** 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 +434,32 @@ 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. +.. code-block:: xml + + + + Simple policy where we select required attributes via an XPath. + + + + + + + + + + + + + + + + .. code-block:: yaml 1 mapping: @@ -446,6 +497,32 @@ 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: +.. 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. + + + + + + + + + + + + + + + .. code-block:: yaml 1 mapping: @@ -477,6 +554,31 @@ 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: +.. 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. + + + + + + + + + + + + + + + .. code-block:: yaml 1 mapping: @@ -508,6 +610,31 @@ substitution returns all values for a specific attribute name, and the Given these substitutions, you can rewrite the policy as follows: +.. 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. + + + + + + + + + + + + + + + .. code-block:: yaml 1 mapping: @@ -547,6 +674,30 @@ 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: +.. code-block:: xml + + + + The default policy. All attributes are in the expected location + in the SAML assertion. + + + + + + + + + + + + + + + .. 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..d4589ae 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 @@ -56,9 +56,40 @@ perform the following tasks: attribute in the SAML assertion, as shown in the following example: +.. code-block:: xml + + + + + + + + + + + + + + + + + + + + + + + + .. code-block:: yaml - mapping: +mapping: rules: - local: faws: @@ -84,8 +115,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..4d5d74b 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 @@ -97,6 +97,35 @@ Notes: attribute in the SAML assertion. +.. code-block:: xml + + + + + + + + + + + + + + + + + + + + + + + + .. code-block:: yaml mapping: @@ -129,7 +158,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..6c87b28 100644 --- a/doc/config-attribute-mapping/faws-mapping.rst +++ b/doc/config-attribute-mapping/faws-mapping.rst @@ -14,6 +14,28 @@ 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: +.. code:: xml + + + + + + + + + + + + + + + + + + .. code:: yaml mapping: @@ -28,11 +50,38 @@ 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: +.. code:: xml + + + + + + + + + + + + + + + + + + + + + .. code:: yaml mapping: @@ -54,12 +103,39 @@ 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``: +.. code:: xml + + + + + + + + + + + + + + + + + + + + + .. code:: yaml mapping: @@ -85,6 +161,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 +171,32 @@ 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. +.. code:: xml + + + + + + + + + + + + + + + + + + + + + .. code:: yaml mapping: @@ -119,6 +222,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 +234,35 @@ 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. +.. code:: xml + + + + + + + + + + + + + + + + + + + + + .. code:: yaml mapping: @@ -147,6 +280,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 +292,37 @@ policy assigns permissions as follows: * Users in the ``mycompany.12345678012.admin`` group are only assigned the ``AdministratorAccess`` IAM policy for AWS account ``123456789012``. +.. code:: xml + + + + + + + + + + + + + + + + + + + + + + + + + .. code:: yaml mapping: @@ -187,6 +352,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 +378,34 @@ 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: +.. code:: xml + + + + + + + + + + + + + + + + + + + + + + + .. code:: yaml mapping: @@ -232,12 +426,72 @@ 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: +.. code:: xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + .. 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..515d81f 100644 --- a/doc/config-attribute-mapping/required-mapping.rst +++ b/doc/config-attribute-mapping/required-mapping.rst @@ -47,9 +47,17 @@ Your |amp| must contain: * - **roles** - The product RBAC (role-based access control) roles that you want to assign to the user. - - YAML array of alphanumeric strings + - XML array of alphanumeric strings - | **Example:** | + | + | + | + | + | + - YAML array of alphanumeric strings + - | **Example:** + | | ``roles:`` | ``- "nova:admin"`` | ``- "lbaas:observer"`` @@ -122,7 +130,29 @@ SAML providers, see :ref:`index-configuring-3p-saml-ug`. |ampref| - .. code-block:: yaml +.. code-block:: xml + + + + + + + + + + + + + + + + + + +.. 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..e521ca2 100644 --- a/doc/config-attribute-mapping/rscloud-mapping.rst +++ b/doc/config-attribute-mapping/rscloud-mapping.rst @@ -14,20 +14,27 @@ that you assign in the |amp|. The following code shows a basic example of an |amp| for Rackspace Cloud: -.. code:: yaml - - mapping: - rules: - - local: - user: - domain: '999994919999' - email: "{At(http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress)}" - expire: "PT12H" - name: "{D}" - roles: - - "admin" - - "ticketing:admin" - version: RAX-1 +.. code:: xml + + + + + + + + + + + + + + + + + In this example, the ``admin`` and ``ticketing:admin`` roles are explicitly assigned to any users who log in by using this |idp| and |amp|. @@ -57,27 +64,32 @@ Permissions by groups example - Cloud The following code shows a complex example of an |amp| for Rackspace Cloud: -.. code:: yaml - - mapping: - rules: - - local: - user: - domain: '9999953939' - email: "{At(urn:oid:1.2.840.113549.1.9.1.1)}" - expire: "{Pt(/saml2p:Response/saml2:Assertion/saml2:Conditions/@NotOnOrAfter[1])}" - name: "{D}" - roles: - - "{0}" - remote: - - path: | - ( - if (mapping:get-attributes('http://schemas.xmlsoap.org/claims/Group')='mycompany.rackspace.admin') then ('billing:admin', 'ticketing:admin','admin') else (), - if (mapping:get-attributes('http://schemas.xmlsoap.org/claims/Group')='mycompany.rackspace.billing') then 'billing:admin' else (), - if (mapping:get-attributes('http://schemas.xmlsoap.org/claims/Group')='mycompany.rackspace.ticketing') then 'ticketing:admin' else () - ) - multiValue: true - version: RAX-1 +.. code:: xml + + + + + + + + + + + + + + + + + + + + + This example uses the substitution and piping features of the |amp|, in conjunction with XPath, to observe the SAML ``groups`` value and to assign @@ -95,23 +107,28 @@ Permissions by groups example - Dedicated Hosting The following code shows a complex example of an |amp| for Dedicated Hosting: -.. code:: yaml - - mapping: - rules: - - local: - user: - domain: "{D}" - email: "{Pt(/saml2p:Response/saml2:Assertion/saml2:Subject/saml2:NameID)}" - expire: PT12H - groups: "{0}" - name: "{D}" - remote: - - multiValue: true - path: | - ( - if (mapping:get-attributes('groups')='admin_group') then ('user-group-admin') else (), - 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 +.. code:: xml + + + + + + + + + + + + + + + + + + + + diff --git a/doc/gettingstarted/config-am-policy.rst b/doc/gettingstarted/config-am-policy.rst index c486407..f2960d1 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,28 @@ shown in the following example. **Default Attribute Mapping Policy** +.. code-block:: xml + + + + + + + + + + + + + + + + + + .. code-block:: yaml mapping: @@ -26,7 +48,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..cf1c6ee 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 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, and the file extensions should be ``.xml``. To validate your XML, you can use any XML validation library or website. diff --git a/doc/overview/features.rst b/doc/overview/features.rst index af7adc0..bfd5d3b 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, XML-based, policy language that enables you to dynamically configure the roles and permissions that users receive when they log in. From e969027c59b92f62185bc570b2b3c5e0e6c779e4 Mon Sep 17 00:00:00 2001 From: anuritjain Date: Fri, 31 Jul 2020 16:06:27 +0530 Subject: [PATCH 2/7] fixed indentation --- doc/appendix/examples.rst | 194 ++++---- doc/appendix/intro.rst | 102 ++-- doc/appendix/map.rst | 175 ++++--- .../config-adfs/adfs-attribmapping.rst | 65 +-- .../config-okta/okta-attribmapping.rst | 60 +-- doc/config-attribute-mapping/faws-mapping.rst | 466 ++++++++++-------- .../required-mapping.rst | 42 +- .../rscloud-mapping.rst | 152 ++++-- doc/gettingstarted/config-am-policy.rst | 28 +- doc/manage-idps/index.rst | 4 +- doc/overview/features.rst | 2 +- 11 files changed, 702 insertions(+), 588 deletions(-) diff --git a/doc/appendix/examples.rst b/doc/appendix/examples.rst index 4ef7046..5ef83a1 100644 --- a/doc/appendix/examples.rst +++ b/doc/appendix/examples.rst @@ -64,7 +64,7 @@ Working with defaults Default mapping: -.. code-block:: xml +.. code-block:: XML - + - + @@ -117,40 +117,40 @@ Resulting attributes: Accessing default from a different field: ----------------------------------------- -.. code-block:: xml +.. code-block:: XML - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + .. 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: @@ -170,42 +170,42 @@ Resulting attributes: More complex example with multiple substitutions ------------------------------------------------ -.. code-block:: xml +.. code-block:: XML - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + .. 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: @@ -225,42 +225,42 @@ Resulting Attributes: Mixing in non-default attributes -------------------------------- -.. code-block:: xml +.. code-block:: XML - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + .. 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 9796391..c9f03a7 100644 --- a/doc/appendix/intro.rst +++ b/doc/appendix/intro.rst @@ -131,58 +131,58 @@ 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. -.. 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. +.. code-block:: XML + + + + The following is an attribute mapping for Widgets.com. + + + + + + + + + + + + + (: + The following describes the rules for assigning roles to + users. :) - if ($group = 'linux_user') then 'nova:observer' else - () - - + 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 + () + + .. code-block:: yaml diff --git a/doc/appendix/map.rst b/doc/appendix/map.rst index 28ed4d5..6d21bb1 100644 --- a/doc/appendix/map.rst +++ b/doc/appendix/map.rst @@ -310,29 +310,29 @@ assertion: You can turn this table into an attribute mapping policy, as shown in the following example: -.. code-block:: xml - - - - Simple policy where we select required attributes via an XPath. - - +.. code-block:: XML + + + + Simple policy where we select required attributes via an XPath. + + + multiValue="true"/> - - - + + + .. code-block:: yaml @@ -434,30 +434,30 @@ 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. -.. code-block:: xml - - - - Simple policy where we select required attributes via an XPath. - - +.. code-block:: XML + + + + Simple policy where we select required attributes via an XPath. + + + multiValue="true"/> - - - + + + .. code-block:: yaml @@ -497,31 +497,31 @@ 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: -.. 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. - - +.. 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. + + + multiValue="true"/> - - - + + + .. code-block:: yaml @@ -554,18 +554,17 @@ 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: -.. 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. - - +.. 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. + + @@ -575,9 +574,9 @@ policy like the following example: - - - + + + .. code-block:: yaml @@ -610,18 +609,17 @@ substitution returns all values for a specific attribute name, and the Given these substitutions, you can rewrite the policy as follows: -.. 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. - - +.. 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. + + @@ -631,9 +629,9 @@ attribute. - - - + + + .. code-block:: yaml @@ -674,17 +672,16 @@ 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: -.. code-block:: xml - - - - The default policy. All attributes are in the expected location - in the SAML assertion. - - +.. code-block:: XML + + + + The default policy. All attributes are in the expected location in the SAML assertion. + + @@ -694,9 +691,9 @@ example has all of the values in the default places: - - - + + + .. code-block:: yaml diff --git a/doc/config-3p-saml/config-adfs/adfs-attribmapping.rst b/doc/config-3p-saml/config-adfs/adfs-attribmapping.rst index d4589ae..4b26d32 100644 --- a/doc/config-3p-saml/config-adfs/adfs-attribmapping.rst +++ b/doc/config-3p-saml/config-adfs/adfs-attribmapping.rst @@ -56,40 +56,43 @@ perform the following tasks: attribute in the SAML assertion, as shown in the following example: -.. code-block:: xml - - - - - - - - - - - - - - - - - - - - - - - +.. code-block:: XML + + + + + + + + + + + + + + + + + + + + + + + .. code-block:: yaml -mapping: + mapping: rules: - local: faws: diff --git a/doc/config-3p-saml/config-okta/okta-attribmapping.rst b/doc/config-3p-saml/config-okta/okta-attribmapping.rst index 4d5d74b..884f4d6 100644 --- a/doc/config-3p-saml/config-okta/okta-attribmapping.rst +++ b/doc/config-3p-saml/config-okta/okta-attribmapping.rst @@ -97,34 +97,38 @@ Notes: attribute in the SAML assertion. -.. code-block:: xml - - - - - - - - - - - - - - - - - - - - - - - +.. code-block:: XML + + + + + + + + + + + + + + + + + + + + + + + .. code-block:: yaml diff --git a/doc/config-attribute-mapping/faws-mapping.rst b/doc/config-attribute-mapping/faws-mapping.rst index 6c87b28..5d0f8be 100644 --- a/doc/config-attribute-mapping/faws-mapping.rst +++ b/doc/config-attribute-mapping/faws-mapping.rst @@ -14,27 +14,27 @@ 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: -.. code:: xml - - - - - - +.. code:: XML + + + + + + - - - - - + + + + + - - - - + + + + .. code:: yaml @@ -56,31 +56,34 @@ 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: -.. code:: xml +.. code:: XML - - - - - + + + + + - - - - - + + + + + - - - - - - - + + + + + + + .. code:: yaml @@ -110,31 +113,37 @@ 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``: -.. code:: xml +.. code:: XML - - - - - + + + + + - - - - - + + + + + - - - - - - - + + + + + + + .. code:: yaml @@ -171,31 +180,38 @@ 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. -.. code:: xml +.. code:: XML - - - - - + + + + + - - - - - + + + + + - - - - - - - + + + + + + + .. code:: yaml @@ -234,34 +250,34 @@ 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. -.. code:: xml +.. code:: XML - - - - - + + + + + - - - - + + + + - - + + - - - - + + + + .. code:: yaml @@ -292,36 +308,43 @@ policy assigns permissions as follows: * Users in the ``mycompany.12345678012.admin`` group are only assigned the ``AdministratorAccess`` IAM policy for AWS account ``123456789012``. -.. code:: xml +.. code:: XML - - - - - + + + + + - - - - + + + + - - + + - - - - - - - - + + + + + + + + .. code:: yaml @@ -378,33 +401,36 @@ 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: -.. code:: xml +.. code:: XML - - - - - + + + + + - - - - + + + + - + - - - - - - - + + + + + + + .. code:: yaml @@ -433,64 +459,78 @@ 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: -.. code:: xml - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.. code:: XML + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + .. code:: yaml diff --git a/doc/config-attribute-mapping/required-mapping.rst b/doc/config-attribute-mapping/required-mapping.rst index 515d81f..ef65eab 100644 --- a/doc/config-attribute-mapping/required-mapping.rst +++ b/doc/config-attribute-mapping/required-mapping.rst @@ -130,27 +130,27 @@ SAML providers, see :ref:`index-configuring-3p-saml-ug`. |ampref| -.. code-block:: xml - - - - - - - - - - - - - - - - - +.. code-block:: XML + + + + + + + + + + + + + + + + + .. code-block:: yaml diff --git a/doc/config-attribute-mapping/rscloud-mapping.rst b/doc/config-attribute-mapping/rscloud-mapping.rst index e521ca2..c4c4d81 100644 --- a/doc/config-attribute-mapping/rscloud-mapping.rst +++ b/doc/config-attribute-mapping/rscloud-mapping.rst @@ -14,7 +14,7 @@ that you assign in the |amp|. The following code shows a basic example of an |amp| for Rackspace Cloud: -.. code:: xml +.. code:: XML - - - - - - - - - + + + + + + + + + +.. code:: yaml + + mapping: + rules: + - local: + user: + domain: '999994919999' + email: "{At(http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress)}" + expire: "PT12H" + name: "{D}" + roles: + - "admin" + - "ticketing:admin" + version: RAX-1 + In this example, the ``admin`` and ``ticketing:admin`` roles are explicitly assigned to any users who log in by using this |idp| and |amp|. @@ -64,7 +79,7 @@ Permissions by groups example - Cloud The following code shows a complex example of an |amp| for Rackspace Cloud: -.. code:: xml +.. code:: XML - - - - - - - - - + + + + + + + + + - + +.. code:: yaml + + mapping: + rules: + - local: + user: + domain: '9999953939' + email: "{At(urn:oid:1.2.840.113549.1.9.1.1)}" + expire: "{Pt(/saml2p:Response/saml2:Assertion/saml2:Conditions/@NotOnOrAfter[1])}" + name: "{D}" + roles: + - "{0}" + remote: + - path: | + ( + if (mapping:get-attributes('http://schemas.xmlsoap.org/claims/Group')='mycompany.rackspace.admin') then ('billing:admin', 'ticketing:admin','admin') else (), + if (mapping:get-attributes('http://schemas.xmlsoap.org/claims/Group')='mycompany.rackspace.billing') then 'billing:admin' else (), + if (mapping:get-attributes('http://schemas.xmlsoap.org/claims/Group')='mycompany.rackspace.ticketing') then 'ticketing:admin' else () + ) + 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 @@ -107,28 +149,54 @@ Permissions by groups example - Dedicated Hosting The following code shows a complex example of an |amp| for Dedicated Hosting: -.. code:: xml +.. code:: XML - - - - + + + + - - - - - + + + + + - - - - - - + + + + + + + +.. code:: yaml + + mapping: + rules: + - local: + user: + domain: "{D}" + email: "{Pt(/saml2p:Response/saml2:Assertion/saml2:Subject/saml2:NameID)}" + expire: PT12H + groups: "{0}" + name: "{D}" + remote: + - multiValue: true + path: | + ( + if (mapping:get-attributes('groups')='admin_group') then ('user-group-admin') else (), + 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 \ No newline at end of file diff --git a/doc/gettingstarted/config-am-policy.rst b/doc/gettingstarted/config-am-policy.rst index f2960d1..7950b21 100644 --- a/doc/gettingstarted/config-am-policy.rst +++ b/doc/gettingstarted/config-am-policy.rst @@ -13,26 +13,28 @@ shown in the following example. **Default Attribute Mapping Policy** -.. code-block:: xml +.. code-block:: XML + - - - - + + + + - + - + - - - + + + .. code-block:: yaml diff --git a/doc/manage-idps/index.rst b/doc/manage-idps/index.rst index cf1c6ee..a3566f1 100644 --- a/doc/manage-idps/index.rst +++ b/doc/manage-idps/index.rst @@ -59,8 +59,8 @@ that you have provided. Update the |amp| ~~~~~~~~~~~~~~~~ -To update the |amp| for your |idp|, upload a new XML 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 XML, and the file extensions should be ``.xml``. To validate your XML, you can use any XML validation library or +The file must be valid XML or YAML, and the file extensions should be ``.xml`` or ``.yaml``. To validate your XML or YAML, you can use any XML or YAML validation library or website. diff --git a/doc/overview/features.rst b/doc/overview/features.rst index bfd5d3b..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, XML-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. From b20c44a8c18e72b202113463b3c268105d6335e9 Mon Sep 17 00:00:00 2001 From: anuritjain Date: Fri, 31 Jul 2020 18:34:12 +0530 Subject: [PATCH 3/7] fixed code changes --- doc/config-attribute-mapping/required-mapping.rst | 8 -------- doc/config-attribute-mapping/rscloud-mapping.rst | 2 +- doc/gettingstarted/config-am-policy.rst | 12 +++++------- 3 files changed, 6 insertions(+), 16 deletions(-) diff --git a/doc/config-attribute-mapping/required-mapping.rst b/doc/config-attribute-mapping/required-mapping.rst index ef65eab..16ad6eb 100644 --- a/doc/config-attribute-mapping/required-mapping.rst +++ b/doc/config-attribute-mapping/required-mapping.rst @@ -47,14 +47,6 @@ Your |amp| must contain: * - **roles** - The product RBAC (role-based access control) roles that you want to assign to the user. - - XML array of alphanumeric strings - - | **Example:** - | - | - | - | - | - | - YAML array of alphanumeric strings - | **Example:** | diff --git a/doc/config-attribute-mapping/rscloud-mapping.rst b/doc/config-attribute-mapping/rscloud-mapping.rst index c4c4d81..9bdf7e2 100644 --- a/doc/config-attribute-mapping/rscloud-mapping.rst +++ b/doc/config-attribute-mapping/rscloud-mapping.rst @@ -16,7 +16,7 @@ Rackspace Cloud: .. code:: XML - + - + + From 79a3abcda806bf0ff4c05e48c250b547f03b1eb0 Mon Sep 17 00:00:00 2001 From: anuritjain Date: Fri, 31 Jul 2020 20:09:15 +0530 Subject: [PATCH 4/7] added headings to examples --- doc/appendix/examples.rst | 16 +++ doc/appendix/intro.rst | 4 + doc/appendix/map.rst | 22 ++++ .../config-adfs/adfs-attribmapping.rst | 3 + .../config-okta/okta-attribmapping.rst | 3 + doc/config-attribute-mapping/faws-mapping.rst | 32 ++++++ .../required-mapping.rst | 4 + .../rscloud-mapping.rst | 106 ++++++++++-------- doc/gettingstarted/config-am-policy.rst | 42 +++---- 9 files changed, 166 insertions(+), 66 deletions(-) diff --git a/doc/appendix/examples.rst b/doc/appendix/examples.rst index 5ef83a1..1bccea6 100644 --- a/doc/appendix/examples.rst +++ b/doc/appendix/examples.rst @@ -64,6 +64,8 @@ Working with defaults Default mapping: +XML Example: + .. code-block:: XML @@ -86,6 +88,8 @@ Default mapping: +YAML Example: + .. code-block:: yaml 1 mapping: @@ -117,6 +121,8 @@ Resulting attributes: Accessing default from a different field: ----------------------------------------- +XML Example: + .. code-block:: XML @@ -139,6 +145,8 @@ Accessing default from a different field: +YAML Example: + .. code-block:: yaml 1 mapping: @@ -170,6 +178,8 @@ Resulting attributes: More complex example with multiple substitutions ------------------------------------------------ +XML Example: + .. code-block:: XML @@ -194,6 +204,8 @@ More complex example with multiple substitutions +YAML Example: + .. code-block:: yaml 1 mapping: @@ -225,6 +237,8 @@ Resulting Attributes: Mixing in non-default attributes -------------------------------- +XML Example: + .. code-block:: XML @@ -249,6 +263,8 @@ Mixing in non-default attributes +YAML Example: + .. code-block:: yaml 1 mapping: diff --git a/doc/appendix/intro.rst b/doc/appendix/intro.rst index c9f03a7..e67d58f 100644 --- a/doc/appendix/intro.rst +++ b/doc/appendix/intro.rst @@ -131,6 +131,8 @@ 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 @@ -184,6 +186,8 @@ for writing such polices. +YAML Example: + .. code-block:: yaml 1 mapping: diff --git a/doc/appendix/map.rst b/doc/appendix/map.rst index 6d21bb1..16a1382 100644 --- a/doc/appendix/map.rst +++ b/doc/appendix/map.rst @@ -310,6 +310,8 @@ assertion: You can turn this table into an attribute mapping policy, as shown in the following example: +XML Example: + .. code-block:: XML @@ -334,6 +336,7 @@ following example: +YAML Example: .. code-block:: yaml @@ -434,6 +437,8 @@ 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 @@ -459,6 +464,7 @@ produce the exact same result. +YAML Example: .. code-block:: yaml @@ -497,6 +503,8 @@ 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 @@ -523,6 +531,8 @@ the following example: +YAML Example: + .. code-block:: yaml 1 mapping: @@ -554,6 +564,8 @@ 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 @@ -578,6 +590,8 @@ policy like the following example: +YAML Example: + .. code-block:: yaml 1 mapping: @@ -609,6 +623,8 @@ 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 @@ -633,6 +649,8 @@ Given these substitutions, you can rewrite the policy as follows: +YAML Example: + .. code-block:: yaml 1 mapping: @@ -672,6 +690,8 @@ 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 @@ -695,6 +715,8 @@ example has all of the values in the default places: +YAML Example: + .. code-block:: yaml 1 mapping: diff --git a/doc/config-3p-saml/config-adfs/adfs-attribmapping.rst b/doc/config-3p-saml/config-adfs/adfs-attribmapping.rst index 4b26d32..7034bce 100644 --- a/doc/config-3p-saml/config-adfs/adfs-attribmapping.rst +++ b/doc/config-3p-saml/config-adfs/adfs-attribmapping.rst @@ -55,6 +55,7 @@ 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 @@ -90,6 +91,8 @@ perform the following tasks: +YAML Example: + .. code-block:: yaml mapping: diff --git a/doc/config-3p-saml/config-okta/okta-attribmapping.rst b/doc/config-3p-saml/config-okta/okta-attribmapping.rst index 884f4d6..cef5839 100644 --- a/doc/config-3p-saml/config-okta/okta-attribmapping.rst +++ b/doc/config-3p-saml/config-okta/okta-attribmapping.rst @@ -96,6 +96,7 @@ Notes: *path* (``"{Pt}"``) syntax in the |amp| language to point to the ``NameID`` attribute in the SAML assertion. +XML Example: .. code-block:: XML @@ -130,6 +131,8 @@ Notes: +YAML Example: + .. code-block:: yaml mapping: diff --git a/doc/config-attribute-mapping/faws-mapping.rst b/doc/config-attribute-mapping/faws-mapping.rst index 5d0f8be..8cc0ced 100644 --- a/doc/config-attribute-mapping/faws-mapping.rst +++ b/doc/config-attribute-mapping/faws-mapping.rst @@ -14,6 +14,8 @@ 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 @@ -36,6 +38,8 @@ following mapping policy assigns the ``admin`` role to all federated users: +YAML Example: + .. code:: yaml mapping: @@ -56,6 +60,8 @@ 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 @@ -85,6 +91,8 @@ role to users who belong to the ``mycompany.global.observer`` group: +YAML Example: + .. code:: yaml mapping: @@ -113,6 +121,8 @@ 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 @@ -145,6 +155,8 @@ to members of the ``mycompany.scoped.admin`` group on multiple +YAML Example: + .. code:: yaml mapping: @@ -180,6 +192,8 @@ 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 @@ -213,6 +227,8 @@ matches, so the policy doesn't evaluate the second ``if`` condition. +YAML Example: + .. code:: yaml mapping: @@ -250,6 +266,8 @@ 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 @@ -279,6 +297,8 @@ users the "ViewOnlyAccess" IAM policy for all AWS accounts. It also assigns the +YAML Example: + .. code:: yaml mapping: @@ -308,6 +328,8 @@ 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 @@ -346,6 +368,8 @@ policy assigns permissions as follows: +YAML Example: + .. code:: yaml mapping: @@ -401,6 +425,8 @@ 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 @@ -432,6 +458,8 @@ create new AWS accounts: +YAML Example: + .. code:: yaml mapping: @@ -459,6 +487,8 @@ 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 @@ -532,6 +562,8 @@ AWS Console and API permissions into a single mapping policy: +YAML Example: + .. code:: yaml --- diff --git a/doc/config-attribute-mapping/required-mapping.rst b/doc/config-attribute-mapping/required-mapping.rst index 16ad6eb..80fd765 100644 --- a/doc/config-attribute-mapping/required-mapping.rst +++ b/doc/config-attribute-mapping/required-mapping.rst @@ -122,6 +122,8 @@ SAML providers, see :ref:`index-configuring-3p-saml-ug`. |ampref| +XML Example: + .. code-block:: XML @@ -144,6 +146,8 @@ SAML providers, see :ref:`index-configuring-3p-saml-ug`. +YAML Example: + .. code-block:: yaml mapping: diff --git a/doc/config-attribute-mapping/rscloud-mapping.rst b/doc/config-attribute-mapping/rscloud-mapping.rst index 9bdf7e2..f82e47b 100644 --- a/doc/config-attribute-mapping/rscloud-mapping.rst +++ b/doc/config-attribute-mapping/rscloud-mapping.rst @@ -14,27 +14,31 @@ 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 @@ -79,36 +83,40 @@ 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 @@ -149,6 +157,8 @@ Permissions by groups example - Dedicated Hosting The following code shows a complex example of an |amp| for Dedicated Hosting: +XML Example: + .. code:: XML @@ -180,6 +190,8 @@ Hosting: +YAML Example: + .. code:: yaml mapping: diff --git a/doc/gettingstarted/config-am-policy.rst b/doc/gettingstarted/config-am-policy.rst index ecb2a3d..03bde9f 100644 --- a/doc/gettingstarted/config-am-policy.rst +++ b/doc/gettingstarted/config-am-policy.rst @@ -13,27 +13,31 @@ shown in the following example. **Default Attribute Mapping Policy** +XML Example: + .. code-block:: XML - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + +YAML Example: .. code-block:: yaml From 12c5721393ccfcb9073efba38752917f8ef2ac57 Mon Sep 17 00:00:00 2001 From: anuritjain Date: Tue, 4 Aug 2020 15:53:29 +0530 Subject: [PATCH 5/7] fixed changes --- doc/appendix/intro.rst | 53 +++++++++++++++++++++++---------------- doc/appendix/map.rst | 4 +-- doc/manage-idps/index.rst | 2 +- 3 files changed, 35 insertions(+), 24 deletions(-) diff --git a/doc/appendix/intro.rst b/doc/appendix/intro.rst index e67d58f..b49ee4e 100644 --- a/doc/appendix/intro.rst +++ b/doc/appendix/intro.rst @@ -23,6 +23,16 @@ a basic understanding of the following technologies: information from structured data and is designed to be embedded in a host language. +- **YAML 1.1**: YAML is a simple data serialization language that is designed + 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? ========================== @@ -147,42 +157,43 @@ XML Example: - + - (: + + (: 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 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 + ( + '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 - () + () + diff --git a/doc/appendix/map.rst b/doc/appendix/map.rst index 16a1382..066d4c9 100644 --- a/doc/appendix/map.rst +++ b/doc/appendix/map.rst @@ -359,7 +359,7 @@ examines how the code uses XPath to extract the attribute values. Parts of the mapping policy ~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The mapping policy is a **XML** 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. @@ -707,7 +707,7 @@ XML Example: - + diff --git a/doc/manage-idps/index.rst b/doc/manage-idps/index.rst index a3566f1..0b015dd 100644 --- a/doc/manage-idps/index.rst +++ b/doc/manage-idps/index.rst @@ -62,5 +62,5 @@ Update the |amp| 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 XML or YAML, and the file extensions should be ``.xml`` or ``.yaml``. To validate your XML or YAML, you can use any XML or 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. From d333393e2c2cf67d49c850998fc79e838f2f9204 Mon Sep 17 00:00:00 2001 From: anuritjain Date: Wed, 5 Aug 2020 17:52:16 +0530 Subject: [PATCH 6/7] indentation fixed --- doc/appendix/examples.rst | 40 +++++++++++++++++++-------------------- doc/appendix/intro.rst | 17 +++++++++-------- doc/appendix/map.rst | 23 +++++++++++----------- 3 files changed, 41 insertions(+), 39 deletions(-) diff --git a/doc/appendix/examples.rst b/doc/appendix/examples.rst index 1bccea6..fc9dc62 100644 --- a/doc/appendix/examples.rst +++ b/doc/appendix/examples.rst @@ -189,17 +189,17 @@ XML Example: xmlns="http://docs.rackspace.com/identity/api/ext/MappingRules" version="RAX-1"> - - - - - - - - - - - + + + + + + + + + + + @@ -249,15 +249,15 @@ XML Example: version="RAX-1"> - - - - - - - - - + + + + + + + + + diff --git a/doc/appendix/intro.rst b/doc/appendix/intro.rst index b49ee4e..aa3406e 100644 --- a/doc/appendix/intro.rst +++ b/doc/appendix/intro.rst @@ -152,14 +152,15 @@ XML Example: version="RAX-1"> The following is an attribute mapping for Widgets.com. - - - - - - - - + + + + + + + + + diff --git a/doc/appendix/map.rst b/doc/appendix/map.rst index 066d4c9..05e8665 100644 --- a/doc/appendix/map.rst +++ b/doc/appendix/map.rst @@ -694,23 +694,24 @@ XML Example: .. code-block:: XML - + - The default policy. All attributes are in the expected location in the SAML assertion. + The default policy. All attributes are in the expected location in + the SAML assertion. - - - - - - - - - + + + + + + + + + From 3ea1809db8291d1c2e9bf4c82570fe5b4f2cc3b2 Mon Sep 17 00:00:00 2001 From: anuritjain Date: Fri, 7 Aug 2020 12:56:58 +0530 Subject: [PATCH 7/7] fixed indents in examples --- doc/appendix/examples.rst | 36 ++-- doc/appendix/intro.rst | 20 +- doc/appendix/map.rst | 98 +++++----- .../config-adfs/adfs-attribmapping.rst | 28 +-- .../config-okta/okta-attribmapping.rst | 24 +-- doc/config-attribute-mapping/faws-mapping.rst | 184 +++++++++--------- .../required-mapping.rst | 16 +- .../rscloud-mapping.rst | 44 ++--- doc/gettingstarted/config-am-policy.rst | 18 +- 9 files changed, 235 insertions(+), 233 deletions(-) diff --git a/doc/appendix/examples.rst b/doc/appendix/examples.rst index fc9dc62..7dca05c 100644 --- a/doc/appendix/examples.rst +++ b/doc/appendix/examples.rst @@ -75,15 +75,15 @@ XML Example: version="RAX-1"> - - - - - - - - - + + + + + + + + + @@ -132,15 +132,15 @@ XML Example: version="RAX-1"> - - - - - - - - - + + + + + + + + + diff --git a/doc/appendix/intro.rst b/doc/appendix/intro.rst index aa3406e..5497d20 100644 --- a/doc/appendix/intro.rst +++ b/doc/appendix/intro.rst @@ -152,15 +152,17 @@ XML Example: version="RAX-1"> The following is an attribute mapping for Widgets.com. - - - - - - - - - + + + + + + + + + + + diff --git a/doc/appendix/map.rst b/doc/appendix/map.rst index 05e8665..9b8535c 100644 --- a/doc/appendix/map.rst +++ b/doc/appendix/map.rst @@ -322,16 +322,16 @@ XML Example: Simple policy where we select required attributes via an XPath. - - - - - - - - - + + + + + + + + + @@ -450,16 +450,16 @@ XML Example: Simple policy where we select required attributes via an XPath. - - - - - - - - - + + + + + + + + + @@ -517,16 +517,16 @@ XML Example: avoid having to select the first attribute value in XPath. - - - - - - - - - + + + + + + + + + @@ -574,18 +574,18 @@ XML Example: xmlns="http://docs.rackspace.com/identity/api/ext/MappingRules" version="RAX-1"> Simple policy where we select required attributes via an - XPath. Here we use the mapping:get-attributes call to return attribute values. + XPath. Here we use the mapping:get-attributes call to return attribute values. - - - - - - - - - + + + + + + + + + @@ -636,15 +636,15 @@ XML Example: instead of Pts as a simple means of accessing an name SAML attribute. - - - - - - - - - + + + + + + + + + diff --git a/doc/config-3p-saml/config-adfs/adfs-attribmapping.rst b/doc/config-3p-saml/config-adfs/adfs-attribmapping.rst index 7034bce..fadbcbb 100644 --- a/doc/config-3p-saml/config-adfs/adfs-attribmapping.rst +++ b/doc/config-3p-saml/config-adfs/adfs-attribmapping.rst @@ -66,20 +66,20 @@ XML Example: version="RAX-1"> - - - - - - - - - - - - + + + + + + + + + + + + - - - - - - - - - - - - + + + + + + + + + + + + - - - - - - - - - + + + + + + + + + @@ -71,15 +71,15 @@ XML Example: version="RAX-1"> - - - - - - - - - + + + + + + + + + - - - - - - - - - + + + + + + + + + - - - - - - - - - + + + + + + + + + - - - - - - - - - - - - + + + + + + + + + + + + @@ -339,18 +339,18 @@ XML Example: version="RAX-1"> - - - - - - - - - - - - + + + + + + + + + + + + - - - - - - - - - - - + + + + + + + + + + + - + @@ -506,7 +506,7 @@ XML Example: - + - - - + + + + + - - - + + + + + - - - + + + + + - - - - - - - - + + + + + + + + diff --git a/doc/config-attribute-mapping/rscloud-mapping.rst b/doc/config-attribute-mapping/rscloud-mapping.rst index f82e47b..6ad08dd 100644 --- a/doc/config-attribute-mapping/rscloud-mapping.rst +++ b/doc/config-attribute-mapping/rscloud-mapping.rst @@ -25,15 +25,15 @@ XML Example: version="RAX-1"> - - - - - - - - - + + + + + + + + + @@ -94,15 +94,15 @@ XML Example: version="RAX-1"> - - - - - - - - - + + + + + + + + + - - + + - - + + - - - - - - - - - + + + + + + + + +