From 8b5c524ad3292c2dbfe2643b40b47a9262786a57 Mon Sep 17 00:00:00 2001
From: Alexander Makarov <amakarov@mirantis.com>
Date: Fri, 4 Mar 2016 22:22:35 +0300
Subject: [PATCH] Examples for kerberos and saml2 plugins

Provide examples on authentication using extras plugins:
 - kerberos
 - saml2
 - adfs

Implements bp documentation

Change-Id: I18d11a98e056546f1a101001e1665e2968e75c65
---
 doc/source/extras.rst | 51 ++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 50 insertions(+), 1 deletion(-)

diff --git a/doc/source/extras.rst b/doc/source/extras.rst
index 0c6ef853..53229e2e 100644
--- a/doc/source/extras.rst
+++ b/doc/source/extras.rst
@@ -17,8 +17,57 @@ dependencies you must install the additional dependencies like::
 By convention (not a requirement) extra plugins have a module located in the
 keystoneauth1.extras module with the same name as the dependency. eg::
 
-    $ from keystoneauth1.extras import kerberos
+    from keystoneauth1.extras import kerberos
 
 There is no keystoneauth specific check that the correct dependencies are
 installed for accessing a module. You would expect to see standard python
 ImportError when the required dependencies are not found.
+
+Examples
+========
+
+All extras plugins follow the pattern:
+
+1. import plugin module
+2. instantiate the plugin
+3. call get_token method of the plugin passing it a session object
+   to get a token
+
+Kerberos
+--------
+
+Get domain-scoped token using
+:py:class:`~keystoneauth1.extras.kerberos.Kerberos`::
+
+    from keystoneauth1.extras import kerberos
+    from keystoneauth1 import session
+
+    plugin = kerberos.Kerberos('http://example.com:5000/v3')
+    sess = session.Session(plugin)
+    token = plugin.get_token(sess)
+
+Get unscoped federated token::
+
+    from keystoneauth1.extras import kerberos
+    from keystoneauth1 import session
+
+    plugin = kerberos.MappedKerberos(
+        auth_url='http://example.com:5000/v3', protocol='example_protocol',
+        identity_provider='example_identity_provider')
+
+    sess = session.Session()
+    token = plugin.get_token(sess)
+
+Get project scoped federated token::
+
+    from keystoneauth1.extras import kerberos
+    from keystoneauth1 import session
+
+    plugin = kerberos.MappedKerberos(
+        auth_url='http://example.com:5000/v3', protocol='example_protocol',
+        identity_provider='example_identity_provider',
+        project_id='example_project_id')
+
+    sess = session.Session()
+    token = plugin.get_token(sess)
+    project_id = plugin.get_project_id(sess)