From 72d27ee6f051ac960a3759fcd8f9749c40ca95e0 Mon Sep 17 00:00:00 2001 From: Nikhil Sharma Date: Tue, 18 Aug 2020 19:16:37 +0530 Subject: [PATCH 1/2] CID-2585 Federation documentation update - YAML to XML --- doc/appendix/examples.rst | 90 +++++- doc/appendix/intro.rst | 36 ++- doc/appendix/map.rst | 278 +++++++++++++----- doc/common/common-front.rst | 2 +- .../config-adfs/adfs-attribmapping.rst | 38 ++- .../config-okta/okta-attribmapping.rst | 42 ++- doc/config-attribute-mapping/faws-mapping.rst | 274 +++++++++++++++-- doc/config-attribute-mapping/index.rst | 2 +- .../required-mapping.rst | 25 +- doc/gettingstarted/add-idp-cp.rst | 16 +- doc/gettingstarted/config-am-policy.rst | 24 +- doc/manage-idps/index.rst | 8 +- doc/overview/features.rst | 5 +- 13 files changed, 714 insertions(+), 126 deletions(-) diff --git a/doc/appendix/examples.rst b/doc/appendix/examples.rst index 907137c..a2ada94 100644 --- a/doc/appendix/examples.rst +++ b/doc/appendix/examples.rst @@ -64,6 +64,28 @@ Working with defaults Default mapping: +XML Example: + +.. code-block:: xml + + 1 + 2 + 3 + 4 + 5 + 6 + 7 + 8 + 9 + 10 + 11 + 12 + 13 + 14 + 15 + +YAML Example: + .. code-block:: yaml 1 mapping: @@ -95,6 +117,28 @@ Resulting attributes: Accessing default from a different field: ----------------------------------------- +XML Example: + +.. code-block:: xml + + 1 + 2 + 3 + 4 + 5 + 6 + 7 + 8 + 9 + 10 + 11 + 12 + 13 + 14 + 15 + +YAML Example: + .. code-block:: yaml 1 mapping: @@ -125,6 +169,28 @@ Resulting attributes: More complex example with multiple substitutions ------------------------------------------------ +XML Example : + +.. code-block:: xml + + 1 + 2 + 3 + 4 + 5 + 6 + 7 + 8 + 9 + 10 + 11 + 12 + 13 + 14 + 15 + +YAML Example : + .. code-block:: yaml 1 mapping: @@ -155,6 +221,28 @@ Resulting Attributes: Mixing in non-default attributes -------------------------------- +XML Example: + +.. code-block:: xml + + 1 + 2 + 3 + 4 + 5 + 6 + 7 + 8 + 9 + 10 + 11 + 12 + 13 + 14 + 15 + +YAML Example: + .. code-block:: yaml 1 mapping: @@ -182,5 +270,3 @@ Resulting Attributes: +--------+------------------------------------------+ | expire | 2017-11-17T16:19:06.298Z | +--------+------------------------------------------+ - - diff --git a/doc/appendix/intro.rst b/doc/appendix/intro.rst index eb56ab9..764d59e 100644 --- a/doc/appendix/intro.rst +++ b/doc/appendix/intro.rst @@ -28,6 +28,12 @@ a basic understanding of the following technologies: 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,34 @@ 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 + + 1 + 2 The following is an attribute mapping for Widgets.com. + 3 + 4 + 5 + 6 + 7 + 8 + 9 + 10 + 11 + 12 + 13 + 14 + 15 + 16 + 17 + 18 + 19 + + .. code-block:: yaml 1 mapping: @@ -182,5 +216,3 @@ for writing such polices. 43 :) 44 if ($group = 'linux_user') then 'nova:observer' else 45 () - - diff --git a/doc/appendix/map.rst b/doc/appendix/map.rst index cad27ca..c63e973 100644 --- a/doc/appendix/map.rst +++ b/doc/appendix/map.rst @@ -20,7 +20,9 @@ The SAML assertion When an |idp| successfully authenticates a user, it presents Rackspace Identity with a SAML assertion, like the following: -.. code-block:: XML +XML Example: + +.. code-block:: xml 1 2 The assertion describes a view of the user that has successfully -logged in. It has all the information deemed by the |idp| to be relevant to the +logged in. It has all the information deemed by the |idp| to be relevant to the service provider, which is Rackspace Technology. .. note:: For help configuring third-party identity providers (such as Active @@ -127,10 +129,10 @@ service provider, which is Rackspace Technology. Parts of the SAML assertion --------------------------- -This section describes the relevant parts of the preceding -`SAML assertion<#the-SAML-assertion>`_. According to the SAML protocol, a -```` element that begins on line 2 wraps the assertion -itself. The actual assertion (````) begins on line 34. +This section describes the relevant parts of the preceding +'SAML assertion<#the-SAML-assertion>'_. According to the SAML protocol, a +"" element that begins on line 2 wraps the assertion +itself. The actual assertion ("") begins on line 34. - **Issuer (37)**: The issuer is the system that generates the assertion. This is identified as a URI. @@ -139,7 +141,7 @@ itself. The actual assertion (````) begins on line 34. request. The signature verifies that the issuer indeed produces the assertion. -- **Subject (58 - 63)**: The subject identifies the user that the assertion +- **Subject (58 - 63)**: The subject identifies the user that the assertion concerns. - **AuthnStatement (64 - 69)**: The ``AuthnStatement`` has details @@ -149,8 +151,8 @@ itself. The actual assertion (````) begins on line 34. attributes associated with the subject. Each attribute in the list is a name/value pair. The values are of a type identified by the ``xsi:type`` XML attribute. In this case, they're all strings. Attributes can have - multiple values. The groups attribute defined in lines 80 through 84, for - example, contain the three separate values of ``group1``, ``group2``, and + multiple values. The groups attribute defined in lines 80 through 84, for + example, contain the three separate values of ``group1``, ``group2``, and ``group3``. Signing SAML assertions @@ -162,69 +164,70 @@ note that while signing the SAML response is optional, signing the SAML assertion is required. Therefore, the system rejects a message that has a single signature at the SAML response level. -A SAML response can have many assertions. In this case, all assertions must be +A SAML response can have many assertions. In this case, all assertions must be signed, and the same issuer must issue them all. Rackspace Identity -examines only the first assertion for authorization data, but a mapping policy +examines only the first assertion for authorization data, but a mapping policy can overwrite this behavior. Required attributes =================== This section describes the attributes that Rackspace Identity -requires to authenticate a user successfully. The following examples include -line references to the preceding `SAML response example<#the-SAML-assertion>`_. +requires to authenticate a user successfully. The following examples include +line references to the preceding 'SAML response example<#the-SAML-assertion>'_. Domain ------ Rackspace Identity keeps information about users, roles, and other entitlements in a domain. When a user federates into Rackspace, -Rackspace Identity places the user in a single identity domain. The user accesses -each domain by using a unique alphanumeric ID, which Rackspace sets to be the -same as the user's account ID. The domain ID is required when a federated user -requests access. This is important because a customer is allowed to create -multiple domains, and Rackspace Identity needs to place the federated user in -the correct one. - -In the preceding `SAML assertion<#the-SAML-assertion>`_, the domain is passed as -a SAML attribute in lines 74 through 76. This implies that the identity provider -is preconfigured to emit the correct value. It's not required that the |idp| do -this, because most federated users target a single domain, and you can hard code -the domain value in an attribute mapping policy. +Rackspace Identity places the user in a single identity domain. The user +accesses each domain by using a unique alphanumeric ID, which Rackspace sets to +be the same as the user's account ID. The domain ID is required when a +federated user requests access. This is important because a customer is allowed +to create multiple domains, and Rackspace Identity needs to place the federated +user in the correct one. + +In the preceding 'SAML assertion<#the-SAML-assertion>'_, the domain is passed +as a SAML attribute in lines 74 through 76. This implies that the identity +provider is preconfigured to emit the correct value. It's not required that +the |idp| do this, because most federated users target a single domain, and +you can hard code the domain value in an attribute mapping policy. Name ---- The **Name** value is the username of the federated user. Rackspace Identity -assumes that each user has a unique username, and that the same user has the +assumes that each user has a unique username, and that the same user has the same username from one federated login to the next. -In the preceding `SAML assertion<#the-SAML-assertion>`_, the ``NameID`` in the ``Subject`` -section of the assertion on line 59 identifies the username is. However, an |idp|can return -a stable username as an attribute in the ``AttributeStatement`` section. +In the preceding 'SAML assertion<#the-SAML-assertion>'_, the "NameID" in the +"Subject" section of the assertion on line 59 identifies the username is. +However, an |idp| can return a stable username as an attribute in the +"AttributeStatement" section. Email ----- -The **Email** value is the email of the federated user. It's an attribute in the -``AttributeStatement`` section on lines 77 through 79 of the preceding -`SAML assertion<#the-SAML-assertion>`_. Some identity providers make no -distinction between a username and an email, in which case the email is in the -``Subject`` section. +The **Email** value is the email of the federated user. It's an attribute in +the "AttributeStatement" section on lines 77 through 79 of the preceding +'SAML assertion<#the-SAML-assertion>'_. Some identity providers make no +distinction between a username and an email, in which case the email is in the +"Subject" section. Roles ----- Rackspace Identity expects an attribute with the list of roles to -assign to the federated user. Rackspace Identity only allows the assignment of +assign to the federated user. Rackspace Identity only allows the assignment of roles that it recognizes. -In the example `SAML assertion<#the-SAML-assertion>`_, the list of roles -is an attribute named ``roles`` on lines 71 through 73. Note that this is a +In the example 'SAML assertion<#the-SAML-assertion>'_, the list of roles +is an attribute named "roles" on lines 71 through 73. Note that this is a good use case for a multivalue attribute, but in this case, -you assign only the ``nova:admin`` role. +you assign only the "nova:admin" role. -The example assigns ``nova:admin`` at the domain level. This +The example assigns ``nova:admin`` at the domain level. This means that the user has the role on all accounts or tenants associated with the domain. For example, if you associate accounts ``12873`` and ``33987`` with the domain, the user has the ``nova:admin`` role on both of those @@ -241,38 +244,38 @@ Expire ------ Rackspace Identity must know the amount of time a federated user can remain on -Rackspace systems before the system should be force the user to authenticate again. You -can use either of the following formats to specify this attribute: +Rackspace systems before the system should be force the user to authenticate +again. You can use either of the following formats to specify this attribute: - You can use an `ISO 8601`_ timestamp, which should include a time zone - designator. For example, the timestamp ``2017-10-04T16:20:57Z`` signifies + designator. For example, the timestamp ``2017-10-04T16:20:57Z`` signifies that the user must authenticate after October 4th, 2017, at 16:20:57 Universal Time Coordinated (UTC). -- You can use an `ISO 8601`_ duration. For example, ``PT1H2M`` signifies that - the user must authenticate one hour and two minutes after +- You can use an `ISO 8601`_ duration. For example, ``PT1H2M`` signifies that + the user must authenticate one hour and two minutes after logging in. -The `SAML assertion example<#the-SAML-assertion>`_ specifies an expire timestamp -in the ``NotOnOrAfter`` attribute of the ``SubjectConfirmationData`` +The 'SAML assertion example<#the-SAML-assertion>'_ specifies an expire +timestamp in the "NotOnOrAfter" attribute of the "SubjectConfirmationData" on line 61. In SAML, this attribute denotes the time after which the SAML assertion is no longer considered valid. While this -timestamp doesn't fit semantically with the ``expire`` attribute that +timestamp doesn't fit semantically with the "expire" attribute that Rackspace Identity expects, it still works as a default. Other attributes ---------------- -Rackspace Identity expects the attributes of ``domain``, ``name``,``email``, -``roles``, and ``expire`` in every federated login. Some Rackspace products -might expect other optional attributes. Consult this document for details on +Rackspace Identity expects the attributes of ``domain``, ``name``,``email``, +``roles``, and ``expire`` in every federated login. Some Rackspace products +might expect other optional attributes. Consult this document for details on these attributes. Mapping attributes ================== You can find the SAML assertion attributes on the following lines of the -`SAML assertion example<#the-SAML-assertion>`_: +'SAML assertion example<#the-SAML-assertion>'_: .. include:: tables/loc.rst @@ -292,11 +295,11 @@ The following table gives the values at those locations: This table represents an attribute mapping. It maps data located in the SAML assertion into attributes that -Rackspace Identity requires to log in a federated user. However, mapping -attributes by referring to line numbers is impractical, inexact, and brittle. -Using XPath is a more stable and practical way of pinpointing the exact location -of the data that you need. XPath is designed specifically to pinpoint and -extract data from XML documents [#j1]_. +Rackspace Identity requires to log in a federated user. However, mapping +attributes by referring to line numbers is impractical, inexact, and brittle. +Using XPath is a more stable and practical way of pinpointing the exact +location of the data that you need. XPath is designed specifically to pinpoint +and extract data from XML documents [#j1]_. Mapping attributes with XPath ----------------------------- @@ -310,6 +313,30 @@ assertion: You can turn this table into an attribute mapping policy, as shown in the following example: +XML Example: + +.. code-block:: xml + + 1 + 2 The default policy. All attributes are in the expected + 3 location in the SAML assertion. + 4 + 5 + 6 + 7 + 8 + 9 + 10 + 11 + 12 + 13 + 14 + 15 + 16 + 17 + +YAML Example: + .. code-block:: yaml 1 mapping: @@ -331,9 +358,9 @@ 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 -retrieve identity attributes from a SAML assertion. -It is a simple script that executes every time a SAML assertion is presented to +The mapping policy is a **XML** or **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. - **mapping (1)**: A single top-level ``mapping`` object always contains @@ -364,7 +391,7 @@ Rackspace Identity. local user. The remote section has statements about the user, which is a remote user, as the |idp| presents it. - Lines 7 through 12 describe the attributes of the local user. Here, + Lines 7 through 12 describe the attributes of the local user. Here, you specify each of the required identity attributes and describe how you can obtain them from an XPath. @@ -380,8 +407,8 @@ This is an XPath substitution. Various types of substitutions are in the mapping policy language, each of which is in curly braces ``{}``. Substitutions are only allowed in the local part of the mapping policy. They help set values for local attributes because they -are always replaced or substituted by other content. For XPath substitution, -the result of the XPath within the parenthesis, when executed against the SAML +are always replaced or substituted by other content. For XPath substitution, +the result of the XPath within the parenthesis, when executed against the SAML assertion, replaces the value. .. note:: @@ -409,6 +436,29 @@ 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 + + 1 + 2 Simple policy where we select required attributes via an XPath. + 3 + 4 + 5 + 6 + 7 + 8 + 9 + 10 + 11 + 12 + 13 + 14 + 15 + 16 + +YAML Example: + .. code-block:: yaml 1 mapping: @@ -432,7 +482,7 @@ Using the {Pt()} substitution Notice that the XPath for retrieving the domain ends with ``saml2:AttributeValue[1]``, while the XPath for retrieving the list of roles ends with ``saml2:AttributeValue``. This structure is because -you want a single value for a domain, but you want a list of roles. Without the +you want a single value for a domain, but you want a list of roles. Without the ``[1]`` at the end, the XPath returns every ``AttributeValue`` in a SAML assertion for a domain. The ``[1]`` signifies that you are only interested in the first value [#j2]_. @@ -443,9 +493,32 @@ first value of an XPath result. This alternative is useful in cases where you expect a single value, and you want to automatically protect against the off chance that the operation might return multiple values in a SAML assertion. -Given this new substitution, you can rewrite the mapping policy like +Given this new substitution, you can rewrite the mapping policy like the following example: +XML Example: + +.. code-block:: xml + + 1 + 2 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. + 3 + 4 + 5 + 6 + 7 + 8 + 9 + 10 + 11 + 12 + 13 + 14 + 15 + 16 + +YAML Example: + .. code-block:: yaml 1 mapping: @@ -474,9 +547,32 @@ common case, a predefined XPath function exists that is called ``mapping:get-attributes``. This function takes the name of a SAML attribute as a string and returns the attribute values associated with that name. -By using the ``mapping:get-attributes`` function, you could rewrite the mapping +By using the ``mapping:get-attributes`` function, you could rewrite the mapping policy like the following example: +XML Example: + +.. code-block:: xml + + 1 + 2 Simple policy where we select required attributes via an XPath. Here we use the mapping:get-attributes call to return attribute values + 3 + 4 + 5 + 6 + 7 + 8 + 9 + 10 + 11 + 12 + 13 + 14 + 15 + 16 + +YAML Example: + .. code-block:: yaml 1 mapping: @@ -508,6 +604,29 @@ 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 + + 1 + 2 Simple policy where we select required attributes. We use At instead of Pts as a simple means of accessing an name SAML attribute. + 3 + 4 + 5 + 6 + 7 + 8 + 9 + 10 + 11 + 12 + 13 + 14 + 15 + 16 + +YAML Example: + .. code-block:: yaml 1 mapping: @@ -544,9 +663,34 @@ name. If you place ``{D}`` in the ``email`` attribute, it is replaced with the default value for email. What are the default locations in a SAML assertion for the five -attributes Rackspace Identity expects? The SAML assertion in the following +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 + + + 1 + 2 The default policy. All attributes are in the expected location in the SAML assertion. + 3 + 4 + 5 + 6 + 7 + 8 + 9 + 10 + 11 + 12 + 13 + 14 + 15 + 16 + + +YAML Example: + .. code-block:: yaml 1 mapping: @@ -566,7 +710,7 @@ example has all of the values in the default places: Next steps ========== -The following section examines writing policies for cases where things don't +The following section examines writing policies for cases where things don't align properly. .. References: 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..f26548d 100644 --- a/doc/config-3p-saml/config-adfs/adfs-attribmapping.rst +++ b/doc/config-3p-saml/config-adfs/adfs-attribmapping.rst @@ -33,11 +33,12 @@ 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 -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 -services by using the ``billing:admin`` Rackspace role. +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 services by using the ``billing:admin`` +Rackspace role. More information ~~~~~~~~~~~~~~~~ @@ -55,6 +56,33 @@ 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 + + 1 + 2 + 3 + 4 + 5 + 6 + 7 + 8 + 9 + 10 + 11 + 12 + 13 + 14 + 15 + 16 + 17 + 18 + 19 + 20 + 21 + +YAML Example: .. code-block:: yaml diff --git a/doc/config-3p-saml/config-okta/okta-attribmapping.rst b/doc/config-3p-saml/config-okta/okta-attribmapping.rst index 7ae6a5b..71da776 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,11 +75,11 @@ section for an attribute policy mapping example ``.yml`` configuration. Attribute policy mapping example -------------------------------- -The following example shows a Rackspace 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 -services by using the ``billing:admin`` Rackspace role. See +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 services by using the ``billing:admin`` Rackspace role. See :ref:`Rackspace Cloud roles` for a full list of all Rackspace roles. @@ -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,32 @@ Notes: *path* (``"{Pt}"``) syntax in the |amp| language to point to the ``NameID`` attribute in the SAML assertion. +XML Example: + +.. code-block:: xml + + 1 + 2 + 3 + 4 + 5 + 6 + 7 + 8 + 9 + 10 + 11 + 12 + 13 + 14 + 15 + 16 + 17 + 18 + 19 + 20 + +YAML Example : .. code-block:: yaml @@ -129,7 +155,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..4f27f96 100644 --- a/doc/config-attribute-mapping/faws-mapping.rst +++ b/doc/config-attribute-mapping/faws-mapping.rst @@ -8,11 +8,34 @@ Fanatical support for AWS permissions ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ These permissions control access to features within Rackspace's Fanatical -Support for the Amazon Web Services (FAWS) Control Panel. You can assign the roles -of ``observer`` or ``admin`` or omit them from the mapping policy. Users with -``observer`` permissions have read-only access to the Control Panel. 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: +Support for the Amazon Web Services (FAWS) Control Panel. You can assign the +roles of ``observer`` or ``admin`` or omit them from the mapping policy. +Users with ``observer`` permissions have read-only access to the Control Panel. +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-block:: xml + + + 1 + 2 + 3 + 4 + 5 + 6 + 7 + 8 + 9 + 10 + 11 + 12 + 13 + 14 + +YAML Example: .. code:: yaml @@ -28,11 +51,36 @@ 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. +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-block:: xml + + 1 + 2 + 3 + 4 + 5 + 6 + 7 + 8 + 9 + 10 + 11 + 12 + 13 + 14 + 15 + 16 + 17 + 18 + +YAML Example: + .. code:: yaml mapping: @@ -54,11 +102,37 @@ 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 +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``: +AWS accounts, and the ``observer`` role to members of ``mycompany.scoped.observer`` +on the single account ``12345678012``: + + XML Example: + +.. code-block:: xml + + 1 + 2 + 3 + 4 + 5 + 6 + 7 + 8 + 9 + 10 + 11 + 12 + 13 + 14 + 15 + 16 + 17 + 18 + +YAML Example: .. code:: yaml @@ -85,16 +159,39 @@ 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``. +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``. -Swapping the ``admin`` and ``observer`` groups in the next example grants +Swapping the ``admin`` and ``observer`` groups in the next example grants 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:: yaml +matches, so the policy doesn't evaluate the second ``if`` condition. + +XML Example: + +.. code-block:: xml + + 1 + 2 + 3 + 4 + 5 + 6 + 7 + 8 + 9 + 10 + 11 + 12 + 13 + 14 + 15 + 16 + 17 + 18 + +.. code-block:: yaml mapping: version: RAX-1 @@ -130,7 +227,31 @@ 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:: yaml +XML Example: + +.. code-block:: xml + + + 1 + 2 + 3 + 4 + 5 + 6 + 7 + 8 + 9 + 10 + 11 + 12 arn:aws:iam::aws:policy/job-function/ViewOnlyAccessarn:aws:iam::aws:policy/AdministratorAccess multiValue="true"/> + 14 + 15 + 16 + 17 + +YAML Example: + +.. code-block:: yaml mapping: version: RAX-1 @@ -158,7 +279,38 @@ policy assigns permissions as follows: * Users in the ``mycompany.12345678012.admin`` group are only assigned the ``AdministratorAccess`` IAM policy for AWS account ``123456789012``. -.. code:: yaml + XML Example: + +.. code-block:: xml + + 1 + 2 + 3 + 4 + 5 + 6 + 7 + 8 + 9 + 10 + 11 + 12 {0} + {1} multiValue="true"/> + + 14 + 15 + 16 + 17 + 18 + 19 + 20 + 21 + + +YAML Example: + +.. code-block:: yaml mapping: version: RAX-1 @@ -189,9 +341,9 @@ policy assigns permissions as follows: 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 -``SecurityAudit`` IAM policy attaches to the user's temporary session for the -AWS account ``123456789012``. +groups, have the``AdministratorAccess`` IAM policy. In this case, the +``SecurityAudit`` IAM policy attaches to the user's temporary session for the +AWS account ``123456789012``. Customer-managed AWS IAM policies that are the same across AWS accounts ----------------------------------------------------------------------- @@ -212,7 +364,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:: yaml +XML Example: + +.. code-block:: xml + + 1 + 2 + 3 + 4 + 5 + 6 + 7 + 8 + 9 + 10 + 11 + 12 {0} + 13 + 14 + + 15 + 16 + 17 + 18 + +YAML Example: + +.. code-block:: yaml mapping: version: RAX-1 @@ -238,7 +417,56 @@ 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:: yaml +XML Example: + +.. code-block:: xml + + 1 + 2 + 3 + 4 + 5 + 6 + 7 + 8 + 9 + 10 + 11 + 13 + 14 + 15 + 16 + 17 + 18 + 19 + 20 {0} + 21 + 22 + + 23 + 24 + 25 + 26 + 27 {0} + 28 + 29 + + 30 + 31 + 32 + 33 + 34 {0} + 35 + 36 + + 37 + 38 + 39 + 40 + +YAML Example: + +.. code-block:: yaml --- mapping: 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..a81c0fd 100644 --- a/doc/config-attribute-mapping/required-mapping.rst +++ b/doc/config-attribute-mapping/required-mapping.rst @@ -122,6 +122,27 @@ SAML providers, see :ref:`index-configuring-3p-saml-ug`. |ampref| +XML Example: + +.. code-block:: xml + + + 1 + 2 + 3 + 4 + 5 + 6 + 7 + 8 + 9 + 10 + 11 + 12 + 13 + 14 + 15 + .. code-block:: yaml mapping: @@ -130,7 +151,7 @@ SAML providers, see :ref:`index-configuring-3p-saml-ug`. rules: - local: user: - domain: "636462353" + domain: "{D}" # Domain must be set to your Identity Domain name: "{D}" # Username is set from the element named "name" value in your SAML @@ -138,7 +159,7 @@ SAML providers, see :ref:`index-configuring-3p-saml-ug`. # Locates the attribute with the above URL as the claim type or name roles: - "nova:observer" - - "lbaas:admin" + - "admin" # Assigns the roles explicitly listed above expire: "{Pt(/saml2p:Response/saml2:Assertion/saml2:Conditions/@NotOnOrAfter[1])}" # Retrieves the NotOnOrAfter value by using the SAML path and XPath diff --git a/doc/gettingstarted/add-idp-cp.rst b/doc/gettingstarted/add-idp-cp.rst index 0327583..c9397cd 100644 --- a/doc/gettingstarted/add-idp-cp.rst +++ b/doc/gettingstarted/add-idp-cp.rst @@ -18,9 +18,9 @@ following table provides descriptions of these parameters: lists and other areas in the Control Panel. * - Email Domains - Provides a valid email domain, such as **mycompany.com**. Users provide - their email address during the federated login process, and the process uses - their email domain to identify and redirect them to the correct |idp| to - complete the login process. + their email address during the federated login process, and the process + uses their email domain to identify and redirect them to the correct + |idp| to complete the login process. Add an |idp| ------------ @@ -38,13 +38,13 @@ Cloud customers use the following steps to add an |idp|: 4. Click **Add Identity Provider**. -5. Provide a short description of the |idp| for organizational purposes. When users - log in by using federation, they see the name provided here. +5. Provide a short description of the |idp| for organizational purposes. When + users log in by using federation, they see the name provided here. -6. Click **Add Domain**, enter the email domain with which users should authenticate, - and click **Add**. +6. Click **Add Domain**, enter the email domain with which users should + authenticate and click **Add**. -7. Within the **SAML Metadata** section, locate and click the **No file chosen** +7. Within the **SAML Metadata** section,locate and click the **No file chosen** button. Choose the metadata file you downloaded from your |idp|. The :ref:`Okta metadata file` shows an example of this file. diff --git a/doc/gettingstarted/config-am-policy.rst b/doc/gettingstarted/config-am-policy.rst index c486407..b416a8c 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 a 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** +XML Example: + +.. code-block:: xml + + 1 + 2 + 3 + 4 + 5 + 6 + 7 + 8 + 9 + 10 + 11 + 12 + 13 + 14 + 15 + +YAML Example: + .. code-block:: yaml mapping: diff --git a/doc/manage-idps/index.rst b/doc/manage-idps/index.rst index 831f3f2..f3fdb15 100644 --- a/doc/manage-idps/index.rst +++ b/doc/manage-idps/index.rst @@ -59,9 +59,9 @@ 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 -website. +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..986a77c 100644 --- a/doc/overview/features.rst +++ b/doc/overview/features.rst @@ -20,5 +20,6 @@ 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 - configure the roles and permissions that users receive when they log in. + - 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 c93d734043268cfbb528a7f28fc66aa1e57d7da6 Mon Sep 17 00:00:00 2001 From: Nikhil Sharma Date: Wed, 19 Aug 2020 17:49:42 +0530 Subject: [PATCH 2/2] CID-2585 Corrected the policy --- .../required-mapping.rst | 41 +++++++++++-------- 1 file changed, 24 insertions(+), 17 deletions(-) diff --git a/doc/config-attribute-mapping/required-mapping.rst b/doc/config-attribute-mapping/required-mapping.rst index a81c0fd..c75942e 100644 --- a/doc/config-attribute-mapping/required-mapping.rst +++ b/doc/config-attribute-mapping/required-mapping.rst @@ -127,21 +127,28 @@ XML Example: .. code-block:: xml - 1 - 2 - 3 - 4 - 5 - 6 - 7 - 8 - 9 - 10 - 11 - 12 - 13 - 14 - 15 + 1 + 2 + 3 + 4 + 5 + 6 + 7 + 8 + 9 + 10 + 11 + 12 + 13 + 14 + 15 + 16 + 17 + 18 + 19 + 20 + 21 + 22 .. code-block:: yaml @@ -158,8 +165,8 @@ XML Example: email: "{At(http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress)}" # Locates the attribute with the above URL as the claim type or name roles: - - "nova:observer" - - "admin" + - "nova:admin" + - "lbaas:observer" # Assigns the roles explicitly listed above expire: "{Pt(/saml2p:Response/saml2:Assertion/saml2:Conditions/@NotOnOrAfter[1])}" # Retrieves the NotOnOrAfter value by using the SAML path and XPath