openstack/keystone
Code Issues Proposed changes

Fix presentation of OAuth2.0 user guides

Browse Source 
Applied remining comments to the first OAuth2.0 documentation patch [1].

[1] https://review.opendev.org/c/openstack/keystone/+/838108

Change-Id: I95aac0b4ac4e887b79ef5b15ac5cb3d356c26735
This commit is contained in:
Hiromu Asahina 2023-06-27 23:55:18 +09:00
parent b438bf1efe
commit f6ab28218e
3 changed files with 122 additions and 160 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

90
doc/source/admin/configure-https.rst Normal file
View File

@ -0,0 +1,90 @@
Configure HTTPS in Identity Service
-----------------------------------
The following part describes steps to enable both HTTP and HTTPS with a
self-signed certificate.
1. Generate an RSA private key.
.. code-block:: console
stack@oauth2-0-server:/$ openssl genrsa -out keystone.key 2048
Generating RSA private key, 2048 bit long modulus (2 primes)
.........................................+++++
.........................+++++
e is 65537 (0x010001)
2. Create a certificate signing request.
.. code-block:: console
stack@oauth2-0-server:/$ openssl req -new -key keystone.key -out keystone.csr
You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) [AU]:
State or Province Name (full name) [Some-State]:
Locality Name (eg, city) []:
Organization Name (eg, company) [Internet Widgits Pty Ltd]:
Organizational Unit Name (eg, section) []:
Common Name (e.g. server FQDN or YOUR name) []:keystone.host
Email Address []:
Please enter the following 'extra' attributes
to be sent with your certificate request
A challenge password []:
An optional company name []:
3. Generate a self-signed certificate.
.. code-block:: console
stack@oauth2-0-server:/$ openssl x509 -req -days 365 -in keystone.csr \
-signkey keystone.key -out keystone.host.crt
Signature ok
subject=C = , ST = , L = , O = , OU = , CN = keystone.host, emailAddress =
Getting Private key
4. Append the configuration file for setting the HTTPS port service under the
directory ``/etc/apache2/sites-enabled/``.
.. code-block:: console
stack@oauth2-0-server:/$ sudo ln -s \
/etc/apache2/sites-available/000-default.conf \
/etc/apache2/sites-enabled/000-default.conf
5. Modify the apache configuration file and add proxy rules to implement HTTPS
support for the Keystone service.
.. code-block:: console
stack@oauth2-0-server:/$ vi 000-default.conf
<VirtualHost *:443>
DocumentRoot /var/www/html
SSLCertificateFile /etc/ssl/certs/keystone.host.crt
SSLCertificateKeyFile /etc/ssl/certs/keystone.key
SSLEngine on
SSLProtocol all -SSLv2 -SSLv3
SSLCipherSuite ECDH:AESGCM:HIGH:!RC4:!DH:!MD5:!aNULL:!eNULL
SSLHonorCipherOrder on
ProxyPass "/identity" "unix:/var/run/uwsgi/keystone-wsgi-public.socket|uwsgi://uwsgi-uds-keystone-wsgi-public" retry=0
</VirtualHost>
6. Restart apache service so that the modified configuration information takes
effect.
.. code-block:: console
stack@oauth2-0-server:/$ systemctl restart apache2.service
==== AUTHENTICATING FOR org.freedesktop.systemd1.manage-units ===
Authentication is required to restart 'apache2.service'.
Authenticating as: Ubuntu (ubuntu)
Password:
==== AUTHENTICATION COMPLETE ===
.. _RFC6749: https://datatracker.ietf.org/doc/html/rfc6749

1
doc/source/admin/index.rst
View File

@ -19,3 +19,4 @@ operators to help with administering a keystone deployment.
keystone-features
authentication-mechanisms
oauth2-usage-guide
configure-https

191
doc/source/admin/oauth2-usage-guide.rst
View File

@ -7,12 +7,12 @@ Overview
OAuth2.0 Client Credentials Grant based on `RFC6749`_ is implemented as an
extension of Keystone. This extension uses the `application credentials`_ as
its back-end because they have some similar features. Users can use
``application_credentials_id`` and ``application_credentials_secret`` as
client credentials to obtain the OAuth2.0 access token. The access token can
then be used to access the protected resources of the OpenStack API, which
uses Keystone middleware supporting the OAuth2.0 Client Credentials Grant.
See the `Identity API reference`_ for more information on generating OAuth2.0
access token.
``application_credentials_id`` and ``application_credentials_secret`` as client
credentials to obtain the OAuth2.0 access token. The access token can then be
used to access the protected resources of the OpenStack API using
Keystonemiddleware that supports receiving access tokens in the Authorization
header. See the `Identity API reference`_ for more information on generating
OAuth2.0 access token.
Guide
~~~~~
@ -23,104 +23,15 @@ Grant by the following steps in this guide. In this example,
.. _application credentials: https://docs.openstack.org/api-ref/identity/v3/index.html#application-credentials
.. _`Identity API reference`: https://docs.openstack.org/api-ref/identity/v3/index.html#os-oauth2-api
Enable Keystone HTTPS Service
---------------------------------
The following part describes steps to enable both HTTP and HTTPS with a
self-signed certificate.
.. warning::
.. warning::
It is strongly recommended that HTTPS be enabled in Keystone when using
OAuth2.0 Client Credentials. See :doc:`./configure-https` for details.
According to `RFC6749`_ , HTTPS **must** be enabled in the authorization
server since requests include sensitive information, e.g., a client secret,
in plain text. Note that you might have to enable both HTTP and HTTPS as
some other OpenStack services or third-party applications don't use
OAuth2.0 and need HTTP for the authentication with the Keystone identity
server.
1. Generate an RSA private key.
.. code-block:: console
stack@oauth2-0-server:/$ openssl genrsa -out keystone.key 2048
Generating RSA private key, 2048 bit long modulus (2 primes)
.........................................+++++
.........................+++++
e is 65537 (0x010001)
2. Create a certificate signing request.
.. code-block:: console
stack@oauth2-0-server:/$ openssl req -new -key keystone.key -out keystone.csr
You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) [AU]:
State or Province Name (full name) [Some-State]:
Locality Name (eg, city) []:
Organization Name (eg, company) [Internet Widgits Pty Ltd]:
Organizational Unit Name (eg, section) []:
Common Name (e.g. server FQDN or YOUR name) []:keystone.host
Email Address []:
Please enter the following 'extra' attributes
to be sent with your certificate request
A challenge password []:
An optional company name []:
3. Generate a self-signed certificate.
.. code-block:: console
stack@oauth2-0-server:/$ openssl x509 -req -days 365 -in keystone.csr \
-signkey keystone.key -out keystone.host.crt
Signature ok
subject=C = , ST = , L = , O = , OU = , CN = keystone.host, emailAddress =
Getting Private key
4. Append the configuration file for setting the HTTPS port service under the
directory ``/etc/apache2/sites-enabled/``.
.. code-block:: console
stack@oauth2-0-server:/$ sudo ln -s \
/etc/apache2/sites-available/000-default.conf \
/etc/apache2/sites-enabled/000-default.conf
5. Modify the apache configuration file and add proxy rules to implement HTTPS
support for the Keystone service.
.. code-block:: console
stack@oauth2-0-server:/$ vi 000-default.conf
<VirtualHost *:443>
DocumentRoot /var/www/html
SSLCertificateFile /etc/ssl/certs/keystone.host.crt
SSLCertificateKeyFile /etc/ssl/certs/keystone.key
SSLEngine on
SSLProtocol all -SSLv2 -SSLv3
SSLCipherSuite ECDH:AESGCM:HIGH:!RC4:!DH:!MD5:!aNULL:!eNULL
SSLHonorCipherOrder on
ProxyPass "/identity" "unix:/var/run/uwsgi/keystone-wsgi-public.socket|uwsgi://uwsgi-uds-keystone-wsgi-public" retry=0
</VirtualHost>
6. Restart apache service so that the modified configuration information takes
effect.
.. code-block:: console
stack@oauth2-0-server:/$ systemctl restart apache2.service
==== AUTHENTICATING FOR org.freedesktop.systemd1.manage-units ===
Authentication is required to restart 'apache2.service'.
Authenticating as: Ubuntu (ubuntu)
Password:
==== AUTHENTICATION COMPLETE ===
.. _RFC6749: https://datatracker.ietf.org/doc/html/rfc6749
some other OpenStack services or third-party applications don't use OAuth2.0
and need HTTP for the authentication with the Keystone identity server.
Enable application credentials authentication
---------------------------------------------
@ -148,74 +59,32 @@ Try to access the Keystone APIs
At last, try to access the Keystone APIs to confirm that the server is working
properly.
1. Through the HTTP protocol, access the Keystone token API to confirm that the
X-Auth-Token can be obtained normally.
1. Create OAuth2.0 client credentials through the application credentials API.
.. code-block:: console
stack@oauth2-0-server:/$ curl -si -X POST http://keystone.host/identity/v3/auth/tokens?nocatalog \
-d '{"auth":{"identity":{"methods":["password"],"password": {"user":{"domain":{"name":"Default"},"name":"username","password":"test_pwd"}}},"scope":{"project":{"domain":{"name":"Default"},"name":"admin"}}}}' \
-H 'Content-type:application/json'
stack@oauth2-0-server:/$ openstack application credential create sample_001
+--------------+----------------------------------------------------------------------------------------+
| Field | Value |
+--------------+----------------------------------------------------------------------------------------+
| description | None |
| expires_at | None |
| id | a7850381222a4e2cb595664dfd57d083 |
| name | sample_001 |
| project_id | 2b90a96668694041a640a2ef84be6de7 |
| roles | admin reader member |
| secret | GVm33KC6AqpDZj_ZzKhZClDqnCpNDMNh66Mvait8Dxw7Kc8kwVj7ImkwnRWvovs437f2aftbW46wEMtH0cyBQA |
| system | None |
| unrestricted | False |
| user_id | 0b8426bb83d944bc8d0fe4c3b9a3f635 |
+--------------+----------------------------------------------------------------------------------------+
HTTP/1.1 201 CREATED
Date: Mon, 28 Feb 2022 08:50:31 GMT
Server: Apache/2.4.41 (Ubuntu)
Content-Type: application/json
Content-Length: 648
X-Subject-Token: $x_auth_token
Vary: X-Auth-Token
x-openstack-request-id: req-e84d2387-10c7-4bb9-942e-61190e9186d9
Connection: close
{"token": {"methods": ["password"], "user": {"domain": {"id": "default", "name": "Default"}, "id": "eb98b8bbb2174aa5acd6cf57b0bf64c6", "name": "admin", "password_expires_at": null}, "audit_ids": ["RkU3ZQXuR7uKF2tEwgtkYg"], "expires_at": "2022-02-28T09:50:31.000000Z", "issued_at": "2022-02-28T08:50:31.000000Z", "project": {"domain": {"id": "default", "name": "Default"}, "id": "83808bea957a4ce1aa612aef63b24d1c", "name": "admin"}, "is_domain": false, "roles": [{"id": "c30201abb78848a6919f582d0cd74f84", "name": "admin"}, {"id": "459dcf48c6794731b700fc6aa1cad669", "name": "member"}, {"id": "54ee344bb009472c8223d4d76d9b1246", "name": "reader"}]}}
2. Through the HTTPS protocol, access the Keystone token API to confirm that the
X-Auth-Token can be obtained normally.
.. code-block:: console
stack@oauth2-0-server:/$ curl -sik -X POST https://keystone.host/identity/v3/auth/tokens?nocatalog \
-d '{"auth":{"identity":{"methods":["password"],"password": {"user":{"domain":{"name":"Default"},"name":"username","password":"test_pwd"}}},"scope":{"project":{"domain":{"name":"Default"},"name":"admin"}}}}' \
-H 'Content-type:application/json'
HTTP/1.1 201 CREATED
Date: Tue, 01 Mar 2022 00:38:48 GMT
Server: Apache/2.4.41 (Ubuntu)
Content-Type: application/json
Content-Length: 648
X-Subject-Token: $x_auth_token
Vary: X-Auth-Token
x-openstack-request-id: req-324f20e2-16d6-4f26-aefc-e2913b76e36f
Connection: close
{"token": {"methods": ["password"], "user": {"domain": {"id": "default", "name": "Default"}, "id": "eb98b8bbb2174aa5acd6cf57b0bf64c6", "name": "admin", "password_expires_at": null}, "audit_ids": ["XFEM4-V4QQiA9v3JVLUeWw"], "expires_at": "2022-03-01T01:38:48.000000Z", "issued_at": "2022-03-01T00:38:48.000000Z", "project": {"domain": {"id": "default", "name": "Default"}, "id": "83808bea957a4ce1aa612aef63b24d1c", "name": "admin"}, "is_domain": false, "roles": [{"id": "c30201abb78848a6919f582d0cd74f84", "name": "admin"}, {"id": "459dcf48c6794731b700fc6aa1cad669", "name": "member"}, {"id": "54ee344bb009472c8223d4d76d9b1246", "name": "reader"}]}}
3. Create OAuth2.0 client credentials through the application credentials API.
.. code-block:: console
stack@oauth2-0-server:/$ curl -sik -X POST https://keystone.host/identity/v3/users/eb98b8bbb2174aa5acd6cf57b0bf64c6/application_credentials \
-H "X-Auth-Token: $x_auth_token" \
-H "Content-Type: application/json" \
-d '{"application_credential": {"name": "sample_001"}}'
HTTP/1.1 201 CREATED
Date: Tue, 01 Mar 2022 00:55:25 GMT
Server: Apache/2.4.41 (Ubuntu)
Content-Type: application/json
Content-Length: 890
Vary: X-Auth-Token
x-openstack-request-id: req-e73ffa83-78df-4663-bccc-dd3ac582417f
Connection: close
{"application_credential": {"id": "$oauth2_client_id", "name": "sample_001", "description": null, "user_id": "eb98b8bbb2174aa5acd6cf57b0bf64c6", "project_id": "83808bea957a4ce1aa612aef63b24d1c", "system": null, "expires_at": null, "unrestricted": null, "roles": [{"id": "c30201abb78848a6919f582d0cd74f84", "name": "admin", "domain_id": null, "description": null, "options": {"immutable": true}}, {"id": "459dcf48c6794731b700fc6aa1cad669", "name": "member", "domain_id": null, "description": null, "options": {"immutable": true}}, {"id": "54ee344bb009472c8223d4d76d9b1246", "name": "reader", "domain_id": null, "description": null, "options": {"immutable": true}}], "secret": "$auth2_client_secret", "links": {"self": "https://keystone.host/identity/v3/application_credentials/f96a2fec117141a6b5fbaa0485632244"}}}
4. Obtain oauth2.0 access tokens through the "Basic" HTTP authentication with
2. Obtain oauth2.0 access tokens through the "Basic" HTTP authentication with
OAuth2.0 client credentials.
.. code-block:: console
stack@oauth2-0-server:/$ curl -sik -u "$oauth2_client_id:$oauth2_client_secret" \
stack@oauth2-0-server:/$ curl -sik -u "$a7850381222a4e2cb595664dfd57d083:GVm33KC6AqpDZj_ZzKhZClDqnCpNDMNh66Mvait8Dxw7Kc8kwVj7ImkwnRWvovs437f2aftbW46wEMtH0cyBQA" \
-X POST https://keystone.host/identity/v3/OS-OAUTH2/token
-H "application/x-www-form-urlencoded" -d "grant_type=client_credentials"
HTTP/1.1 200 OK
@ -229,3 +98,5 @@ properly.
{"access_token":"gAAAAABhi1cMynG89h8t6TJrxNiZuNzjcIUIxNctoVfuqTw7BpUedLKxjPymClVEnj9GhIT5u2mpjaJATlEAtaa3D6_t8jk_fV-mqo2IUlsmTPTnMwkcjh5FSHQVRdqvDxgY3nSqLA_Hfv-zPmjS5KWX3hmyDE5YWO1ztX6QNVQb4wTPyNL1-7I","expires_in":3600,"token_type":"Bearer"}
.. _RFC6749: https://datatracker.ietf.org/doc/html/rfc6749