openstack-attic/identity-api
Code Issues Proposed changes

Added HP-IDM extension.

Browse Source 
Change-Id: I7d474957f9547ce2dd08a4b3251dec1f7fe671ac
This commit is contained in:
Jorge L. Williams 2011-12-23 12:06:24 -06:00
parent 536bdcfaa7
commit 61fd0267d2
7 changed files with 511 additions and 2 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

37
openstack-identity-api/pom.xml
View File

@ -33,7 +33,7 @@
</profiles>
<properties>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
<doctools.version>1.0.6-SNAPSHOT</doctools.version>
<doctools.version>1.0.9-SNAPSHOT</doctools.version>
</properties>
<dependencies>
@ -156,6 +156,14 @@
<arg value="-xsl:${project.build.directory}/generated-resources/cloud/normalizeWadl/normalizeWadl.xsl"/>
<arg value="-o:${project.build.directory}/generated-resources/xml/xslt/OS-KSEC2-admin.wadl"/>
</java>
<java
jar="${net.sourceforge.saxon:saxon:jar}"
fork="true">
<arg value="-u"/>
<arg value="-s:src/docbkx/HP-IDM/HP-IDM-admin.wadl"/>
<arg value="-xsl:${project.build.directory}/generated-resources/cloud/normalizeWadl/normalizeWadl.xsl"/>
<arg value="-o:${project.build.directory}/generated-resources/xml/xslt/HP-IDM-admin.wadl"/>
</java>
</target>
</configuration>
<goals>
@ -256,7 +264,32 @@
</postProcess>
</configuration>
</execution>
</executions>
<execution>
<id>HP-IDM</id>
<goals>
<goal>generate-pdf</goal>
<goal>generate-webhelp</goal>
</goals>
<phase>generate-sources</phase>
<configuration>
<includes>HP-IDM/HP-IDM.xml</includes>
<trimWadlUriCount>1</trimWadlUriCount>
<pdfUrl>hp-idm.pdf</pdfUrl>
<canonicalUrlBase>http://docs.rackspacecloud.com/openstack-extensions/auth/hp-idm/content</canonicalUrlBase>
<chunkSectionDepth>0</chunkSectionDepth>
<postProcess>
<copy todir="target/docbkx/webhelp/HP-IDM/HP-IDM/content/">
<fileset dir="target/docbkx/pdf/HP-IDM">
<include name="**/*.pdf"/>
</fileset>
<fileset dir="src/docbkx/HP-IDM/samples/">
<include name="ext_query.xml"/>
</fileset>
</copy>
</postProcess>
</configuration>
</execution>
</executions>
<configuration>
<!-- These parameters apply to pdf and webhelp -->
<xincludeSupported>true</xincludeSupported>

150
openstack-identity-api/src/docbkx/HP-IDM/HP-IDM-admin.wadl Normal file
View File

@ -0,0 +1,150 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--*******************************************************-->
<!-- Import Common XML Entities -->
<!-- -->
<!-- You can resolve the entites with xmllint -->
<!-- -->
<!-- xmllint -noent HP-IDM-admin.wadl -->
<!--*******************************************************-->
<!DOCTYPE application [
<!ENTITY % common SYSTEM "https://raw.github.com/openstack/keystone/master/keystone/content/common/common.ent">
%common;
]>
<application xmlns="http://wadl.dev.java.net/2009/02"
xmlns:identity="http://docs.openstack.org/identity/api/v2.0"
xmlns:HP-IDM="http://docs.openstack.org/identity/api/ext/HP-IDM/v1.0"
xmlns:capi="http://docs.openstack.org/common/api/v1.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsdxt="http://docs.rackspacecloud.com/xsd-ext/v1.0">
<grammars>
<include href="https://raw.github.com/openstack/keystone/master/keystone/content/common/xsd/api.xsd"/>
<include href="https://raw.github.com/openstack/keystone/master/keystone/content/common/xsd/api-common.xsd"/>
</grammars>
<!--*******************************************************-->
<!-- All Resources -->
<!--*******************************************************-->
<!-- We should use SSL in production -->
<resources base="http://localhost:35357">
<resource id="version" path="v2.0">
<resource id="tokens" path="tokens">
<resource id="tokenById" path="{tokenId}">
<param name="X-Auth-Token" style="header" type="xsd:string" required="true">
<doc>You need a valid admin token for access.</doc>
</param>
<param name="tokenId" style="template" type="xsd:string" required="true"/>
<param name="belongsTo" style="query" type="xsd:string" required="false"/>
<param name="HP-IDM-serviceId" style="query" type="xsd:string" required="false"/>
<method href="#validateToken"/>
<method href="#checkToken"/>
</resource>
</resource>
</resource>
</resources>
<!--*******************************************************-->
<!-- All Methods -->
<!--*******************************************************-->
<!-- Token Operations -->
<method name="GET" id="validateToken">
<doc xml:lang="EN" title="Validate Token">
<p xmlns="http://www.w3.org/1999/xhtml" class="shortdesc">
Check that a token is valid and that it belongs to a supplied tenant
and services and return the permissions relevant to a particular client.
</p>
<p xmlns="http://www.w3.org/1999/xhtml">
Valid tokens will exist in the
<code>/tokens/{tokenId}</code> path and invalid
tokens will not. In other words, a user should expect an
itemNotFound (<code>404</code>) fault for an
invalid token.
</p>
<p xmlns="http://www.w3.org/1999/xhtml">
If 'HP-IDM-serviceId' is provided, it must be a comma-separated string of
service IDs. If any of the service IDs is invalid or if there are no
roles associated with the service IDs, a user should expect a 401.
</p>
</doc>
<request>
<param name="belongsTo" style="query" required="false" type="xsd:string">
<doc xml:lang="EN">
<p xmlns="http://www.w3.org/1999/xhtml">
Validates a token has the supplied tenant in scope.
</p>
</doc>
</param>
<param name="HP-IDM-serviceId" style="query" required="false" type="xsd:string">
<doc xml:lang="EN">
<p xmlns="http://www.w3.org/1999/xhtml">
If provided, filter the roles to be returned by the given service IDs.
</p>
</doc>
</param>
</request>
<response status="200 203">
<representation mediaType="application/xml" element="identity:access">
<doc>
<xsdxt:code href="../samples/validatetoken.xml"/>
</doc>
</representation>
<representation mediaType="application/json">
<doc>
<xsdxt:code href="../samples/validatetoken.json"/>
</doc>
</representation>
</response>
&commonFaults;
&getFaults;
</method>
<method name="HEAD" id="checkToken">
<doc xml:lang="EN" title="Check Token">
<p xmlns="http://www.w3.org/1999/xhtml" class="shortdesc">
Check that a token is valid and that it belongs to a particular tenant and services
(For performance).
</p>
<p xmlns="http://www.w3.org/1999/xhtml">
Valid tokens will exist in the
<code>/tokens/{tokenId}</code> path and invalid
tokens will not. In other words, a user should expect an
itemNotFound (<code>404</code>) fault for an
invalid token.
</p>
<p xmlns="http://www.w3.org/1999/xhtml">
If `belongsTo` is provided, validates that a token has a specific tenant in scope.
</p>
<p xmlns="http://www.w3.org/1999/xhtml">
If 'HP-IDM-serviceId' is provided, it must be a comma-separated string of
service IDs. If any of the service ID is invalid or if there are no
roles associated with the service IDs, a user should expect a 401.
</p>
<p xmlns="http://www.w3.org/1999/xhtml">
No response body is returned for this method.
</p>
</doc>
<request>
<param name="belongsTo" style="query" required="false" type="xsd:string">
<doc xml:lang="EN">
<p xmlns="http://www.w3.org/1999/xhtml">
Validates a token has the supplied tenant in scope. (for performance).
</p>
</doc>
</param>
<param name="HP-IDM-serviceId" style="query" required="false" type="xsd:string">
<doc xml:lang="EN">
<p xmlns="http://www.w3.org/1999/xhtml">
Check the roles against the given service IDs.
</p>
</doc>
</param>
</request>
<response status="200 203"/>
&commonFaults;
&getFaults;
</method>
</application>

275
openstack-identity-api/src/docbkx/HP-IDM/HP-IDM.xml Normal file
View File

@ -0,0 +1,275 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book [
<!-- Some useful entities borrowed from HTML -->
<!ENTITY ndash "&#x2013;">
<!ENTITY mdash "&#x2014;">
<!ENTITY hellip "&#x2026;">
<!-- Useful for describing APIs -->
<!ENTITY GET '<command xmlns="http://docbook.org/ns/docbook">GET</command>'>
<!ENTITY PUT '<command xmlns="http://docbook.org/ns/docbook">PUT</command>'>
<!ENTITY POST '<command xmlns="http://docbook.org/ns/docbook">POST</command>'>
<!ENTITY DELETE '<command xmlns="http://docbook.org/ns/docbook">DELETE</command>'>
<!-- Information about the extension -->
<!ENTITY PUB_DATE "2011-12-21">
<!ENTITY ALIAS "HP-IDM">
<!ENTITY NAMESPACE "http://docs.openstack.org/identity/api/ext/HP-IDM/v1.0">
]>
<book xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:svg="http://www.w3.org/2000/svg"
xmlns:m="http://www.w3.org/1998/Math/MathML"
xmlns:html="http://www.w3.org/1999/xhtml"
xmlns:acme="http://docs.acme.org/servers/api/ext/template/v1.0"
xmlns:wadl="http://wadl.dev.java.net/2009/02"
xmlns:osapi="http://docs.openstack.org/compute/api/v1.1"
version="5.0" xml:id="example" status="DRAFT">
<title>OpenStack Identity HP-IDM Extension</title>
<titleabbrev>&ALIAS;</titleabbrev>
<info>
<author>
<personname>
<firstname/>
<surname/>
</personname>
<affiliation>
<orgname>HP</orgname>
</affiliation>
</author>
<copyright>
<year>2011</year>
<holder>Hewlett-Packard Development Company L.P.</holder>
</copyright>
<productname>OpenStack Identity</productname>
<pubdate>&PUB_DATE;</pubdate>
<legalnotice role="apache2">
<annotation>
<remark>Copyright details are filled in by the template.</remark>
</annotation>
</legalnotice>
<abstract>
<!--
Insert a short description of your template. This is used
in the copyright statement.
-->
<para>HP-IDM Extension For Token Validation.</para>
</abstract>
<!--
Revision history goes here. The docs system can turn this
into an atom feed.
-->
<revhistory>
<revision>
<date>2011-12-21</date>
<revdescription>
<itemizedlist spacing="compact">
<listitem>
<para>
Initial version.
</para>
</listitem>
</itemizedlist>
</revdescription>
</revision>
</revhistory>
</info>
<chapter xml:id="AboutExtension">
<title>About This Extension</title>
<variablelist spacing="compact">
<varlistentry>
<term>Name</term>
<listitem>
<para>HP-IDM Extension</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Namespace</term>
<listitem>
<para>&NAMESPACE;</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Alias</term>
<listitem>
<para>&ALIAS;</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Contact</term>
<listitem>
<para>
<personname>
<firstname>Guang</firstname>
<surname>Yee</surname>
</personname>
<email>guang.yee@hp.com</email>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Status</term>
<listitem>
<para>ALPHA</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Last Update</term>
<listitem>
<para>&PUB_DATE;</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Dependencies</term>
<listitem>
<para>Keystone API v2.0 (2011-12-21)</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Doc Link (PDF)</term>
<listitem>
<para>
<link xlink:href="https://github.com/openstack/keystone/raw/master/content/admin/HP-IDM-admin-devguide.pdf">
https://github.com/openstack/keystone/raw/master/content/admin/HP-IDM-admin-devguide.pdf
</link>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Doc Link (WADL)</term>
<listitem>
<para>
<link xlink:href="https://raw.github.com/openstack/keystone/master/keystone/content/admin/HP-IDM-admin.wadl">
https://raw.github.com/openstack/keystone/master/keystone/content/admin/HP-IDM-admin.wadl
</link>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Short Description</term>
<listitem>
<!--
A short description of the extension goes here.
This short descrption is aimed at devs.
-->
<para>
HP-IDM Admin Extension to Keystone V2.0 API adds capability
to filter roles with optional service IDs for token validation
to mitigate security risks with role name conflicts.
</para>
</listitem>
</varlistentry>
</variablelist>
<!--
This is how you do a page break in the PDF output. It's
optional.
-->
<?hard-pagebreak?>
<!--
The following examples should illustrate the extension query
response.
-->
<example>
<title>Sample Valid Token Request</title>
<programlisting language="xml"><xi:include href="samples/sample_request.txt" parse="text"/></programlisting>
</example>
<example>
<title>Sample Valid Token Request With Global Service ID Specified</title>
<programlisting language="xml"><xi:include href="samples/sample_request_with_global_sid.txt" parse="text"/></programlisting>
</example>
<example>
<title>Extension Query Response: XML</title>
<programlisting language="xml"><xi:include href="samples/ext_query.xml" parse="text"/></programlisting>
</example>
<example>
<title>Extension Query Response: JSON</title>
<programlisting language="javascript"><xi:include href="samples/ext_query.json" parse="text"/></programlisting>
</example>
<section>
<title>Document Change History</title>
<para>
The most recent changes to this document are described
below.
</para>
<!--
The rev history, described in the info element above,
should be output in this part of the document.
-->
<?rax revhistory?>
</section>
</chapter>
<chapter>
<title>Summary of Changes</title>
<!--
Provide an overall summary of the extension. Give an
overview of how the extensions works and what capabilities it
adds.
-->
<para>
HP-IDM Admin Extension to Keystone V2.0 API adds capability to filter roles
with optional service IDs for token validation to mitigate security risks
with role name conflicts.
See
<link xlink:href="https://bugs.launchpad.net/keystone/+bug/890411">
https://bugs.launchpad.net/keystone/+bug/890411
</link>
for more details.
</para>
<section>
<title>New Headers</title>
<!--
Describe any new headers, if any.
-->
<para>None.</para>
</section>
<section>
<title>New Faults</title>
<!--
Describe any new faults, if any. Make sure you specify
if the fault can be expectid in all requests.
-->
<para>None.</para>
</section>
<section role="api-reference">
<title>New Resources</title>
<!--
List any new resources here. The api-reference role
above means that a reference table of all new resources
will be placed here.
-->
<para>
No new resource. HP-IDM Extension merely introduced a new optional HP-IDM-serviceId parameter for the validate token operations. The following APIs are affected.
</para>
<section>
<title>Validate Tokens With The New Optional HP-IDM-serviceId Parameter</title>
<para>
The following are a list of operations on templates.
</para>
<!--
You can insert a WADL by referencing it from another
file. The WADL need not be normalized because you
can insert a normalization step in the build process
(see pom.xml).
-->
<wadl:resources>
<wadl:resource href="HP-IDM-admin.wadl#tokenById"/>
</wadl:resources>
</section>
</section>
<section>
<title>New Actions</title>
<!--
Describe any new actions if any.
-->
<para>None.</para>
</section>
<section>
<title>New States</title>
<!--
Describe any new states.
-->
<para>None.</para>
</section>
</chapter>
</book>

22
openstack-identity-api/src/docbkx/HP-IDM/samples/ext_query.json Normal file
View File

@ -0,0 +1,22 @@
{
"extension": {
"name": "HP Token Validation Extension",
"namespace": "http://docs.openstack.org/identity/api/ext/HP-IDM/v1.0",
"alias": "HP-IDM",
"updated": "2011-12-06T19:00:00-00:00",
"description": "Validate token with the optional HP-IDM-serviceId parameter so that only the roles associated with the given service IDs are returned. See https://bugs.launchpad.net/keystone/+bug/890411 for more details.",
"links": [
{
"rel": "describedby",
"type": "application/pdf",
"href": "https://github.com/openstack/keystone/raw/master/keystone/content/admin/HP-IDM-admin-devguide.pdf"
},
{
"rel": "describedby",
"type": "application/vnd.sun.wadl+xml",
"href": "https://raw.github.com/openstack/keystone/master/keystone/content/admin/HP-IDM-admin.wadl"
}
]
}
}

21
openstack-identity-api/src/docbkx/HP-IDM/samples/ext_query.xml Normal file
View File

@ -0,0 +1,21 @@
<?xml version="1.0" encoding="UTF-8"?>
<extension
xmlns="http://docs.openstack.org/common/api/v1.0"
xmlns:atom="http://www.w3.org/2005/Atom"
name="HP Token Validation Extension"
namespace="http://docs.openstack.org/identity/api/ext/HP-IDM/v1.0"
alias="HP-IDM"
updated="2011-12-06T17:00:00-00:00">
<description>
Validate token with the optional HP-IDM-serviceId parameter so that only the roles associated with the given service IDs are returned. See https://bugs.launchpad.net/keystone/+bug/890411 for more details.
</description>
<atom:link rel="describedby"
type="application/pdf"
href="https://github.com/openstack/keystone/raw/master/keystone/content/admin/HP-IDM-admin-devguide.pdf"/>
<atom:link rel="describedby"
type="application/vnd.sun.wadl+xml"
href="https://raw.github.com/openstack/keystone/master/keystone/content/admin/HP-IDM-admin.wadl"/>
</extension>

4
openstack-identity-api/src/docbkx/HP-IDM/samples/sample_request.txt Executable file
View File

@ -0,0 +1,4 @@
GET /v2.0/tokens/ab48a9efdfedb23ty3494?belongsTo=1&HP-IDM-serviceId=1,2 HTTP/1.1
X-Auth-Token: 999888777666
Host: identity.api.openstack.org
Accept: application/json

4
openstack-identity-api/src/docbkx/HP-IDM/samples/sample_request_with_global_sid.txt Executable file
View File

@ -0,0 +1,4 @@
GET /v2.0/tokens/ab48a9efdfedb23ty3494?belongsTo=1&HP-IDM-serviceId=1,2,global HTTP/1.1
X-Auth-Token: 999888777666
Host: identity.api.openstack.org
Accept: application/json