Add doc of OAuth2.0 Client Credentials Grant Flow

This patch provides Keystone documents for OAuth2.0 client authorization. The specification about new API is added to API Reference. Also OAuth2.0 client credentials grant flow is added to admin guide. Implement: blueprint oauth2-client-credentials-ext Change-Id: I6ac5835fb64a4e81f34f7b8631d255b2bb7f66da
2022-04-15 09:56:20 +00:00 · 2022-04-15 09:56:20 +00:00 · b438bf1efe
commit b438bf1efe
parent c141e6164e
7 changed files with 378 additions and 1 deletions
--- a/api-ref/source/v3-ext/index.rst
+++ b/api-ref/source/v3-ext/index.rst
@ -22,6 +22,7 @@ This page describes these Identity API v3 extensions:

 * `OS-ENDPOINT-POLICY API`_
 * `OS-OAUTH1 API`_
+* `OS-OAUTH2 API`_
 * `OS-TRUST API`_
 * `OS-REVOKE API`_
 * `OS-EP-FILTER API`_
@ -32,6 +33,7 @@ This page describes these Identity API v3 extensions:

 .. include:: endpoint-policy.inc
 .. include:: oauth.inc
+.. include:: oauth2.inc
 .. include:: trust.inc
 .. include:: revoke.inc
 .. include:: ep-filter.inc
--- a/api-ref/source/v3-ext/oauth2.inc
+++ b/api-ref/source/v3-ext/oauth2.inc
@ -0,0 +1,111 @@
+.. -*- rst -*-
+
+===============
+ OS-OAUTH2 API
+===============
+
+Provide the ability for identity users to delegate roles to third party
+consumers via the `OAuth 2.0 Client Credentials grant specification
+<https://oauth.net/2/grant-types/client-credentials/>`__.
+Requires v3.0+ of the Identity API. An OAuth2-derived access token will
+provide a means of acting on behalf of the authorizing user.
+
+Overview
+========
+
+Definitions
+-----------
+
+- *User:* The end-users who use Identity API service, the entity whose role(s)
+  will be delegated, and the entity that registers Clients.
+
+- *Client:* An application making protected resource requests on behalf of the
+  User. The credentials of the client are created though the Application
+  Credentials API.
+
+- *Access Token:* A token used by the Client to make protected resource
+  requests with the delegated roles.
+
+Delegated Authentication Flow
+-----------------------------
+
+Delegated Authentication via OAuth 2.0 is done in four steps:
+
+#. An Identity API service User creates an `application credential`_.
+
+#. The Client authenticates with the authorization server on the Keystone and
+   requests a new Access Token.
+
+#. The Client uses the Access Token to make requests for OpenStack Service
+   APIs.
+
+#. Keystone Middleware validates the Access Token in an API request to obtain
+   its metadata and validity, and forwards the request to the OpenStack service
+   if the token is active.
+
+.. _application credential: https://docs.openstack.org/api-ref/identity/v3/index.html?expanded=create-application-credential-detail#create-application-credential
+
+Create Access Token
+===================
+
+.. rest_method::  POST /identity/v3/OS-OAUTH2/token
+
+Enables a user to create an access token.
+The user makes a request to the token endpoint by adding the following
+parameters using the "application/x-www-form-urlencoded" format with
+a character encoding of UTF-8 in the HTTP request entity-body. And the
+request should use the basic authentication header which contains the
+application credentials information to authenticate a user through the
+authorization server.
+
+Relationship: ``https://docs.openstack.org/api/openstack-identity/3/ext/OS-OAUTH2/1.0/rel/token``
+
+Request
+-------
+
+Parameters
+~~~~~~~~~~
+
+.. rest_parameters:: parameters.yaml
+
+    - grant_type: request_token_grant_type_body_required
+
+Example
+~~~~~~~
+
+.. literalinclude:: ./samples/OS-OAUTH2/token-create-request.txt
+   :language: javascript
+
+Response
+--------
+
+Parameters
+~~~~~~~~~~
+
+.. rest_parameters:: parameters.yaml
+
+    - access_token: response_token_access_token_body
+    - token_type: response_token_token_type_body
+    - expires_in: response_token_expires_in_body
+
+Status Codes
+~~~~~~~~~~~~
+
+.. rest_status_code:: success ../v3/status.yaml
+
+   - 200
+
+.. rest_status_code:: error ../v3/status.yaml
+
+   - 400
+   - 401
+   - 404
+   - 500
+
+Status: 200 OK
+
+Example
+~~~~~~~
+
+.. literalinclude:: ./samples/OS-OAUTH2/token-create-response.json
+   :language: javascript
--- a/api-ref/source/v3-ext/parameters.yaml
+++ b/api-ref/source/v3-ext/parameters.yaml
@ -351,6 +351,33 @@ remaining_uses:
  in: body
  required: false
  type: boolean
+request_token_grant_type_body_required:
+  description: |
+    Value MUST be set to "client_credentials".
+  in: body
+  required: true
+  type: string
+response_token_access_token_body:
+  description: |
+    The authentication token issued by the authorization server.
+  in: body
+  required: true
+  type: string
+response_token_expires_in_body:
+  description: |
+    The lifetime in seconds of the access token.  For example, the value "3600"
+    denotes that the access token will expire in one hour from the time the
+    response was generated.
+  in: body
+  required: true
+  type: integer
+response_token_token_type_body:
+  description: |
+    The type of the token issued by the authorization server. Currently only the
+    "Bearer" token type is supported.
+  in: body
+  required: true
+  type: string
 revoke_audit_chain_id:
  description: |
    Specifies a group of tokens based upon the ``audit_id`` of the
@ -553,4 +580,3 @@ url:
  in: body
  required: true
  type: string
-
--- a/api-ref/source/v3-ext/samples/OS-OAUTH2/token-create-request.txt
+++ b/api-ref/source/v3-ext/samples/OS-OAUTH2/token-create-request.txt
@ -0,0 +1 @@
+grant_type=client_credentials
--- a/api-ref/source/v3-ext/samples/OS-OAUTH2/token-create-response.json
+++ b/api-ref/source/v3-ext/samples/OS-OAUTH2/token-create-response.json
@ -0,0 +1,5 @@
+{
+    "access_token": "gAAAAABhi1cMynG89h8t6TJrxNiZuNzjcIUIxNctoVfuqTw7BpUedLKxjPymClVEnj9GhIT5u2mpjaJATlEAtaa3D6_t8jk_fV-mqo2IUlsmTPTnMwkcjh5FSHQVRdqvDxgY3nSqLA_Hfv-zPmjS5KWX3hmyDE5YWO1ztX6QNVQb4wTPyNL1-7I",
+    "token_type": "Bearer",
+    "expires_in": 3600
+}
--- a/doc/source/admin/index.rst
+++ b/doc/source/admin/index.rst
@ -18,3 +18,4 @@ operators to help with administering a keystone deployment.
   service-api-protection
   keystone-features
   authentication-mechanisms
+   oauth2-usage-guide
--- a/doc/source/admin/oauth2-usage-guide.rst
+++ b/doc/source/admin/oauth2-usage-guide.rst
@ -0,0 +1,231 @@
+======================================
+OAuth2.0 Client Credentials Grant Flow
+======================================
+
+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.
+
+Guide
+~~~~~
+Enable Keystone identity server to support OAuth2.0 Client Credentials
+Grant by the following steps in this guide. In this example,
+``keystone.host`` is the domain name used by the Keystone identity server.
+
+.. _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::
+
+   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
+
+Enable application credentials authentication
+---------------------------------------------
+Due to the design of the current implementation, the application credentials
+must be enabled in Keystone as it is used for the management of OAuth2.0
+client credentials.
+
+1. Modify ``keystone.conf`` to support application credentials authentication.
+
+.. code-block:: console
+
+    stack@oauth2-0-server:/$ vi /etc/keystone/keystone.conf
+    [auth]
+    methods = external,password,token,application_credential
+
+2. Restart Keystone service so that the modified configuration information takes
+   effect.
+
+.. code-block:: console
+
+    stack@oauth2-0-server:/$ sudo systemctl restart devstack@keystone.service
+
+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.
+
+.. 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'
+
+    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
+   OAuth2.0 client credentials.
+
+.. code-block:: console
+
+    stack@oauth2-0-server:/$ curl -sik -u "$oauth2_client_id:$oauth2_client_secret" \
+    -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
+    Date: Tue, 01 Mar 2022 00:56:59 GMT
+    Server: Apache/2.4.41 (Ubuntu)
+    Content-Type: application/json
+    Content-Length: 264
+    Vary: X-Auth-Token
+    x-openstack-request-id: req-a8358f51-2e0f-45a7-bb1e-7d29c6a793f4
+    Connection: close
+
+    {"access_token":"gAAAAABhi1cMynG89h8t6TJrxNiZuNzjcIUIxNctoVfuqTw7BpUedLKxjPymClVEnj9GhIT5u2mpjaJATlEAtaa3D6_t8jk_fV-mqo2IUlsmTPTnMwkcjh5FSHQVRdqvDxgY3nSqLA_Hfv-zPmjS5KWX3hmyDE5YWO1ztX6QNVQb4wTPyNL1-7I","expires_in":3600,"token_type":"Bearer"}
+