OpenStack - User contributions [en]

Keystone/VOManagement

2014-06-05T12:13:42Z

Kwss:

<h2>Introduction</h2>
<p>A Virtual Organisation (VO) is a group of people who work together in a similar way to members of a real world organisation. However, in a VO the members may be a collection of users from multiple organisations who are collaborating together. Different users in the VO will typically have different access rights to the VO’s resources, so whilst they are all members of the same VO, they will typically not have the same roles within the VO.</p>
<p>Openstack services have the concept of groups – users can be assigned membership in a group, and a group can be granted OpenStack roles and permissions in a bulk manner. An administrator can assign users to a VO role by assigning group membership to them, and then setting the correct OpenStack roles and permissions for the group.</p>

<h2>VO Role Naming and VO Administration</h2>
<p>Different VOs may have the same VO role names, but these would need to be different groups in OpenStack. How is this to be implemented?</p>
<p>Typically different VOs will have different administrators. We therefore need to distribute the management of VO roles (group names) to different administrators. How is this possible in OpenStack?</p>
<p>One way would be to make each VO a separate Keystone domain, and have the domain name equal to the VO name, then the group name can equal the VO role name (assuming that groups are bounded by domains). Different VO administrators can then create different groups (VO roles) within their own Keystone domains.</p>
<p>If different domains is not desirable, then roles in VOs could be indicated by individual group names formulated as <VOname>.<RoleName>. If group names are not bound to domains, then group names will have to be <VOname>.<RoleName> in order to keep them globally unique. A set of administrators for the (default) domain could be created, and users with both the admin role and <VOname>.<RoleName> could be given administrative rights for that VO role.</p>

<h2>Identifying VO members</h2>

<p>Regardless of the way VO roles are named and managed, in a large cloud deployment with federated authentication enabled the VO administrator might not know the identifier or identity attributes issued for each VO member by their respective IdPs. Because of this we propose that a management utility should be available for administrators to organise the membership of VOs, by inviting VO members to self-register. In this way, neither the administrator nor the VO member need be aware of either the identifier or identity attributes issued to him/her by their IdP. The proposed system will take the name of the IdP and the unique ID assigned to the user by the IdP as the inputs to the mapping function, and will automatically create a mapping rule for this user.</p>

<p> If the VO administrator does know the identity attributes that will characterize his VO members, then he can create the mapping rules using the existing mapping API and none of this new functionality is needed.</p>

<h2>Proposal</h2>

The proposed VO Management utility should consist of five categories of API functions:
<ol>
<li>The administrator should be able to create a new VO role, list existing VO roles, and delete an existing VO role. A VO role is defined as a group name with a PIN number or password associated with it, to be used for user self-registration to the VO role. The administrator can distribute the group name and PIN/pw to proposed members of the VO role, so that they can request membership (i.e. self-register).</li>
<li>The members should be able to request membership of the VO role using the PIN/pw and group name. They should also be able to request leaving any VO role they are a member of at any time (without using the PIN). In addition they should be able to list the VO roles they are a member of and also get a list of fellow members of a VO role.</li>
<li>The administrator should be able to view, accept and deny VO role membership requests.</li>
<ol type="a">
<li>View should list all outstanding membership requests.</li>
<li>Accept should create a mapping rule that assigns the group to the member in question, and remove the request.</li>
<li>Deny should simply delete the request.</li>
</ol>
<li>The administrator should be able to remove VO role members and modify VO role memberships e.g. Change a user from VO.role1 to VO.role2. (Note. This might be available already as an existing Keystone admin operation on groups.) </li>
<li>A user should be marked as blacklisted when he has made three attempts to join a VO role with the incorrect PIN. The administrator should be able to view blacklisted users, for all VO roles or for a single VO role, and delete them to allow them to again attempt to join VO roles.</li></ol>

<h2>New Entities</h2>

<h3>Virtual Organisation Role (VO-role)</h3>
<p>Attributes:</p>
<p>"id" (string) The ID of the VO role</p>
<p>“vo_name" (string) the VO role/group name</p>
<p>“vo_role" (string) the VO role/group role</p>
<p>"description" (string) the description of the VO role
<p>"group_id" (string, FK) The ID of the group which has this role</p>
<p>"enabled" (boolean) Whether the VO role is active</p>
<p>“pin” (string) the secret PIN for group membership</p>
<p>“automatic_join” (boolean) whether users joining with a valid PIN should be joined to the VO role automatically or manually confirmed by an administrator. It should default to false (manual confirm).</p>

<h3>Virtual Organisation Blacklist (VO-blacklist)</h3>
<p>Attributes: </p>
<p>"id" (string) The ID of the blacklist entry</p>
<p>“user_id” (string) The user ID who tried to join </p>
<p>“idp” (string, FK) The IdP which authenticated the user </p>
<p>“group_id” The ID of the VO role/Group the user tried to join</p>
<p>“count” The number of incorrect attempts. (max three)</p>

<h3>Virtual Organisation Request (VO-request)</h3>
Attributes:
<p>"id" (string) The ID of the VO join request</p>
<p>“user_id” (string) The user ID who wishes to join</p>
<p>“idp” (string, FK) The IdP which authenticated the user</p>
<p>“group_id” The ID of the VO role/Group the user requests membership in.</p>

Keystone/trusted-attribute-issuing-policy

2014-05-20T10:23:01Z

Kwss: A Trusted Attribute Issuing Policy for Federated Identity Providers

== Trusted Attribute Issuing Policy for Federated Identity Providers ==

Only certain identity providers should be trusted to issue certain attributes, for example, a University might be able to issue a student number, but not a credit card number. In order to enforce this, we propose an API to allow administrators to set an issuing policy for an Identity Provider which denotes which attributes can be issued. Any attributes which violate the policy will be discarded before any attribute mapping takes place. There should be one policy per Identity Provider.

There are three ways in which an attribute can be treated in the policy.

* The attribute can be omitted from the policy completely - if this attribute is received from this Identity Provider it will be discarded.
* The attribute can be included with an empty list of values - any value of this attribute will be valid so if this attribute is present it will be preserved.
* The attribute can be included with a list of one or more values - any values not specified will be stripped from the received attribute, if no values remain the attribute will be discarded, else the attribute will be preserved with the new list of values after stripping any unspecified values.

Keystone/VOManagement

2014-04-22T20:47:47Z

Kwss:

<h2>Introduction</h2>
<p>A Virtual Organisation (VO) is a group of people who work together in a similar way to members of a real world organisation. However, in a VO the members may be a collection of users from multiple organisations who are collaborating together. Different users in the VO will typically have different access rights to the VO’s resources, so whilst they are all members of the same VO, they will typically not have the same roles within the VO.</p>
<p>Openstack services have the concept of groups – users can be assigned membership in a group, and a group can be granted OpenStack roles and permissions in a bulk manner. An administrator can create a role in a VO by assigning a group to a number of VO users and then setting the correct OpenStack roles and permissions for the group.</p>

<h2>VO Role Naming and VO Administration</h2>

<p>Typically different VOs will have different administrators. We therefore need to distribute the management of VO roles (group names) to different administrators. How is this possible in OpenStack?</p>
<p>One way would be to make each VO a separate Keystone domain, and have the domain name equal to the VO name, then the group name can equal the VO role name. Different VO administrators can then create different groups (VO roles) within their own Keystone domains.</p>
<p>If different domains is not desirable, then roles in VOs could be indicated by individual group names formulated as <VOname>.<RoleName>. A set of administrators for the (default) domain could be created, and users with both the admin role and <VOname>.<RoleName> could be given administrative rights for that VO role.</p>

<h2>Identifying VO members</h2>

<p>Regardless of the way VO roles are named and managed, in a large cloud deployment with federated authentication enabled the VO administrator might not know the identifier or identity attributes issued for each VO member by their respective IdPs. Because of this we propose that a management utility should be available for administrators to organise the membership of VOs, by inviting VO members to self-register. In this way, neither the administrator nor the VO member need be aware of either the identifier or identity attributes issued to him/her by their IdP.</p>

<h2>Proposal</h2>

The proposed VO Management utility should consist of five API functions:
<ol>
<li>The administrator should be able to create a new VO role and delete an existing VO role. A VO role is defined as a group name with a PIN number associated with it. The administrator can distribute the group name and PIN to proposed members of the VO role, so that they can request membership (i.e. self-register).</li>
<li>The members should be able to request membership of the VO role using the PIN and group name. They should also be able to request leaving any VO role they are a member of at any time (without using the PIN).</li>
<li>The administrator should be able to view, accept and deny VO role membership requests.</li>
<ol type="a">
<li>View should list all outstanding membership requests.</li>
<li>Accept should create a mapping rule that assigns the group to the member in question, and remove the request.</li>
<li>Deny should simply delete the request.</li>
</ol>
<li>The administrator should be able to remove VO role members and modify VO role memberships e.g. Change a user from VO.role1 to VO.role2. (Note. This might be available already as an existing Keystone admin operation on groups.) </li>
<li>A user should be marked as blacklisted when he has made three attempts to join a VO role with the incorrect PIN. The administrator should be able to view blacklisted users, and delete them.</li></ol>

<h2>New Entities</h2>

<h3>Virtual Organisation Role (VO-role)</h3>
<p>Attributes:</p>
<p>"id" (string) The ID of the VO role</p>
<p>“vo_name" (string) the VO role/group name</p>
<p>“vo_role" (string) the VO role/group role</p>
<p>"description" (string) the description of the VO role
<p>"group_id" (string, FK) The ID of the group which has this role</p>
<p>"enabled" (boolean) Whether the VO role is active</p>
<p>“pin” (string) the secret PIN for group membership</p>
<p>“automatic_join” (boolean) whether users joining with a valid PIN should be joined to the VO role automatically or manually confirmed by an administrator. It should default to false (manual confirm).</p>

<h3>Virtual Organisation Blacklist (VO-blacklist)</h3>
<p>Attributes: </p>
<p>"id" (string) The ID of the blacklist entry</p>
<p>“user_id” (string) The user ID who tried to join </p>
<p>“idp” (string, FK) The IdP which authenticated the user </p>
<p>“group_id” The ID of the VO role/Group the user tried to join</p>
<p>“count” The number of incorrect attempts. (max three)</p>

<h3>Virtual Organisation Request (VO-request)</h3>
Attributes:
<p>"id" (string) The ID of the VO join request</p>
<p>“user_id” (string) The user ID who wishes to join</p>
<p>“idp” (string, FK) The IdP which authenticated the user</p>
<p>“group_id” The ID of the VO role/Group the user requests membership in.</p>

Keystone/VOManagement

2014-04-15T22:24:50Z

Kwss:

<h2>Introduction</h2>
<p>A Virtual Organisation (VO) is a group of people who work together in a similar way to members of a real world organisation. However, in a VO the members may be a collection of users from multiple organisations who are collaborating together. Different users in the VO will typically have different access rights to the VO’s resources, so whilst they are all members of the same VO, they will typically not have the same roles within the VO.</p>
<p>Openstack services have the concept of groups – users can be assigned membership in a group, and a group can be granted OpenStack roles and permissions in a bulk manner. An administrator can create a role in a VO by assigning a group to a number of VO users and then setting the correct OpenStack roles and permissions for the group.</p>

<h2>VO Role Naming and VO Administration</h2>

<p>Typically different VOs will have different administrators. We therefore need to distribute the management of VO roles (group names) to different administrators. How is this possible in OpenStack?</p>
<p>One way would be to make each VO a separate Keystone domain, and have the domain name equal to the VO name, then the group name can equal the VO role name. Different VO administrators can then create different groups (VO roles) within their own Keystone domains.</p>
<p>If different domains is not desirable, then roles in VOs could be indicated by individual group names formulated as <VOname>.<RoleName>. A set of administrators for the (default) domain could be created, and users with both the admin role and <VOname>.<RoleName> could be given administrative rights for that VO role.</p>

<h2>Identifying VO members</h2>

<p>Regardless of the way VO roles are named and managed, in a large cloud deployment with federated authentication enabled the VO administrator might not know the identifier or identity attributes issued for each VO member by their respective IdPs. Because of this we propose that a management utility should be available for administrators to organise the membership of VOs, by inviting VO members to self-register. In this way, neither the administrator nor the VO member need be aware of either the identifier or identity attributes issued to him/her by their IdP.</p>

<h2>Proposal</h2>

The proposed VO Management utility should consist of five API functions:
<ol>
<li>The administrator should be able to create a new VO role and delete an existing VO role. A VO role is defined as a group name with a PIN number associated with it. The administrator can distribute the group name and PIN to proposed members of the VO role, so that they can request membership (i.e. self-register).</li>
<li>The members should be able to request membership of the VO role using the PIN and group name. They should also be able to request leaving any VO role they are a member of at any time (without using the PIN).</li>
<li>The administrator should be able to view, accept and deny VO role membership requests.</li>
<ol type="a">
<li>View should list all outstanding membership requests.</li>
<li>Accept should create a mapping rule that assigns the group to the member in question, and remove the request.</li>
<li>Deny should simply delete the request.</li>
</ol>
<li>The administrator should be able to remove VO role members and modify VO role memberships e.g. Change a user from VO.role1 to VO.role2. (Note. This might be available already as an existing Keystone admin operation on groups.) </li>
<li>A user should be marked as blacklisted when he has made three attempts to join a VO role with the incorrect PIN. The administrator should be able to view blacklisted users, and delete them.</li></ol>

<h2>New Entities</h2>

<h3>Virtual Organisation Role (VO-role)</h3>
<p>Attributes:</p>
<p>"id" (string) The ID of the VO role</p>
<p>“name" (string) the VO role/group name</p>
<p>"description" (string) the description of the VO role
<p>"group_id" (string, FK) The ID of the group which has this role</p>
<p>"enabled" (boolean) Whether the VO role is active</p>
<p>“PIN” (string) the secret PIN for group membership</p>
<p>“automatic_join” (boolean) whether users joining with a valid PIN should be joined to the VO role automatically or manually confirmed by an administrator. It should default to false (manual confirm).</p>

<h3>Virtual Organisation Blacklist (VO-blacklist)</h3>
<p>Attributes: </p>
<p>"id" (string) The ID of the blacklist entry</p>
<p>“user_id” (string) The user ID who tried to join </p>
<p>“idp” (string, FK) The IdP which authenticated the user </p>
<p>“group_id” The ID of the VO role/Group the user tried to join</p>
<p>“count” The number of incorrect attempts. (max three)</p>

<h3>Virtual Organisation Request (VO-request)</h3>
Attributes:
<p>"id" (string) The ID of the VO join request</p>
<p>“user_id” (string) The user ID who wishes to join</p>
<p>“idp” (string, FK) The IdP which authenticated the user</p>
<p>“group_id” The ID of the VO role/Group the user requests membership in.</p>

Keystone/TempUserProvisioning/Blueprint

2013-05-17T12:57:32Z

Kwss: /* API changes */

=== Temporary User Provisioning in Keystone ===
There are many instances in which it might be beneficial to be able to create temporary user entries in Keystone. For example, guest accounts and fixed term contract employees, support for short term alliances such as Virtual Organisation, or autoprovisioning of federated users. We propose adding an expiry time to user entities, and to support this, a function to delete all expired entries. In order to support backwards compatibility, the system should still allow for users to be created without an expiry time, which then denotes a permanent user that can only be deleted by an administrator.
The current structure of the user entity is:
<pre><nowiki>{
"user": {
"default_project_id": "263fd9",
"domain_id": "1789d1",
"email": "joe@example.com",
"enabled": true,
"id": "0ca8f6",
"links": {
"self": "http://identity:35357/v3/users/0ca8f6"
},
"name": "Joe"
}
}</nowiki></pre>
The proposed new structure of the user entry is:
<pre><nowiki>{
"user": {
"default_project_id": "263fd9",
"domain_id": "1789d1",
"email": "joe@example.com",
"enabled": true,
"id": "0ca8f6",
"links": {
"self": "http://identity:35357/v3/users/0ca8f6"
},
"name": "Joe"
“expiry_time”: “2013-05-27T18:30:59.999999Z”
}
}</nowiki></pre>

==== Handling token expiry ====
When a system can create both temporary and permanent users, because tokens are time limited, then it is important that a token cannot be issued which exceeds the expiry time of the user it is linked to. Therefore in order to support the addition of temporary users, the code that sets token validity should be changed so as to limit it to no later than the user expiry time.
==== API changes ====
The following API changes are needed
#Addition of expiry time as an optional parameter to the call that creates a new user entry
#Addition of a new API call to delete all expired user entries
These will be made to the API documentation

Keystone/TempUserProvisioning/Blueprint

2013-05-17T12:56:59Z

Kwss:

=== Temporary User Provisioning in Keystone ===
There are many instances in which it might be beneficial to be able to create temporary user entries in Keystone. For example, guest accounts and fixed term contract employees, support for short term alliances such as Virtual Organisation, or autoprovisioning of federated users. We propose adding an expiry time to user entities, and to support this, a function to delete all expired entries. In order to support backwards compatibility, the system should still allow for users to be created without an expiry time, which then denotes a permanent user that can only be deleted by an administrator.
The current structure of the user entity is:
<pre><nowiki>{
"user": {
"default_project_id": "263fd9",
"domain_id": "1789d1",
"email": "joe@example.com",
"enabled": true,
"id": "0ca8f6",
"links": {
"self": "http://identity:35357/v3/users/0ca8f6"
},
"name": "Joe"
}
}</nowiki></pre>
The proposed new structure of the user entry is:
<pre><nowiki>{
"user": {
"default_project_id": "263fd9",
"domain_id": "1789d1",
"email": "joe@example.com",
"enabled": true,
"id": "0ca8f6",
"links": {
"self": "http://identity:35357/v3/users/0ca8f6"
},
"name": "Joe"
“expiry_time”: “2013-05-27T18:30:59.999999Z”
}
}</nowiki></pre>

==== Handling token expiry ====
When a system can create both temporary and permanent users, because tokens are time limited, then it is important that a token cannot be issued which exceeds the expiry time of the user it is linked to. Therefore in order to support the addition of temporary users, the code that sets token validity should be changed so as to limit it to no later than the user expiry time.
==== API changes ====
The following API changes are needed
#Addition of expiry time as an optional parameter to the call that creates a new user entry
# Addition of user ID as an optional parameter to the call that creates a new user entry.
#Addition of a new API call to delete all expired user entries
These will be made to the API documentation

Keystone/TempUserProvisioning/Blueprint

2013-05-16T15:26:55Z

Kwss: Created page with "=== Temporary User Provisioning in Keystone === There are many instances in which it might be beneficial to be able to create temporary user entries in Keystone. For example, ..."

=== Temporary User Provisioning in Keystone ===
There are many instances in which it might be beneficial to be able to create temporary user entries in Keystone. For example, guest accounts and fixed term contract employees, support for short term alliances such as Virtual Organisation, or autoprovisioning of federated users. We propose adding an expiry time to user entities, and to support this, a function to delete all expired entries. In order to support backwards compatibility, the system should still allow for users to be created without an expiry time, which then denotes a permanent user that can only be deleted by an administrator.
The current structure of the user entity is:
<pre><nowiki>{
"user": {
"default_project_id": "263fd9",
"domain_id": "1789d1",
"email": "joe@example.com",
"enabled": true,
"id": "0ca8f6",
"links": {
"self": "http://identity:35357/v3/users/0ca8f6"
},
"name": "Joe"
}
}</nowiki></pre>
The proposed new structure of the user entry is:
<pre><nowiki>{
"user": {
"default_project_id": "263fd9",
"domain_id": "1789d1",
"email": "joe@example.com",
"enabled": true,
"id": "0ca8f6",
"links": {
"self": "http://identity:35357/v3/users/0ca8f6"
},
"name": "Joe"
“expiry_time”: “2013-05-27T18:30:59.999999Z”
}
}</nowiki></pre>

==== Handling token expiry ====
When a system can create both temporary and permanent users, because tokens are time limited, then it is important that a token cannot be issued which exceeds the expiry time of the user it is linked to. Therefore in order to support the addition of temporary users, the code that sets token validity should be changed so as to limit it to no later than the user expiry time.
==== Specifying User IDs ====
In order to maintain functionality for temporary users on systems which user User IDs in access control lists we have modified the user creation process to allow a user ID to passed in with the user entity, if this parameter is present, it will be used instead of the standard randomly generated ID.
==== API changes ====
The following API changes are needed
#Addition of expiry time as an optional parameter to the call that creates a new user entry
# Addition of user ID as an optional parameter to the call that creates a new user entry.
#Addition of a new API call to delete all expired user entries
These will be made to the API documentation

Keystone/Federation/TempUserCreation/Blueprint

2013-04-19T11:49:12Z

Kwss: /* 3.2 Assigning Authz Attributes to Users according to Attribute Mappings */

== Temporary User Creation in a Federated Keystone ==
Version 1.2. 11 April 2013
=== 1. Introduction ===
In a standard centrally managed Keystone environment users are managed by an administrator of the Keystone service and are created manually via the Keystone [http://docs.openstack.org/api/openstack-identity-service/2.0/content/Overview-Keystone-API-d1e62.html REST API]. However, in a federated environment, the Keystone Identity service for Openstack Cloud services does not have access to the available users as the external Identity Provider(s) (IdPs) manage them. Therefore, in order to achieve a fully federated Keystone installation it is necessary to implement a mechanism for automatically creating the internal Keystone user entries after external IdPs successfully authenticate the users. After authentication, external IdPs provide Keystone with a set of identity attributes for the user e.g. as a SAML assertion. An [http://blueprints.launchpad.net/keystone/+spec/role-mapping-service-keystone attribute mapping service] allows Keystone to assign the correct privileges to these users (as roles, projects, domains etc. collectively called the authz attributes in this document) according to the identity attributes provided by the external IdP. This document describes the design and workflow of such a mechanism. It is based on creating a temporary user in Keystone, whose lifespan is based on that of the IdP’s identity assertion.
=== 2. Initial Assumptions ===
We assume that user authentication against an external IdP is available, such as that described in the [http://wiki.openstack.org/Keystone/Federation/Blueprint federation blueprint], and that after authentication Keystone is provided with an assertion by the IdP that contains the following information:
* Some sort of unique user name or identifier (UNUNID) that uniquely identifies the subject of the assertion. The type and location of this data in the IdP’s assertion will be federation protocol specific (the type might be configured as extra data in the Service Catalog service endpoint entry of the authenticating IdP). It might be the same or different for the same user in different assertions (note that it could be a random number but in this case the user ID cannot be used to authorize the user in service ACLs). The protocol specific code will handle extraction of this identifier and return its value. It will be used by Keystone to uniquely identify the user.
* A set of type and value paired identity attributes which will be used to authorize the authenticated user. This set should be consistent and repeatable in multiple assertions.
* A date which defines the maximum validity time of the assertion.
We also assume that IdPs are stored in the existing Keystone Service Catalog as described in [https://blueprints.launchpad.net/keystone/+spec/adding-idps-to-service-catalog here]. The final assumption is that for ease of implementation, higher level utility APIs are available for retrieving a user’s authz attributes using a single API call with a parameter of a list of identity attributes as described [https://blueprints.launchpad.net/keystone/+spec/mapping-distributed-admin here].
Because a temporary user entry is created in Keystone’s database, this means that the UUID returned by Keystone on entry creation would normally be different each time the same federated user accesses OpenStack, so that the UUID could not be used in access control lists. This problem is addressed [https://blueprints.launchpad.net/keystone/+spec/acls-userids-federation here].
=== 3. FIM Controller ===
In this design document, the FIM Controller is the module responsible for orchestrating the validation of the IdP’s assertion and creating the temporary user entry in Keystone’s databases. (In the implementation the FIM Controller is the federated.FederatedAuthentication module.)
==== 3.1 Identifying Users ====
The first stage in this mechanism is to identify the user and to create a temporary user entry within Keystone, which is valid only for the current session. In order to minimize the redundancy of data stored in the Keystone backend, a validity time should be stored alongside each temporary user entry. At each call of the FIM controller’s user creation module, the stored temporary users should be queried and any expired users deleted. In order to maintain current functionality a blank value for validity time will denote a permanent user.

Each federation protocol has its own specific credential validation service (usually a module with the name of the protocol) that validates the IdP’s assertion and returns three parameters: the UNUNID, the set of identity attributes, and the validity time.

The UNUNID is extracted from the returned values and is used as the username for this temporary user entry; its value is not important and is just used by services managed by Keystone to retrieve the user’s authz attributes (role, project and domain assignment information) during authorization. Note that we have modified the Keystone code that issues tokens to ensure that the token’s validity time does not exceed that of the temporary user entry.

The workflow for temporary user entry creation is as follows:
# Call the protocol specific module to validate the IdP’s assertion in a protocol specific way.
# It returns the UNUNID, identity attributes and validity time from the assertion.
# Call the user management module. If a user entry with the UNUNID already exists, then update the validity time to match the latest value, else create a new temporary user entry with a name and UUID created from the UNUNID and a validity time of the returned value. The UNUNID is hashed using SHA1 to create a 20 byte string, then converted into a 40 hexadecimal string.
# In order to create a user entry a password is required. Also the Token API requires that both the username and password are presented for token creation. Consequently, a strong random password is generated during initialization of the Keystone server, and held in memory (only). This is then used for all the temporary users’ passwords. The password is generated as follows: a randomly generated number of size 128 bits is created, concatenated with the current system timestamp in milliseconds, reduced to 20 bytes by using the SHA1 algorithm, then base 64 encoded to produce a 28 character password. This is stored in memory and is lost when the system is stopped. It is important to note that any existing tokens created using the federated middleware will be invalidated at restart time if the user authenticates again, as a new password will have been created. It is a built in mechanism of Keystone user management to invalidate existing tokens when a user’s password is changed.
# It returns the new user details. The username and password will subsequently be used to authenticate on behalf of the federated user and retrieve an unscoped token after attribute mapping has been performed.

==== 3.2 Assigning Authz Attributes to Users according to Attribute Mappings ====
The second stage is to perform the attribute mapping in order to add the user’s authz attributes to the user’s entry. For each attribute mapping that matches a subset of the user’s identity attributes, a set of authz attributes is returned. Each authz attribute set is assigned to the user independently of the other matched sets. There are currently three types of authz attributes in the Openstack service: Roles, Projects and Domains. There are no constraints in the attribute mapping code as to the mapping of these authz attributes from identity attributes, even if some of the mappings may not give the user any OpenStack privileges. However, mappings which do not conform to the current limitations in Keystone will necessarily have to be ignored by the FIM Controller (for now anyway, until the restrictions in Keystone are removed).

Roles alone are currently meaningless in Keystone for authz purposes and must be assigned on a project. There is currently no mechanism for assigning roles to users without the context of a project. This means an authz attribute set containing only OpenStack roles will grant no privileges to the user, and consequently will be ignored by the FIM Controller. Projects alone can be assigned to users, though whether they grant any privileges or not will be determined by the service. These will not be ignored by the FIM Controller.

Both roles and projects are domain specific in the V3 API. However, the concept of a default domain is available and as such, a set containing only roles and projects, or projects alone, will be assigned to the user under this default domain (automatically by the existing Keystone code).

With these constraints in mind, authz attribute assignment within an authz attribute set should conform to the following rules:
* A set comprising roles, projects and domains: each role should be assigned to the user on each project under each domain;
* A set comprising roles and projects only: each role should be assigned to the user on each project under the default domain;
* A set comprising projects and domains is ignored;
* A set containing only projects is ignored;
* A set containing only roles is ignored;
* A set containing only domains is ignored.

With these rules in mind, the following workflow should be followed:

# Retrieve all the existing authz attributes assigned to the user (oldAuthz list). For a new user the list will be empty, but for a returning user it will contain those mapped from his previous identity attributes.
#For each authz attribute set:
## If the set contains 1 or more domains:
### For each domain (D) in the set
#### For each role (R) in the set
##### Assign role (R) under domain (D)
##### Remove from oldAuthz list (if present).
## For each project (P) in the set
### If set contains 1 or more domains AND project's domain does not match any of these domains:
#### Skip this project
### Else:
#### For each role (R) in the set
##### Assign role (R) to user under project (P).
##### Remove from oldAuthz list (if present).
# Any attributes remaining in the oldAuthz set are no longer valid so remove them.

===== Examples =====
The examples assume an environment with three mappings set up in Keystone as follows.

'''Mapping 1'''

Identity Attributes: accountType=Staff

Authz Attributes: role=Admin, role = User, project=myProject

'''Mapping 2'''

Identity Attributes: organization=University of Kent

Authz Attributes: role=Member, project=myProject, domain=Kent

'''Mapping 3'''

Identity Attributes: organization=University of Kent, department=Computing

Authz Attributes: role=developer, project=computingProject, domain=KentComputing

===== Example 1 =====
User Identity Attributes: accountType=Staff, organization=University of Kent

Returned Authz Attribute Sets: {role : Admin, User; project : myProject}, {role : Member, project : myProject, domain : Kent}

Resulting Assignments:
* User is assigned role: Admin on project: myProject under default domain
* User is assigned role: User on project: myProject under default domain
* User is assigned role: Member on project: myProject under domain: Kent
===== Example 2 =====
User Identity Attributes: accountType=Student, organization=University of Kent

Returned Authz Attribute Sets: {role : Member, project : myProject, domain : Kent}

Resulting Assignments:
* User is assigned role: Member on project: myProject under domain: Kent

===== Example 3 =====
User Identity Attributes: department=Computing, organization=University of Kent

Returned Authz Attribute Sets: {role : developer, project : computingProject, domain : KentComputing}, {role : Member, project : myProject, domain : Kent}

Resulting Assignments:
* User is assigned role: Member on project: myProject under domain: Kent
* User is assigned role: developer on project: computingProject under domain: KentComputing

Keystone/Federation/UserIDsInACLs

2013-04-12T10:43:06Z

Kwss:

== Handling ACLs that use UserIDs in Federated Keystone ==
<nowiki>Version 0.5 11 April 2013
Authors: David Chadwick and Kristy Siu </nowiki>

'''Note''' Not all cloud services use ACLs and UserIDs. Those services that use roles for authorisation are not affected by the issue specified in this blueprint.

=== Introduction ===
Federated Keystone does not store permanent user entries for users who authenticate via external Identity Providers (IdPs). Instead [https://blueprints.launchpad.net/keystone/+spec/temp-user-creation temporary user entries are created] for the duration of the validity time of the assertion issued by the Identity Provider. In this way, there are no Keystone administration costs associated with managing user entries. User management and provisioning is done by the IdPs. The Keystone federation code creates temporary entries on user login and automatically deletes them when they have expired. (Note that permanent entries can still be created by omitting the validity time when the entry is created.)
=== Problem Statement ===
A consequence of this is that the same user, with the same set of identity attributes, will have new temporary user entries created each time he logs into OpenStack (unless the existing temporary entry has not expired). Each temporary entry will have a new user_id assigned to it. So the existing user_id for federated users can no longer be used in service ACLs, as the user’s user_id will change every time he logs in. For example, in Swift, container ACLs can hold user_ids in one of three forms: (A) tenant_name:user_id, (B) tenant_id:user_id and (C) *:user_id.
=== Proposed Solution ===
The solution should not affect existing cloud service providers, and they should not have to change their code, so that adding federation to Keystone is backwards compatible to the non-federated use of Keystone.
It is the case that users often still have unique identifiers assigned to them by IdPs. These typically come in two forms: identity attributes that are globally unique, such as email address, and persistent Ids (PIds) issued by the IdP to identify the subject of the assertion to the SP. This blueprint places no requirements on IdPs other than that they should issue one of these unique identifiers if the cloud service uses user-ids in its ACLs.

If a cloud service wishes to use federated identities, and also wishes to use user_ids in ACL, then the following solution is proposed:

# The IdP must issue the user with an identifier whose value is unique throughout the entire federation. We will call this attribute X (it could be an email address or a PId or any other attribute with the required uniqueness property).
# The protocol specific credential validation code must ensure that attribute X is present in the set of identity attributes that are returned to the Keystone federation controller code.
# The service catalog entry for the IdP may record the name of this attribute in the identifier_attribute parameter e.g. identifier_attribute=attributeX if this is appropriate for the protocol used by the IdP. In cases where the protocol always returns the same unique identifying attribute (e.g. Google IdP always uses OpenID as the unique attribute) then this can be handled by protocol specific code.
# The federation code (FIM Core) that creates temporary user entries will use the value of the identifier attribute as the basis for the value of the user_id when the entry is created. Because the value of this attribute could be arbitrarily long, the FIM Controller will SHA1 hash the attribute value (-> 20 bytes) then convert it to 28 base64 characters.
# The Keystone code will be modified so that if the value of the user_id is passed on user creation, it will be used, otherwise the code will behave as before and automatically create a new value.

In this way, the cloud service provider is not impacted by the use of federated identities, and is unaware that anything has changed (except that the value of the user_id attribute may be significantly different than before, and could contain a much wider character set, although if the value is converted and stored in hex (using uuid4().hex) then the service will not see any difference at all).
=== Creating ACLs – The Who Am I? Service ===
Since the temporary user entry probably won’t exist when the service wants to create the ACL, then there must be a way for the service provider to get the user’s user_id. The following is proposed
# A new Keystone service request/response (the Who Am I? service) will be provided which will allow the user to find out all of his attributes (both IdP provided and Keystone provided).
# The user will enter the two command line parameters –F and -? (F for federated, ? for who am I?)
# The API call will contain the headers X-Authentication-Type: federated and X-Request-Type:WhoAmI
# The FIM Controller will trap this request, and after it has created the temporary user entry and performed the attribute mapping, it will return the set of identity attributes and the unique identifier value issued by the IdP and the Keystone temporary entry that has been created (user name, user id, project, roles etc.)

Keystone/Federation/Blueprint

2013-02-25T12:02:21Z

Kwss: /* Implementation Status */

= Federated Keystone =
Providing Federated Access to OpenStack Clouds

Version: 1.2 Author: David W Chadwick Date: 22 February 2013

__TOC__
== Overview ==
The overall idea is that Keystone will no longer be the only identity service for OpenStack services, but instead, there will be a wide range of identity services distributed around the Internet, called Identity Providers (IdPs). The advantages of using external identity providers are numerous, and include:

* there is no longer any need to provision user entries in Keystone, since the user entries already exist in the IdP's databases.
* there is no need to build additional authentication mechanisms into Keystone, since the IdPs take care of authenticating their own users using whichever technologies they deem to be appropriate. So multiple authentication technologies are already in use.
* there is no need to support users who forget their passwords. The IdPs already do this.
* multiple collaborating organisations can quickly share the same cloud services by each one using their own local IdP to authenticate their users.
* it provides single sign on to the user, who can use the same set of credentials with his IdP to access many different services on the Internet.

The way it works is this. The user contacts Federated Keystone, which presents the user with the list of trusted IdPs. The user chooses his IdP from this list, and his client is redirected to it. The user then directly authenticates with his own IdP. Assuming the authentication is successful, the IdP returns an authentication and authorisation token to Keystone, which validates it, then swaps it for the normal unscoped and scoped Keystone tokens which allow the user to access the OpenStack services.

== Guiding Principles ==
# Each cloud service keeps it existing tenants/projects and roles for authz, and passes the bulk of the work off to Federated Keystone to do the heavy lifting (i.e. interacting with the Identity Providers, validating the various credentials, mapping the attributes into the ones understood by the service etc.).
# There can be thousands of Identity Providers/Attribute Authoritys with millions of different attributes. It would be too complex for Cloud Service Providers (CSPs) to have to create authz policies based on these. Consequently each Cloud Service Provider has its own limited set of attributes and roles, and only trusts Keystone to issue them. It trusts Keystone to map between the externally provided attributes and the internally understood ones. (In fact the CSPs are unaware of whether Keystone is federated or not.) Federated Keystone is the only known (and trusted) Identity Provider to the Cloud Service Providers. In the non-federated world the architecture degenerates to the current Keystone implementation.
# Consequently, all Identity Provider/Attribute Authority issued attributes/roles must be globally identifiable, either via their unique name/type (e.g. a URN) or via the name of their issuer (DNS name) and their local name (see Appendix 2).
# Federated Keystone has a set of trust relationships with a set of external Identity Providers, Authentication Services and Attribute Authoritys. The Keystone administrator enters these trusted entities into (an enhanced) Keystone Service Catalog. The Attribute Mapper of Federated Keystone knows how attributes from these external entities map into the local attributes known by the Cloud Service Providers. This information may be configured into the Keystone administrator, or he may delegate this task to trusted administrators from the Identity Providers (see Blueprint https://blueprints.launchpad.net/keystone/+spec/mapping-distributed-admin).
# Since external Identity Providers hold all the identity details of the users in their own databases, there is little point in Keystone duplicating this information. Consequently there is no longer any requirement to add users to Keystone's database. Instead, when a federated user contacts Keystone, a temporary entry is automatically created for him by the federation software, and this is only valid for the duration of the user's IdP generated token. When the entry times out, the entry is automatically deleted by the federation software. A consequence of this is that Cloud Service Providers should no longer use Keystone generated User IDs in their access control lists, but instead should use a persistent identity attribute of the user, such as his email address or the PID created by SAML IdPs.
# Most existing authentication systems rely on usernames and passwords. We have to live with that. Consequently all existing federated authn systems are open to phishing attacks, whereby an evil SP redirects the user to a fake Identity Provider which then captures the user’s un/pw. In the current design the simple client is open to such attacks, whereas the intelligent client (Attribute Aggregator) is not. With the intelligent client, after the user decides which attributes and issuers to use, the Attribute Aggregator performs a directory lookup in the enhanced service catalog to find the issuer in order to obtain its metadata and make a direct request to it. In this case the user cannot be re-directed to a fake issuer by an evil SP and have his password stolen.
# The user knows which cloud service he wishes to use, so ideally this should be his first port of call (and not Keystone or some external IdP). But given that the existing mode of operation is to contact Keystone first, then we keep this in the first implementation.

== Single Identity Provider, Simple Client ==
In this mode of operation, the user has a simple client and trusts Federated Keystone (FK) to behave correctly. A single IdP authenticates the user and provides all the user's authorisation attributes to FK.

The downside of a simple client is that it is open to phishing attacks from evil Keystones, which redirect the client to a false IdP in step 10.However, the phishing can be nullified if the IdP uses a zero proof authentication mechanism, since in this case no secrets will be revealed by the simple client. Alternatively the intelligent client ([[AtAg]]) can be used.

The swimlanes that pictorially show this protocol flow are available from dropbox [http://dl.dropbox.com/u/44986510/SwinLaneSimpleClient.pdf SwinLane Simple Client]

# The user launches his federated client
# The client contacts federated Keystone (FK)
# FK retrieves the set of trusted Identity Providers from the directory service (enhanced service catalog)
# FK sends the set of Identity Providers to the client in response to message 2.
# The user chooses which Identity Provider he wishes to use
# The client returns the chosen Identity Provider to FK.
# FK performs a directory lookup on this Identity Provider, and obtains its metadata
# FK then calls the Request Issuing Service to create an authentication and attribute request in the appropriate format for the chosen Identity Provider.
# FK returns the Identity Provider request message to the client, along with the address of the Identity Provider
# The client passes the request to the Identity Provider
# The Identity Provider asks the user to authenticate by its chosen method (out of scope of this proposal). It could be PKI based, Kerberos based, simple UN/PW, or OTP etc. How strongly the user is authenticated is reflected in the Level of Assurance (LoA) that is returned in the response (providing the protocol supports this).
# Having identified the user, the Identity Provider returns the authentication and attribute assertion to the client (as a binary blob)
# The client passes the Identity Provider’s response to FK.
# FK calls the Credential Validation Service (CVS) to validate the Identity Provider’s response
# The CVS calls the directory service to get the IdP's meta data in order to validate the response
# The CVS returns the user's valid attributes to FK
# FK calls the Attribute Mapping Service to obtain the local set of attributes that are equivalent to the Identity Provider provided set.
# FK calls the Token Issuing Service (TIS) to obtain an unscoped token for the user
# FK returns the unscoped token to the user, along with a list of tenants/projects available to the user
# The user choses which tenant/project he wishes to use
# The client passes the unscoped token and tenant/project to FK
# FK calls the token validation service (TVS) to validate the unscoped token
# FK then calls the TIS to issue a scoped token for the user
# FK returns the scoped token and list of cloud services at which this can be used to the client.
# The client contacts the Cloud Service Provider with the scoped token, requesting the service
# The Cloud Service Provider passes the scoped token to FK for validation
# FK contacts the TVS to validate the token and gets the response
# FK sends the reply to the Cloud Service Provider
# The Cloud Service Provider asks the PDP is the user is authorised for this request
# The Cloud Service Provider sends the response to the client
# The client makes additional requests to the Cloud Service Provider using the same scoped token, goto 25.

=== Implementation Status ===
The simple client mode has now been fully implemented for both the Keystone V2 and V3 APIs, and several existing OpenStack clients have been enhanced to support federated access to Keystone. More enhanced clients are expected to follow in due course.

The Keystone V2 implementation is available from [https://github.com/kwss/keystone.git here]

Until Grizzly is officially released, the Keystone V3 implementation is only available directly from the authors at the University of Kent. Please email them to get your copy

The Keystone V3 implementation implements the following blueprints
* Adding IdPs to an enhanced Keystone Service Catalog [https://blueprints.launchpad.net/keystone/+spec/adding-idps-to-service-catalog adding-idps-to-service-catalog]
* Mapping attributes from Identity Providers to internal OpenStack attributes [https://blueprints.launchpad.net/keystone/+spec/role-mapping-service-keystone role-mapping-service-keystone]
* Distributed Administration of the Attribute Mapping function [https://blueprints.launchpad.net/keystone/+spec/mapping-distributed-admin mapping-distributed-admin]
* Federating multiple Keystone services together [https://wiki.openstack.org/wiki/Keystone/Delegation Delegation of Keystone Servers]

== Single Identity Provider, Intelligent Client ==
''NOTE. There is currently no plan to implement the Intelligent Client, so the following should be regarded as an approximate outline only, and it may contain errors.''

This mode protects the client from phishing attacks by evil Keystones and other services since the intelligent client decides for itself how to contact the user’s Identity Provider. It therefore cannot be redirected to an evil CSP. The swimlane diagram for the Intelligent Client can be found here [[attachment:SwimlaneIntelClient.pdf]]

# The user types in his request to the client
# The user contacts the Cloud Service to request a service
# The Cloud Service Provider sends the client its attribute requirements policy (ARP) and the address of the Openstack Gateway to contact.
# The client passes the ARP to Openstack Gateway
# Openstack Gateway calls the Attribute Mapping Service to convert the ARP into one that contains the external attributes and Identity Providers that may be capable of fulfilling the policy.
# Openstack Gateway passes the set of external attributes and Identity Providers back to the client as an External Attributes Requirements Policy (EARP).
# The client passes the policy to its intelligent Attribute Aggregation component ([[AtAg]]) which filters the policy against the user’s attributes.
# Attribute Aggregator asks the user which of his possible attributes and Identity Providers he wants to use to access the Cloud Service Provider e.g. he may have several roles, credit cards, email addresses etc. and can choose between them. He may have several Identity Providers that can fulfil the policy. The user chooses his preferred Identity Provider and attributes.
# Attribute Aggregator contacts the Directory service, passing it the name of the user’s chosen Identity Provider, to find out the latest contact details (meta information) of it. Note. If Attribute Aggregator has this information configured into it, then this step can be omitted.
# Attribute Aggregator contacts the Request Issuing Service (RIS) to obtain a properly formatted Authn request in the correct protocol. It is returned a binary blob (the Identity Provider authentication and attribute request message). The attribute request contains the mapped set of attributes required by the cloud service. Note that the intelligent Attribute Aggregator may have the RIS as a built in service.
# Attribute Aggregator contacts the chosen Identity Provider, sending it the binary blob.
# The Identity Provider authenticates the user by its chosen method (out of scope of this proposal). It could be PKI based, Kerberos based, simple UN/PW, or OTP etc. How strongly the user is authenticated is reflected in the Level of Assurance (LoA) that is returned in the response (providing the protocol supports this).
# Having identified the user, the Identity Provider returns the authentication and attribute assertion to Attribute Aggregator (as a binary blob)
# Attribute Aggregator passes this response to the client
# The client passes the assertion to Openstack Gateway.
# Same as Single Identity Provider, Simple Client from now onwards

== Mode of Operation with Holder of Key Verification ==
In both of the single Identity Provider modes the assertions returned by the client to federated Keystone are bearer credentials. Furthermore the tokens (scoped and unscoped) produced by Keystone are also bearer credentials. This means that federated Keystone cannot be certain that the credentials produced by the IdP actually belong to the client that is presenting them. Furthermore, the cloud service providers cannot be sure that the token presented by the user actually belongs to the user. Using holder of key verification, the client creates a new key pair for each session, and the Identity Provider inserts the public key into the assertions. The client can then prove to federated Keystone (by signing a message) that it has the private key that corresponds to the public key in the assertions, and therefore that the assertions belong to it. Similarly the client can prove to the cloud services that the token belongs to it, by signing a message to the cloud service. The protocol steps are the same as before, but the protocol messages are different as stated below.

* For Single Identity Provider, Simple Client, the procedure is the same until step 11 when the client creates a new key pair for the user and includes the public key in the authentication exchange with the Identity Provider. In step 12 the Identity Provider includes the public key in the response that it creates for federated Keystone. In step 13 the client signs the message containing the Identity Provider’s response. This allows federated Keystone to prove, in step 14, that the client is the rightful owner of the Identity Provider’s response. In step 18 Keystone's token issuing service inserts the user's public key into the token, and in step 21 the client signs the request message to Keystone, which validates it in step 22. This process is repeated again in steps 23 to 27, so that now the cloud service provider can validate that the client is the rightful owner of the token.
Note that the whole token model and structure that Keystone currently uses needs enhancing to overcome its current multiple limitations (replayable, copyable, escalation of privileges etc.) but this is outside the scope of the current blueprint.

* ''Note that this text has not been corrected''. For Single Identity Provider, Intelligent Client, the procedure is the same until step 11 when Attribute Aggregator creates a new key pair for the user, and includes the public key in the user’s authentication exchange with the Identity Provider. In step 12 the Identity Provider includes the public key in the response that it creates for the Openstack Gateway. In step 13 Attribute Aggregator passes the new key pair back to the client along with the Identity Provider’s response. In step 14 the client signs the message containing the Identity Provider’s response with its private key. This allows Openstack Gateway to prove that the client is the rightful owner of the Identity Provider’s response.

== Mode of Operation using an Authentication Service and Attribute Authority ==
''NOTE. There is currently no plan to implement a separate Authentication Service and Attribute Authority, so the following should be regarded as an approximate outline only, and it may contain errors.''

In this mode of operation the attribute authority uses an external authentication service to authenticate clients who want to retrieve attributes from it. Attribute Authorities work in the following way. An unknown user contacts the Attribute Authority for a service, and the Attribute Authority redirects the user to one of its trusted Authentication Services (or Identity Providers). The user must already have a relationship with one of these trusted authentication services. The user authenticates to the Authentication Service (or Identity Provider) and the Authentication Service returns to the Attribute Authority an authentication assertion containing a persistent ID (PID). From now on, the Attribute Authority will know this user as PID issued by Authentication Service. The user pays the Attribute Authority for the service and the Attribute Authority issues the user with an attribute, which it stores permanently in its database along with the user’s ID (PID@AS). Whenever the user wishes to retrieve its attribute, it must contact the Attribute Authority, be redirected to the same Authentication Service (or Identity Provider), authenticate, and then the Attribute Authority can validate the identity of the user (PID@AS) and issue it with an attribute assertion, or possibly with an authentication and attribute assertion (depending upon whether the Attribute Authority is willing to underwrite the authentication performed by the Authentication Service. Clearly it is to some extent, otherwise it would not issue the attribute assertion. See also Appendix 1). The user ID in the attribute (and authentication) assertion may be a random ID, the same PID as that issued by the Authentication Service, or a different PID generated by the Attribute Authority (in which case the Attribute Authority will need to keep the PID mappings). The user should be able to choose which type of ID it requires in the attribute assertion.

The swimlanes for this protocol flow can be found here [[attachment:SwimlaneAA+AS.pdf]]

# The user contacts the Cloud Service to request a service
# The Cloud Service Provider sends the client its attribute requirements policy (ARP) and the address of the Openstack Gateway to contact.
# The client passes the ARP to Openstack Gateway
# Openstack Gateway calls the Attribute Mapping Service to convert the ARP into one that contains the external attributes, Attribute Authoritys, Authentication Services and Identity Providers that may be capable of fulfilling the policy. Note that an Authentication Service will only occur in this policy if the Openstack Gateway requires a PID for the user from a trusted Authentication Service (and does not trust the Attribute Authority to issue one). Note that if the ARP is fixed then the mapping can also be fixed.
# Openstack Gateway passes the set of external attributes, Attribute Authoritys, Authentication Services and Identity Providers back to the client as an External Attributes Requirements Policy (EARP).
# The client passes the policy to its intelligent Attribute Aggregation component ([[AtAg]]) which filters the policy against the user’s attributes.
# Attribute Aggregator asks the user which of his possible attributes (and issuers) he wants to use to access the Cloud Service Provider e.g. he may have several roles, credit cards, email addresses etc. and can choose between them. He may have several Identity Providers and Attribute Authoritys that can fulfil the attribute requirements of the policy. The user chooses his preferred attributes (and its issuer).
# Attribute Aggregator contacts the Directory service, passing it the name of the user’s chosen Attribute Authority, to find out the latest contact details (meta information) of it. Note. If Attribute Aggregator has this information configured into it, then this step can be omitted.
# Attribute Aggregator contacts the Request Issuing Service (RIS) to obtain a properly formatted Attribute request in the correct protocol. It is returned a binary blob (the attribute request message). The attribute request contains the set of attributes required by Openstack Gateway. Note that the intelligent Attribute Aggregator may have the RIS as a built in service.
# Attribute Aggregator contacts the chosen Attribute Authority, sending it the binary blob.
# The Attribute Authority asks Attribute Aggregator to authenticate via its Authentication Service, passing it the login URL. The Attribute Authority may only use one Authentication Service, or it may use several in which case it will ask Attribute Aggregator (i.e. the user) to choose which Authentication Service it normally uses.
# The user chooses which Authentication Service he wants to use
# Attribute Aggregator contacts the Authentication Service at its login URL.
# Authentication Service authenticates the user by its chosen method (out of scope of this proposal). It could be PKI based, Kerberos based, simple UN/PW, or OTP etc. How strongly the user is authenticated is reflected in the Level of Assurance (LoA) that is returned in the response (providing the protocol supports this).
# Having identified and authenticated the user, the Authentication Service returns the authentication assertion to Attribute Aggregator containing the PID of the user (as a binary blob)
# Attribute Aggregator passes the assertion to the Attribute Authority.
# The Attribute Authority validates the assertion, looks up the user in its database and returns the attribute (and possibly authentication) assertion to Attribute Aggregator
# Depending upon Openstack Gateway’s EARP, Attribute Aggregator may return either the attribute (and authentication) assertion from the Attribute Authority, or the attribute assertion from the Attribute Authority and the authentication assertion from Authentication Service to the client.
# The client passes the response to Openstack Gateway.
# From now on it is the same as from step 15 in the single Identity Provider, simple client case.

== Mode of Operation with Attribute Aggregation ==
''NOTE. There is currently no plan to implement attribute aggregation, so the following should be regarded as an approximate outline only, and it may contain errors.''

Attribute aggregation is required when the Openstack Gateway needs attributes from multiple trusted sources and a single Identity Provider is insufficient to verify the identity of the user. Thus multiple Identity Providers are required (or multiple Attribute Authoritys and an Identity Provider or Authentication Service).

With multiple Identity Providers it would be possible to simply ask the user to authenticate to each Identity Provider separately in order to pick up each set of attributes. Multiple authentication exchanges are inconvenient to the user, so the mechanism should be able to support SSO. However, SSO requires that some component stores the PIDs of the user at each Identity Provider/Authentication Service and can map between them, or that the user is known by the same PID at each Identity Provider/Authentication Service, which is unlikely (unless it is a government issued eID). A crude SSO mechanism is that the Attribute Aggregator could securely store the user’s credentials at each Identity Provider and have one strong master PW to unlock them all. Then Attribute Aggregator could authenticate directly to each Identity Provider in order to pick up the user’s attributes.

If we have Attribute Authorities and Authentication Services, if each Attribute Authority uses/trusts the same Authentication Service (or Identity Provider), then the Authentication Service can issue PIDs for each Attribute Authority, and use SSO when each Attribute Authority redirects the user to it for authentication. In this case the Attribute Authorities only need to trust the same Authentication Service and Attribute Aggregator can aggregate all the attribute assertions by contacting each Attribute Authority in turn, and then send the full set of attributes to the Openstack Gateway.

It is also possible for Identity Providers to mutually trust each other and allow SSO between themselves. This can work as follows. The user authenticates to one Identity Provider, which asks the user if he wants to federate his identity with another Identity Provider. If the user agrees, Identity Provider1 (acting as an SP) redirects the user to Identity Provider2, whereupon the user authenticates and Identity Provider2 returns the user’s PID2 to Identity Provider1. From now on the user can pick up his attributes from Identity Provider1 by being authenticated by Identity Provider2. The user goes to Identity Provider1, is redirected by Identity Provider1 to Identity Provider2, where he authenticates, his PID2 is sent to Identity Provider1, whereupon his attributes are returned to him. If all the Identity Providers federate with and trust Identity Provider2, it can hold the set of PIDs for this user, and the user can use Identity Provider2 for SSO. Attribute Aggregator can collect attribute assertions from each Identity Provider in turn to give to Openstack Gateway, and the user only needs to authenticate once (to Identity Provider2).

If the user has not federated all his Attribute Authorities and Identity Providers to a single authentication service (Authentication Service or Identity Provider) then SSO is not possible without additional support from Attribute Aggregator. We can use Attribute Aggregator to hold the PID mappings as follows. Attribute Aggregator has its own key pair, certified by a CA trusted by the federation Identity Providers. Attribute Aggregator initially acts as an SP to each Identity Provider and asks the Identity Provider to authenticate the user. The user authenticates to the Identity Provider, which returns the user’s PID to Attribute Aggregator. Attribute Aggregator can subsequently mutually authenticate with the Identity Provider using its key pair, and ask to pick up the user’s attributes by quoting the relevant PID. Providing the Identity Provider is happy to release the user’s attributes at any time to the Attribute Aggregator SP, this will work. If however, the Identity Provider wants proof that the user is currently logged in to the SP, then Attribute Aggregator can give the Identity Provider the current authentication assertion issued to the user by the current Authentication Service. Providing the Identity Provider trusts this Authentication Service it should be prepared to return the user’s attributes to Attribute Aggregator. Alternatively, Attribute Aggregator could securely store the user’s authentication credentials at each Identity Provider and have one strong master PW to unlock them all. Then Attribute Aggregator could authenticate directly to each Identity Provider in order to pick up the user’s attributes.

In the flow below we assume that the user has federated all his attribute issuers (Attribute Authoritys and Identity Providers) with a single authentication service (AS). The protocol flow is the same as that in using an Authentication Service and Attribute Authority, up to step 17, after which one or more additional Attribute Authorities are contacted. The protocol flow then resumes as in step 18 of using an Authentication Service and Attribute Authority.

The swimlanes for this protocol flow is available here [[attachment:SwimlaneAttAgg.pdf]]

18. Attribute Aggregator contacts RIS asking for an attribute request for AA2 and is returned the binary message.

19. Attribute Aggregator passes the message to AA2 asking for the user’s attributes

20. The Attribute Authority asks Attribute Aggregator to authenticate via its Authentication Service, passing it the login URL. The Attribute Authority may only use one Authentication Service, or it may use several in which case it will ask Attribute Aggregator (i.e. the user) to choose which Authentication Service it normally uses.

21. Attribute Aggregator chooses the Authentication Service already in use and contacts the Authentication Service at its login URL passing it the existing session cookie.

22. Authentication Service sees that the user is currently logged in, so returns the authentication assertion for AA2 (containing the PID of the user) to Attribute Aggregator

23. Attribute Aggregator forwards the authentication assertion to AA2

24. AA2 validates the assertion, looks up the user in its database and returns the attribute (and possibly authentication) assertion to Attribute Aggregator

25. Attribute Aggregator returns the complete set of assertions to the client as in step 18 of using an Authentication Service and Attribute Authority

== Appendix 1. Attribute Assertions vs Authentication Assertions ==
Once we progress towards an attribute based authorisation infrastructure, the difference between attribute and authentication assertions should disappear. The former is a more generic assertion than the latter. Authn assertions only contain an ID attribute (which may be a public key) plus details of how strongly the user was authenticated. Attribute assertions may contain any attribute (including an ID attribute or public key) and should contain details of how strongly the user was authenticated in order to obtain the attribute assertion. Thus we should be able to dispense with authentication assertions and only have attribute assertions, providing of course each attribute assertion contains details of how strongly the user was authenticated in order to obtain it.

== Appendix 2. Attributes vs Attribute Authorities ==
Attributes may be globally defined, e.g. visa attributes, or locally defined e.g. member of club X. Globally defined attributes are often specified in international standards and may be used in several different domains and federations. Their syntax and semantics are fixed, regardless of which Attribute Authority issues them. Local attributes are defined by their issuing attribute authority and usually are only valid in the domain or federation in which the Attribute Authority is a member. For locally identifiable attributes the attribute authority (issuer) must be globally identifiable (in the federation). The attribute then becomes globally identifiable through hierarchical naming (Attribute Authority.attribute).

Trust in an attribute assertion is always decided by the relying party. However, relying parties would normally only trust local attributes that are issued by the Attribute Authority which defines them. For example. No RP would believe an Attribute Authority who said I was a member of club X, if the Attribute Authority for club X was not prepared to assert this. (Note that with delegation of authority this is slightly different, because a member of club X may also act as an Attribute Authority and assert that someone else is a member of club X. But the original assertion of membership came from the Attribute Authority (or SoA) of club X.)

Globally defined attributes may be issued by many different Attribute Authoritys. So the RP has to specify which Attribute Authority it trusts to issue which globally defined attributes. If an attribute is very popular there may be hundreds or thousands of Attribute Authoritys which issue it, e.g. role. The Visa attribute is one such attribute which is issued by hundreds of banks (as plastic credit cards). However, in the Visa case, it supports delegation of authority and there is only one Source of Authority for the Visa attribute. Relying parties have a central service they can contact to ask if the issuer and attribute assertion (credit card) is valid or not. So they do not need to specify who they trust to issue this attribute, they simply specify that they accept this attribute, regardless of who issued it, because they have a trusted server for checking if the issuer (and the assertion) is genuine or not. Note that in the case of Visa these are long lived assertions, so a means of revocation checking is essential. In this case the revocation checking process serves to check if the issuer is trusted as well as if the assertion is still valid. When we use short lived assertions the situation is different, since there is no revocation checking mechanism. It is deemed to be not needed since a valid assertion will never be revoked. But we still have the issue of knowing whether the issuer is genuine or not. Simply checking the digital signature is not enough, since anyone can get a valid PKC from Verisign and with this can sign anything. Consequently anyone can issue a short lived Visa attribute assertion. So how does the relying party know if this is a valid issuer or not, given that there is no revocation checking mechanism? One solution is for the RP to keep a list of trusted Attribute Authoritys for each globally defined attribute. But this potentially has a scalability problem. Delegation of authority is the way of solving the scalability issue. In this case we have one root Attribute Authority (the Source of Authority, SoA) and all other Attribute Authoritys are delegated by it. In this case the RP only needs to trust the SoA and then any Attribute Authority delegated by the SoA is a trusted Attribute Authority. We can support delegation of authority either by having assertion chains (SoA-> Attribute Authority) or a central service run by the SoA for checking the validity of an Attribute Authority (as in the Visa case).

== Glossary ==
AA – Attribute Authority. An authoritative source of user attributes E.g. a bank can provide a credit card attribute, a university a degree attribute, an employer the role attribute etc.

AM – Attribute Mapper. Maps from externally provided attributes into the equivalent internal attributes (roles/projects etc) used by cloud services, or vice versa.

ARP – Attribute Requirements Policy. Created by a service provider to inform the user which attributes, from which trusted authorities, and to which level of assurance, are needed in order to access the service

AS – Authentication Service. Is able to authenticate a user and issue an (authentication) assertion containing a unique persistent identifier (PID) for each user. May or may not know who the user actually is in the physical world – this is specified in the Level of Assurance of the issued assertion - but can determine that it is the same virtual user every time. One can consider an AS to be an Identity Provider that only issues a PID attribute and no other attribute.

[[AtAg]] – Attribute Aggregator, an intelligent component of the client that is responsible for evaluating the service’s attribute requirements policy, and then contacting the set of Identity Providers/AAs/ASs as necessary to obtain the identity attributes required to access the service. It is fully controlled by the user. It knows which Identity Providers and AAs hold which attributes for this user. It also holds user self-asserted attributes. It may also know how to authenticate the user to each Identity Provider and AA/AS.

Authz – Authorisation Service. Given an authz request “can a user with these identity attributes access this resource” typically returns granted or denied

Client – the basic software necessary for interfacing to the cloud on behalf of the user. Could be a standard browser or command line client.

Cloud Service Provider 1…n (CSPs) – these are the cloud service providers that are using the [[OpenStack]] Gateway to provide is identity and access management functionality

CVS – Credential Validation Service. Given an authentication and/or attribute assertion will return the set of valid identity attributes. Is driven by a credential validation policy

Dir – Directory Service (enhanced Keystone Service Catalog). Contains the set of identity and attribute authorities and cloud service providers and the information needed to contact them (so called meta data).

IdP – Identity Provider. A combination of an Authentication Service and Attribute Authority. Can issue authentication and attribute assertions.

FK – Federated Keystone. An enhanced version of Keystone which can federate with external Identity Providers. It is a proxy IDP, in that it is seen to be an IdP by the CSPs, but a service provider by the external IdPs.

RIS – Request Issuing Service. Given the output of the directory service, issues the federated authentication and attribute request in the appropriate protocol. There may be one RIS per federation protocol that is supported.

TIS – Token Issuing Service. Provides tokens to OG for it to give to the user/client

TVS – Token Validation Service. Validates the tokens given to OG by the Cloud Service Providers

== MSc Dissertation ==
An MSc dissertation describing the first prototype implementation can be downloaded from [http://dl.dropbox.com/u/44986510/Yanndissertation.pdf MSc Dissertation]. Please note that the current implementation is already an enhancement of this, and has started to remove many of the limitations of the original implementation. Nevertheless the disseration provides useful backgroung reading to implementors