8287 token creation (quay#1188)

* Fixes syntax issue in Quay docs

* Updates API docs

---------

Co-authored-by: Steven Smith <[email protected]>

Author: stevsmit

api/master.adoc

@@ -22,11 +22,30 @@ The following guide describes the {productname} API in more detail, and provides
 * Using the {productname} API 
 * {productname} API configuration examples
 
-This guide is accompanied with a second guide, . . ., that provides information about all `api/v1` endpoints and how to access those endpoints with example commands.
+//This guide is accompanied with a second guide, . . ., that provides information about all `api/v1` endpoints and how to access those endpoints with example commands.
 
+//overview
 include::modules/token-overview.adoc[leveloffset=+1]
 
-include::modules/proc_use-api.adoc[leveloffset=+1]
+//creating oauth 2 access token
+include::modules/oauth2-access-tokens.adoc[leveloffset=+1]
+include::modules/creating-oauth-access-token.adoc[leveloffset=+2]
+include::modules/reassigning-oauth-access-token.adoc[leveloffset=+2]
+include::modules/deleting-oauth-access-token.adoc[leveloffset=+2]
+
+//robot account tokens
+include::modules/robot-account-tokens.adoc[leveloffset=+1]
+include::modules/regenerating-robot-account-token-ui.adoc[leveloffset=+2]
+include::modules/regenerating-robot-account-token-api.adoc[leveloffset=+2]
+
+//oci referrers
+include::modules/oci-referrers-oauth-access-token.adoc[leveloffset=+1]
+include::modules/creating-v2-oauth-access-token.adoc[leveloffset=+2]
+
+
+//include::modules/proc_use-api.adoc[leveloffset=+1]
+
+include::modules/creating-oauth-application-api.adoc[leveloffset=+1]
 
 == {productname} Application Programming Interface (API)
 [id="ref-api-quay"]

modules/creating-oauth-access-token.adoc

@@ -0,0 +1,51 @@
+:_content-type: PROCEDURE
+[id="creating-oauth-access-token"]
+= Creating an OAuth 2 access token
+
+With {productname}, you must create an OAuth 2 access token before you can access the API endpoints of your organization. OAuth 2 access token can only be generated by using the {productname} UI; the CLI cannot be used to generate an OAuth 2 access token. 
+
+Use the following procedure to create an OAuth2 access token. 
+
+.Prerequisites
+
+* You have logged in to {productname} as an administrator.
+* You have created an OAuth 2 application.
+
+.Procedure
+
+. On the main page, select an Organization.
+
+. In the navigation pane, select *Applications*. 
+
+. Click the name of your application, for example, *Test application*.
+
+. In the navigation pane, select *Generate Token*. 
+
+. Check the boxes for the following options:
+
+.. *Administer Organization*. When selected, allows the user to be able to administer organizations, including creating robots, creating teams, adjusting team membership, and changing billing settings.
+
+.. *Administer Repositories*. When selected, provides the user administrator access to all repositories to which the granting user has access.
+
+.. *Create Repositories*.  When selected, provides the user the ability to create repositories in any namespaces that the granting user is allowed to create repositories. 
+
+.. *View all visible repositories*. When selected, provides the user the ability to view and pull all repositories visible to the granting user.
+
+.. *Read/Write to any accessible repositories*.  When selected, provides the user the ability to view, push and pull to all repositories to which the granting user has write access.
+
+.. *Super User Access*.  When selected, provides the user the ability to administer your installation including managing users, managing organizations and other features found in the superuser panel. 
+
+.. *Administer User*  When selected, provides the user the ability to  administer your account including creating robots and granting them permissions to your repositories. 
+
+.. *Read User Information*.  When selected, provides the user the ability to read user information such as username and email address.
+
+. Click *Generate Access Token*. You are redirected to a new page.
+
+. Review the permissions that you are allowing, then click *Authorize Application*. Confirm your decision by clicking *Authorize Application*. 
+
+. You are redirected to the *Access Token* page. Copy and save the access token.
++
+[IMPORTANT]
+====
+This is the only opportunity to copy and save the access token. It cannot be reobtained after leaving this page. 
+====

modules/creating-oauth-application-api.adoc

@@ -0,0 +1,79 @@
+:_content-type: PROCEDURE
+[id="creating-oauth-application-api"]
+= Managing a user application by using the API
+
+{productname} users can create, list information about, and delete a _user application_ that can be used as an alternative to using your password for Docker, Podman, or other service providers. User application tokens work like your username and password, but are encrypted and do not provide any information to third parties regarding who is accessing {productname}.
+
+[NOTE]
+====
+After creation via the CLI, the user application token is listed under *User Settings* of the {productname} UI. Note that this differs from an application token that is created under user settings, and should be considered a different application entirely.
+====
+
+Use the following procedure to create a user application token.
+
+.Prerequisites
+
+* You have access to the {productname} API, which entails having already created an OAuth 2 access token.
+
+.Procedure
+
+* Create a user application by entering the link:https://docs.redhat.com/en/documentation/red_hat_quay/3.13/html-single/red_hat_quay_api_guide/index#appspecifictokens[`POST /api/v1/user/apptoken`] API call:
++
+[source,terminal]
+----
+$ curl -X POST \
+  -H "Authorization: Bearer <access_token>" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "title": "MyAppToken"
+  }' \
+  "http://quay-server.example.com/api/v1/user/apptoken"
+----
++
+.Example output
++
+[source,terminal]
+----
+{"token": {"uuid": "6b5aa827-cee5-4fbe-a434-4b7b8a245ca7", "title": "MyAppToken", "last_accessed": null, "created": "Wed, 08 Jan 2025 19:32:48 -0000", "expiration": null, "token_code": "K2YQB1YO0ABYV5OBUYOMF9MCUABN12Y608Q9RHFXBI8K7IE8TYCI4WEEXSVH1AXWKZCKGUVA57PSA8N48PWED9F27PXATFUVUD9QDNCE9GOT9Q8ACYPIN0HL"}}
+----
+
+* You can obtain information about your application, including when the application expires, by using the link:https://docs.redhat.com/en/documentation/red_hat_quay/3.13/html-single/red_hat_quay_api_guide/index#listapptokens[`GET /api/v1/user/apptoken`] command. For example:
++
+[source,terminal]
+----
+$ curl -X GET \
+  -H "Authorization: Bearer <access_token>" \
+  "http://quay-server.example.com/api/v1/user/apptoken"
+----
++
+[source,terminal]
+----
+{"tokens": [{"uuid": "6b5aa827-cee5-4fbe-a434-4b7b8a245ca7", "title": "MyAppToken", "last_accessed": null, "created": "Wed, 08 Jan 2025 19:32:48 -0000", "expiration": null}], "only_expiring": null}
+----
+
+* You can obtain information about a specific user application by entering the link:https://docs.redhat.com/en/documentation/red_hat_quay/3.13/html-single/red_hat_quay_api_guide/index#getapptoken[`GET /api/v1/user/apptoken/{token_uuid}`] command:
++
+[source,terminal]
+----
+$ curl -X GET \
+  -H "Authorization: Bearer <access_token>" \
+  "http://quay-server.example.com/api/v1/user/apptoken/<token_uuid>"
+----
++
+.Example output
++
+[source,terminal]
+----
+{"token": {"uuid": "6b5aa827-cee5-4fbe-a434-4b7b8a245ca7", "title": "MyAppToken", "last_accessed": null, "created": "Wed, 08 Jan 2025 19:32:48 -0000", "expiration": null, "token_code": "K2YQB1YO0ABYV5OBUYOMF9MCUABN12Y608Q9RHFXBI8K7IE8TYCI4WEEXSVH1AXWKZCKGUVA57PSA8N48PWED9F27PXATFUVUD9QDNCE9GOT9Q8ACYPIN0HL"}}
+----
+
+* You can delete a user application token by entering the 
++
+[source,terminal]
+----
+$ curl -X DELETE \
+  -H "Authorization: Bearer <access_token>" \
+  "http://quay-server.example.com/api/v1/user/apptoken/<token_uuid>"
+----
++
+This command does not return output in the CLI. You can return a list of tokens by entering one of the aforementioned commands.

modules/creating-oauth-application.adoc

@@ -0,0 +1,34 @@
+:_content-type: PROCEDURE
+[id="creating-oauth-application"]
+= Creating an OAuth 2 application by using the UI
+
+{productname} administrators can define an application by specifying a unique name, a homepage URL, a description of the application's uses, an e-mail, or a redirect/callback URL. 
+
+[NOTE]
+====
+The following application token is created under an Organization. This differs from an application token that is created under user settings, and should be considered a different application entirely.
+====
+
+Use the following procedure to create an OAuth2 application. 
+
+.Prerequisites
+
+* You have logged in to {productname} as an administrator. 
+
+.Procedure
+
+. On the main page, select an Organization.
+
+. In the navigation pane, select *Applications*. 
+
+. Click *Create New Application* and provide a new application name, then press *Enter*. 
+
+. On the *OAuth Applications* page, select the name of your application.
+
+. Optional. Enter the following information:
+
+.. *Application Name*
+.. *Homepage URL*
+.. *Description*
+.. *Avatar E-mail*
+.. *Redirect/Callback URL prefix*

modules/creating-v2-oauth-access-token.adoc

@@ -0,0 +1,46 @@
+:_content-type: PROCEDURE
+[id="creating-v2-oauth-access-token"]
+= Creating an OCI referrers OAuth access token
+
+This OCI referrers OAuth access token is used to list OCI referrers of a manifest under a repository.
+
+.Procedure
+
+. Update your `config.yaml` file to include the `FEATURE_REFERRERS_API: true` field. For example:
++
+[source,yaml]
+----
+# ...
+FEATURE_REFERRERS_API: true
+# ...
+----
+
+. Enter the following command to Base64 encode your credentials:
++
+[source,terminal]
+----
+$ echo -n '<username>:<password>' | base64
+----
++
+.Example output
++
+[source,terminal]
+----
+abcdeWFkbWluOjE5ODlraWROZXQxIQ==
+----
+
+. Enter the following command to use the base64 encoded string and modify the URL endpoint to your {productname} server:
++
+[source,terminal]
+----
+$ curl --location '<quay-server.example.com>/v2/auth?service=<quay-server.example.com>&scope=repository:quay/listocireferrs:pull,push' --header 'Authorization: Basic <base64_username:password_encode_token>' -k | jq
+----
++
+.Example output
++
+[source,terminal]
+----
+{
+  "token": "<example_secret>
+}
+----

modules/deleting-oauth-access-token.adoc

@@ -0,0 +1,22 @@
+:_content-type: PROCEDURE
+[id="deleting-oauth-access-token"]
+= Deleting an OAuth 2 access token
+
+Because OAuth 2 access tokens are created through the OAuth application, they cannot be rotated or renewed. In the event that a token is compromised, or you need to delete a token, you must deleted its associated application through the {productname} UI. 
+
+[IMPORTANT]
+====
+Deleting an application deletes all tokens that were made within that specific application. Use with caution.
+====
+
+.Prerequisites
+
+* You have created an OAuth 2 access token.
+
+.Procedure
+
+. On the {productname} UI, click the name of the organization hosting the application. Then, in the navigation pane, click *Applications*.
+
+. Click the application name, for example, *Test application*.
+
+. In the navigation pane, click *Delete Application*. You are redirected to a new page. Click *Delete application* and confirm your decision.

modules/keyless-authentication-robot-accounts.adoc

@@ -4,7 +4,7 @@
 
 In previous versions of {productname}, robot account tokens were valid for the lifetime of the token unless deleted or regenerated. Tokens that do not expire have security implications for users who do not want to store long-term passwords or manage the deletion, or regeneration, or new authentication tokens. 
 
-With {productname} {producty}, {productname} administrators are provided the ability to exchange external OIDC token for short-lived, or _ephemeral_ robot account tokens with either Red Hat Single Sign-On (based on the Keycloak project) or Microsoft Entra ID. This allows robot accounts to leverage tokens that last one hour, which are are refreshed regularly and can be used to authenticate individual transactions. 
+With {productname} {producty}, {productname} administrators are provided the ability to exchange external OIDC tokens for short-lived, or _ephemeral_ robot account tokens with either Red Hat Single Sign-On (based on the Keycloak project) or Microsoft Entra ID. This allows robot accounts to leverage tokens that last one hour, which are are refreshed regularly and can be used to authenticate individual transactions. 
 
 This feature greatly enhances the security of your {productname} registry by mitigating the possibility of robot token exposure by removing the tokens after one hour.
 

modules/oauth2-access-tokens.adoc

@@ -0,0 +1,43 @@
+:_content-type: REFERENCE
+[id="oauth2-access-tokens"]
+= OAuth 2 access tokens 
+
+link:https://oauth.net/2/[OAuth 2] access tokens (considered "API tokens" for {productname}) enable user-authenticated access to the {productname} API, suitable for applications that require user identity verification. These tokens are obtained through an OAuth 2 authorization process, where a {productname} administrator generates a token on behalf of themselves or another user to access {productname} API endpoints. OAuth 2 tokens authorize actions on API endpoints based on the scopes defined for the token. 
+
+[NOTE]
+====
+Although OAuth 2 tokens authorize actions on API endpoints based on the scopes defined for the token, access to the resources themselves is governed by {productname}'s role-based access control (RBAC) mechanisms. Actions can be created on a resource, for example, a repository, provided that you have the proper role (*Admin* or *Creator*) to do so for that namespace. This is true even if the API token was granted the `repo:admin` scope.
+====
+
+OAuth 2 access tokens can only be created by using the {productname} UI; there is no way to create an OAuth 2 access token by using the CLI. When creating an OAuth 2 token, the following options can be selected for a token holder:
+
+* *Administer Organization*. When selected, allows the user to be able to administer organizations, including creating robots, creating teams, adjusting team membership, and changing billing settings.
+
+* *Administer Repositories*. When selected, provides the user administrator access to all repositories to which the granting user has access.
+
+* *Create Repositories*.  When selected, provides the user the ability to create repositories in any namespaces that the granting user is allowed to create repositories. 
+
+* *View all visible repositories*. When selected, provides the user the ability to view and pull all repositories visible to the granting user.
+
+* *Read/Write to any accessible repositories*.  When selected, provides the user the ability to view, push and pull to all repositories to which the granting user has write access.
+
+* *Super User Access*.  When selected, provides the user the ability to administer your installation including managing users, managing organizations and other features found in the superuser panel. 
+
+* *Administer User*  When selected, provides the user the ability to  administer your account including creating robots and granting them permissions to your repositories. 
+
+* *Read User Information*.  When selected, provides the user the ability to read user information such as username and email address.
+
+Token distributors should be mindful of the permissions that they are granting when generating a token on behalf of a user, and should have absolute trust in a user before granting such permissions as *Administer organization*, *Super User Access*, and *Administer User*. Additionally, the access token is only revealed at the time of creation; they cannot be listed from the CLI, nor can they be found on the {productname} UI. If an access token is lost or forgotten, a new token must be created; a token cannot be recovered.
+
+OAuth 2 access tokens are passed as a `Bearer` token in the `Authorization` header of an API call and, as a result, are used to provide authentication and authorization to the defined API endpoint, such as an image tag, a repository, an organization, and so on.
+
+The API is available from the `/api/v1` endpoint of your {productname} host. For example, `\https://<quay-server.example.com>/api/v1`. It allows users to connect to endpoints through their browser to `GET`, `POST`, `DELETE`, and `PUT` {productname} settings by enabling the Swagger UI. The API can be accessed by applications that make API calls and use OAuth tokens, and it sends and receives data as JSON. 
+
+With {productname}, there is currently no way to rotate or to set an expiration time on an OAuth 2 access token, and the token lifespan is 10 years. Tokens can be deleted by deleting the applications in which they were created in the event that they are compromised, however, this deletes all tokens that were made within that specific application.
+
+[NOTE]
+====
+In practice, {productname} administrators _could_ create a new OAuth application on the *Applications* page of their organization each time they wanted to create a new OAuth token for a user. This would ensure that a single application is not responsible for all OAuth tokens. As a result, in the event that a user's token is compromised, the administrator would delete the application of the compromised token. This would help avoid disruption for other users whose tokens might be part of the same application. 
+====
+
+The following sections shows you how to generate and reassign an OAuth 2 access token.

modules/oci-referrers-oauth-access-token.adoc

@@ -0,0 +1,14 @@
+:_content-type: REFERENCE
+[id="oci-referrers-oauth-access-token"]
+= OCI referrers OAuth access token
+
+In some cases, depending on the features that your {productname} deployment is configured to use, you might need to leverage an _OCI referrers OAuth access token_. OCI referrers OAuth access tokens are used to list OCI referrers of a manifest under a repository, and uses a `curl` command to make a `GET` request to the {productname} `v2/auth` endpoint.
+
+These tokens are obtained via basic HTTP authentication, wherein the user provides a username and password encoded in Base64 to authenticate directly with the `v2/auth` API endpoint. As such, they are based directly on the user's credentials aod do not follow the same detailed authorization flow as OAuth 2, but still allow a user to authorize API requests.
+
+_OCI referrers OAuth access tokens_ do not offer scope-based permissions and do not expire. They are solely used to list OCI referrers of a manifest under a repository.
+
+[discrete]
+== Additional resource
+
+* link:https://docs.redhat.com/en/documentation/red_hat_quay/3.13/html-single/use_red_hat_quay/index#attaching-referrers-image-tag[Attaching referrers to an image tag]