diff --git a/doc/source/admin/configure-https.rst b/doc/source/admin/configure-https.rst
new file mode 100644
index 0000000000..a1d704f5b3
--- /dev/null
+++ b/doc/source/admin/configure-https.rst
@@ -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
+
+ 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
+
+
+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
\ No newline at end of file
diff --git a/doc/source/admin/index.rst b/doc/source/admin/index.rst
index 4784ac7146..5746ba0a5a 100644
--- a/doc/source/admin/index.rst
+++ b/doc/source/admin/index.rst
@@ -19,3 +19,4 @@ operators to help with administering a keystone deployment.
keystone-features
authentication-mechanisms
oauth2-usage-guide
+ configure-https
diff --git a/doc/source/admin/oauth2-usage-guide.rst b/doc/source/admin/oauth2-usage-guide.rst
index c677ab6a52..14a2b8f521 100644
--- a/doc/source/admin/oauth2-usage-guide.rst
+++ b/doc/source/admin/oauth2-usage-guide.rst
@@ -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
-
- 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
-
-
-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
\ No newline at end of file