Apollo-1116- updated docs with XML examples by anuritjain · Pull Request #68 · rackerlabs/docs-rackspace-federation

anuritjain · 2020-07-30T16:04:13Z

Add XML mapping policies to federation docs

Apollo Dev Sign-off
Doc Teams Sign-off

rackernexus · 2020-07-30T16:11:16Z

Build 142 was successful. Staging content Preview!. valid for 14 days

nicko-winner · 2020-07-30T20:08:54Z

+            <attribute path="(\n  if (mapping:get-attributes('groups')='rackspace-billing')\n  then    'billing:admin' else ()\n)\n"
+                       multiValue="true"/>


Can you replace the \n characters with actual new lines?
The goal of this comment, is to format the path attribute in a way that is is most readable to customers:

Suggested change

<attribute path="(\n if (mapping:get-attributes('groups')='rackspace-billing')\n then 'billing:admin' else ()\n)\n"

multiValue="true"/>

<attribute

path="(

if (mapping:get-attributes('groups')='rackspace-billing')

then 'billing:admin' else ()

)"

multiValue="true"

/>

Before making this change across all the examples I would make sure it validates first, but I think it will make the examples easier to read the conditional logic in attributes is allowed to span multiple lines.

nicko-winner · 2020-07-30T20:10:28Z

       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


Suggested change

- 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

rackernexus · 2020-07-31T10:42:47Z

Build 143 was successful. Staging content Preview!. valid for 14 days

rackernexus · 2020-07-31T13:08:55Z

Build 144 was successful. Staging content Preview!. valid for 14 days

nicko-winner · 2020-07-30T20:14:08Z


-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


Suggested change

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 ``.yml`` . To validate your document, you can use any XML or YAML validation library or

nicko-winner · 2020-07-31T14:21:52Z

+          <user>
+            <domain value="{D}"/>
+            <name value="{D}"/>
+            <email value="{At(FirstName)} {At(LastName)} &lt;{D(name)}@{D(domain)}.rackspace.com&gt;"/>


Verify that < and > are the appropriate character to use here, check the federation test case examples and see if they encode these characters <> in the same way. (I know this kind of encoding is needed for <> character being used inside of a tag, not sure if its needed inside an attribute)

ok checked this test case - looks like attribute values <> need encoding: https://github.com/rackerlabs/attributeMapping/blob/master/core/src/test/resources/tests/mapping-tests/defaults4/maps/defaults4.xml

nicko-winner · 2020-07-31T14:24:16Z

+               <domain value="{D}"/>
+               <name value="{D}"/>
+               <email value="{D}"/>
+               <roles value="{D}" multiValue="true"/>


there is no multiValue="true" in the YAML example, is this needed if you are using a default value here {d}?

when i converted Yaml to XML using CLI tool, it is giving me same output, i.e, with multivalue="true", so kept it as it is..

the other examples do not seem to be using multiValue="true" when using a default value on roles, we should probably be consistent here.

https://github.com/rackerlabs/docs-rackspace-federation/pull/68/files#diff-e684b4a76886438d5d307093da10b392R198

I will check the test cases, but i'm not sure multiValue="true" is getting converted consistently, or as simply as it could be.

rackernexus · 2020-07-31T14:44:30Z

Build 145 was successful. Staging content Preview!. valid for 14 days

prathibha-emany · 2020-08-03T16:05:14Z

+          xmlns="http://docs.rackspace.com/identity/api/ext/MappingRules"
+          version="RAX-1">
+    <rules>
+      <rule>


Is there a reason for tag in all these XML examples? This is not in YAML

Good question. I wonder if @nikhil09541 , or Tim Cline may have more context as to why it is needed as this tag seems to be an identity requirement and is used in the test cases repo.

here is an examples with multiple <rule> tags. https://github.com/rackerlabs/attributeMapping/blob/1aa04de04e01fc6ff916f1b00fa2cead24305390/core/src/test/resources/tests/mapping-tests/mapping-rule-ext-attribute2/maps/mapping-rule-ext-attribute2.xml

prathibha-emany · 2020-08-03T16:08:03Z

- **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.


YAML 1.1 section should be intact as we will be supporting both YAML and XML. May be we should update this section to call out XML as well. Thoughts?

restored YAML 1.1 section and added XML 1.0 section below it.

prathibha-emany · 2020-08-03T16:10:06Z

+        <domain value="{D}"/>
+        <name value="{D}"/>
+        <email value="{At(email)}"/>
+        <roles value="{D}"/>


<roles value="{0}" in the YAML example. In this XML example it is noted as {D}, Can you please check this ? https://developer.rackspace.com/docs/rackspace-federation/appendix/intro/#mapping-policy-for-widget-com

prathibha-emany · 2020-08-03T16:12:13Z

+               <name value="{Pts(/saml2p:Response/saml2:Assertion/saml2:Subject/saml2:NameID)}"/>
+               <email value="{Pts(/saml2p:Response/saml2:Assertion/saml2:AttributeStatement/saml2:Attribute[@Name='email']/saml2:AttributeValue[1])}"/>
+               <roles value="{Pts(/saml2p:Response/saml2:Assertion/saml2:AttributeStatement/saml2:Attribute[@Name='roles']/saml2:AttributeValue)}"
+                        multiValue="true"/>


I see in many instances , roles Value tag is ending with multiValue=true which is not in YAML samples. Can we look into why it is appearing?

for this, I have checked & converted all the examples again and found that in most of the examples, multiValue="true" is adding automatically in <roles value tag.

I found a good multi value example here: https://github.com/rackerlabs/attributeMapping/blob/1aa04de04e01fc6ff916f1b00fa2cead24305390/core/src/test/resources/tests/mapping-tests/adfs-faws-ext1/maps/adfs-single-rule.xml

It seems like if you are not trying to map multiple attributes to a single field than you do not need multiValue="true"

prathibha-emany · 2020-08-03T16:13:05Z

 Parts of the mapping policy
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~

-The mapping policy is a **YAML** document that contains instructions to


We should probably keep both YAML and XML references until we completely deprecate YAML

prathibha-emany · 2020-08-03T16:19:44Z

+            </user>
+         </local>
+            <remote>
+               <attribute 


what is this <attribute tag that is not in YAML, was it just added during conversion as <attribute path ?

when we convert Yaml to XML, this tag is added under <remote tag, as path is an attribute of remote.

prathibha-emany · 2020-08-03T16:22:24Z

+                <roles value="{0}" multiValue="true"/>
+                <expire value="PT4H"/>
+              </user>
+              <faws xsi:type="LocalAttributeGroup">


What is this "LocalAttributeGroup"? Unable to locate this in YAML

There is the best example I could find that offered some context on this:

ref: https://github.com/rackerlabs/attributeMapping/blob/1aa04de04e01fc6ff916f1b00fa2cead24305390/core/src/test/resources/tests/mapping-tests/mapping-rule-ext-attribute/maps/mapping-rule-ext-attribute.xml#L28-L37

From what I am seeing in the identity tests repo, if there is a <faws tag it will also have LocalAttributeGroup, looks like a requirement of the schema

prathibha-emany · 2020-08-03T16:23:46Z

+                <roles value="{0}" multiValue="true"/>
+                <expire value="PT4H"/>
+              </user>
+              <faws xsi:type="LocalAttributeGroup">


What is this "LocalAttributeGroup" value? Unable to locate this in YAML examples

seems that for faws and aws tags, this xsi:type namespace is used in some examples.

nicko-winner · 2020-08-03T19:15:34Z

+              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


would it be possible to match the indentation approach used in the YAML file? Seems like the 'if' statements should be inside of the forloop, adding indentation would make it more apparent. I can't say i'm very familiar with the style characteristics of this language, but if we can use the YAML file as a reference. Might be worth referring to the YAML docs for how to deal with spacing here.

fixed indentation as per YAML example.

rackernexus · 2020-08-04T10:31:36Z

Build 146 was successful. Staging content Preview!. valid for 14 days

catlook

LGTM

nicko-winner · 2020-08-04T19:29:00Z

+            xmlns="http://docs.rackspace.com/identity/api/ext/MappingRules"
+            version="RAX-1">
+      <rules>
+      <rule>


can you indent <rule> here so it looks like its inside `

nicko-winner · 2020-08-04T19:29:43Z

+            version="RAX-1">
+      <rules>
+        <rule>
+        <local>


can you indent <local />

nicko-winner · 2020-08-04T19:31:38Z

+      <description>The default policy. All attributes are in the expected location in the SAML assertion.</description>
+      <rules>
+         <rule>
+         <local>


nicko-winner · 2020-08-06T17:25:14Z

+          version="RAX-1">
+    <description>The following is an attribute mapping for Widgets.com.</description>
+    <rules>
+      <local>


all the other examples have a <rules> tag with a<rule> tag inside it, Is that not a required convention in this case?

for this example, after the conversion, <rule> tag is not added in the code by default, if u want I can add manually now.

Hmm, I would be nice to know in what cases the <rule> attribute is not needed. Maybe @nikhil09541 can provide context here. We can also try to do some testing on the apollodevuser IDP to how identity responds to this format.

nicko-winner · 2020-08-06T17:27:05Z

+            version="RAX-1">
+      <rules>
+         <rule>
+         <local>


indent local

nicko-winner · 2020-08-06T17:27:31Z

+            version="RAX-1">
+      <rules>
+         <rule>
+         <local>


indent local

nicko-winner · 2020-08-06T17:27:45Z

+            version="RAX-1">
+      <rules>
+         <rule>
+         <local>


indent local, can you check the other examples and make sure they are all indented correctly? there are at least a few others that could use indentation.

I have added indentation to all examples at <local> tag and looks fine now. please check once.

rackernexus · 2020-08-07T07:31:51Z

Build 148 was successful. Staging content Preview!. valid for 14 days

nikhil09541 · 2020-08-08T06:23:36Z

+                  <domain value="636462353"/>
+                  <name value="{D}"/>
+                  <email value="{At(http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress)}"/>
+                  <roles value="nova:observer lbaas:admin" multiValue="true"/>


I have tested the xml provided here , it fails and gives 400 error due to the multiline value="true".
Ideally shouldn't we provide the multiple values to single attribute like this:

<roles multivalue="true"> <role value='admin'/> <role value='billing:admin'/> <role value='ticketing:admin'/> <roles/>

Please cross check with the xsd schema which currently is a blueprint for xml here :
https://github.com/rackerlabs/attributeMapping/blob/master/core/src/main/resources/xsd/mapping.xsd#L93-L107

nikhil09541 · 2020-08-08T06:26:59Z

+
+    <?xml version="1.0" encoding="UTF-8" ?>
+    <mapping xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xmlns:xs="http://www.w3.org/2001/XMLSchema"


The format of the policy fails if we add new line over here . Accepted format includes xml declaration in a single line like :

updated docs with XML examples

237286d

nicko-winner reviewed Jul 30, 2020

View reviewed changes

fixed indentation

e969027

fixed code changes

b20c44a

nicko-winner reviewed Jul 31, 2020

View reviewed changes

added headings to examples

79a3abc

prathibha-emany reviewed Aug 3, 2020

View reviewed changes

nicko-winner reviewed Aug 3, 2020

View reviewed changes

fixed changes

12c5721

catlook approved these changes Aug 4, 2020

View reviewed changes

nicko-winner reviewed Aug 4, 2020

View reviewed changes

indentation fixed

d333393

nicko-winner reviewed Aug 6, 2020

View reviewed changes

fixed indents in examples

3ea1809

nikhil09541 suggested changes Aug 10, 2020

View reviewed changes

		<attribute path="(\n if (mapping:get-attributes('groups')='rackspace-billing')\n then 'billing:admin' else ()\n)\n"
		multiValue="true"/>

	- 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

	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 ``.yml`` . To validate your document, you can use any XML or YAML validation library or

Uh oh!

Conversation

anuritjain commented Jul 30, 2020 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

rackernexus commented Jul 30, 2020

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rackernexus commented Jul 31, 2020

Uh oh!

rackernexus commented Jul 31, 2020

Uh oh!

Choose a reason for hiding this comment

Uh oh!

nicko-winner Jul 31, 2020 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

nicko-winner Jul 31, 2020 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rackernexus commented Jul 31, 2020

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

nicko-winner Aug 4, 2020 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

prathibha-emany Aug 3, 2020 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

anuritjain Aug 4, 2020 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

anuritjain Aug 4, 2020 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

anuritjain commented Jul 30, 2020 •

edited

Loading

nicko-winner Jul 31, 2020 •

edited

Loading

nicko-winner Jul 31, 2020 •

edited

Loading

nicko-winner Aug 4, 2020 •

edited

Loading

prathibha-emany Aug 3, 2020 •

edited

Loading

anuritjain Aug 4, 2020 •

edited

Loading

anuritjain Aug 4, 2020 •

edited

Loading

nicko-winner Aug 6, 2020 •

edited

Loading