summaryrefslogtreecommitdiffstats
path: root/keystone-moon/doc/source/auth-totp.rst
diff options
context:
space:
mode:
Diffstat (limited to 'keystone-moon/doc/source/auth-totp.rst')
-rw-r--r--keystone-moon/doc/source/auth-totp.rst136
1 files changed, 136 insertions, 0 deletions
diff --git a/keystone-moon/doc/source/auth-totp.rst b/keystone-moon/doc/source/auth-totp.rst
new file mode 100644
index 00000000..4e81757f
--- /dev/null
+++ b/keystone-moon/doc/source/auth-totp.rst
@@ -0,0 +1,136 @@
+..
+ Licensed under the Apache License, Version 2.0 (the "License"); you may
+ not use this file except in compliance with the License. You may obtain
+ a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+ License for the specific language governing permissions and limitations
+ under the License.
+
+===================================
+Time-based One-time Password (TOTP)
+===================================
+
+Configuring TOTP
+================
+
+TOTP is not enabled in Keystone by default. To enable it add the ``totp``
+authentication method to the ``[auth]`` section in ``keystone.conf``:
+
+.. code-block:: ini
+
+ [auth]
+ methods = external,password,token,oauth1,totp
+
+For a user to have access to TOTP, he must have configured TOTP credentials in
+Keystone and a TOTP device (i.e. `Google Authenticator`_).
+
+.. _Google Authenticator: http://www.google.com/2step
+
+TOTP uses a base32 encoded string for the secret. The secret must be at least
+148 bits (16 bytes). The following python code can be used to generate a TOTP
+secret:
+
+.. code-block:: python
+
+ import base64
+ message = '1234567890123456'
+ print base64.b32encode(message).rstrip('=')
+
+Example output::
+
+ GEZDGNBVGY3TQOJQGEZDGNBVGY
+
+This generated secret can then be used to add new 'totp' credentials to a
+specific user.
+
+Create a TOTP credential
+------------------------
+
+Create ``totp`` credentials for user:
+
+.. code-block:: bash
+
+ USER_ID=b7793000f8d84c79af4e215e9da78654
+ SECRET=GEZDGNBVGY3TQOJQGEZDGNBVGY
+
+ curl -i \
+ -H "Content-Type: application/json" \
+ -d '
+ {
+ "credential": {
+ "blob": "'$SECRET'",
+ "type": "totp",
+ "user_id": "'$USER_ID'"
+ }
+ }' \
+ http://localhost:5000/v3/credentials ; echo
+
+Google Authenticator
+--------------------
+
+On a device install Google Authenticator and inside the app click on 'Set up
+account' and then click on 'Enter provided key'. In the input fields enter
+account name and secret. Optionally a QR code can be generated programatically
+to avoid having to type the information.
+
+QR code
+-------
+
+Create TOTP QR code for device:
+
+.. code-block:: python
+
+ import qrcode
+
+ secret='GEZDGNBVGY3TQOJQGEZDGNBVGY'
+ uri = 'otpauth://totp/{name}?secret={secret}&issuer={issuer}'.format(
+ name='name',
+ secret=secret,
+ issuer='Keystone')
+
+ img = qrcode.make(uri)
+ img.save('totp.png')
+
+In Google Authenticator app click on 'Set up account' and then click on 'Scan
+a barcode', and then scan the 'totp.png' image. This should create a new TOTP
+entry in the application.
+
+Authenticate with TOTP
+======================
+
+Google Authenticator will generate a 6 digit PIN (passcode) every few seconds.
+Use the passcode and your user ID to authenticate using the ``totp`` method.
+
+Tokens
+------
+
+Get a token with default scope (may be unscoped) using totp:
+
+.. code-block:: bash
+
+ USER_ID=b7793000f8d84c79af4e215e9da78654
+ PASSCODE=012345
+
+ curl -i \
+ -H "Content-Type: application/json" \
+ -d '
+ { "auth": {
+ "identity": {
+ "methods": [
+ "totp"
+ ],
+ "totp": {
+ "user": {
+ "id": "'$USER_ID'",
+ "passcode": "'$PASSCODE'"
+ }
+ }
+ }
+ }
+ }' \
+ http://localhost:5000/v3/auth/tokens ; echo