This is an automated email from the ASF dual-hosted git repository.
lmccay pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/knox.git
The following commit(s) were added to refs/heads/master by this push:
new 134f85652 KNOX-3157 - Add the documentation for APIKEY and CLIENTID
APIs to the new knox-site (#1054)
134f85652 is described below
commit 134f8565207d197cc5e94a0049af97c336007bd3
Author: lmccay <[email protected]>
AuthorDate: Tue Jun 10 19:05:01 2025 -0400
KNOX-3157 - Add the documentation for APIKEY and CLIENTID APIs to the new
knox-site (#1054)
---
knox-site/docs/config_apikey.md | 63 +++++++++++++++++++++++++++++
knox-site/docs/config_client_credentials.md | 61 ++++++++++++++++++++++++++++
knox-site/docs/config_knox_token.md | 18 ---------
knox-site/docs/index.md | 2 +
knox-site/mkdocs.yml | 34 +++++++++-------
5 files changed, 145 insertions(+), 33 deletions(-)
diff --git a/knox-site/docs/config_apikey.md b/knox-site/docs/config_apikey.md
new file mode 100644
index 000000000..36ef4bbfc
--- /dev/null
+++ b/knox-site/docs/config_apikey.md
@@ -0,0 +1,63 @@
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You 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
+
+ https://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.
+-->
+# API Key API
+
+### Introduction
+The APIKEY API is an extension of the KnoxToken API that defaults certain
configuration and translates the responses in
+a way that supports the specific API Key use cases. This API is used to issue
API Keys for use with services like AI
+Inferencing APIs such as OpenAI compatible APIs where an Authorization Bearer
Token is expected and it is not a JWT with
+expectations around expiry and cryptographic verification of the credentials.
+
+The only difference from the KnoxToken API in the configuration are the
parameter names. They must be prefixed with
+"apikey." this is done to disambiguate the config from that of KnoxToken
itself when they are colocated in the same
+topology.
+
+In addition, the default behavior differs in that the time-to-live or TTL
defaults to "-1" which means that by default
+the API Keys do not expire. It also differs in that the returned APIKeys are
Passcode tokens and as such are by definition
+server managed. Therefore, we default the server managed configuration to true
for convenience and to reduce errors in
+deployment.
+
+**API Key** - The example below shows the interaction with the APIKey API via
curl and the response with default behavior.
+
+ <service>
+ <role>APIKEY</role>
+ </service>
+
+In this deployment example the TTL is -1 by default which means it never
expires and is not included in the response.
+
+ $ curl -ivku guest:guest-password -X POST
"https://localhost:8443/gateway/sandbox/apikey/api/v1/auth/key";
+
{"key_id":"9c2d22fb-e28d-4495-aaae-d4103dada8d1","api_key":"T1dNeVpESXlabUl0WlRJNFpDMDBORGsxTFdGaFlX....R1F4OjpNMlV5WXpFeE56a3RZbVJtTXkwME1HTTJMVGxoTmpVdE9HWXdNbUZrTTJWa016UXo="}
+
+**API Key** - The example below shows the interaction with the APIKey API via
curl and the response.
+
+In this deployment example the TTL is set to 74000 ms which is translated to
seconds in the response.
+
+ <service>
+ <role>APIKEY</role>
+ <param>
+ <name>apikey.knox.token.ttl</name>
+ <value>74000</value>
+ </param>
+ </service>
+
+ $ curl -ivku guest:guest-password -X POST
"https://localhost:8443/gateway/sandbox/apikey/api/v1/auth/key";
+
{"key_id":"9c2d22fb-e28d-4495-aaae-d4103dada8d1","api_key":"T1dNeVpESXlabUl0WlRJNFpDMDBORGsxTFdGaFlX....R1F4OjpNMlV5WXpFeE56a3RZbVJtTXkwME1HTTJMVGxoTmpVdE9HWXdNbUZrTTJWa016UXo=","expires_in":74}
+
+Note that in both of the above response that there is a key_id as well as the
api_key. The api_key is intended to be used
+as the API Key via Authorization Bearer Token in the invocations of APIs.
+
+The key_id may be used in management operations of the API Key lifecycle by
those with appropriate permissions to do so.
diff --git a/knox-site/docs/config_client_credentials.md
b/knox-site/docs/config_client_credentials.md
new file mode 100644
index 000000000..989b46822
--- /dev/null
+++ b/knox-site/docs/config_client_credentials.md
@@ -0,0 +1,61 @@
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You 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
+
+ https://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.
+-->
+
+# Client Credentials API
+
+### Introduction
+The CLIENTID API is an extension of the KnoxToken API that defaults certain
configuration and translates the responses in
+a way that supports the specific OAuth Client Credentials Flow use cases. This
API is used to issue API Keys for use with
+services like the Iceberg REST Catalog API.
+
+The only difference from the KnoxToken API in the configuration are the
parameter names. They must be prefixed with
+"clientid." this is done to disambiguate the config from that of KnoxToken
itself when they are colocated in the same
+topology.
+
+In addition, the default behavior differs in that the time-to-live or TTL
defaults to "-1" which means that by default
+the API Keys do not expire. It also differs in that the returned APIKeys are
Passcode tokens and as such are by definition
+server managed. Therefore, we default the server managed configuration to true
for convenience and to reduce errors in
+deployment.
+
+**Client Credentials** - The example below shows the interaction with the
APIKey API via curl and the response with default behavior.
+
+ <service>
+ <role>CLIENTID</role>
+ </service>
+
+In this deployment example the TTL is -1 by default which means it never
expires and is not included in the response.
+
+ $ curl -ivku guest:guest-password -X POST
"https://localhost:8443/gateway/sandbox/clientid/api/v1/oauth/credentials";
+
{"client_secret":"WXpOa1l6SmxPRFF0TmpOalpTMDBPREZpTFRobE5qY3RO....jpOems1T1RabU5qSXROREl4T1MwMFlUVTBMV0UyWlRVdFptTXlNek0xTjJWaVl6SXg=","client_id":"c3dc2e84-63ce-481b-8e67-75f754894f87"}
+
+**Client Credentials** - The example below shows the interaction with the
APIKey API via curl and the response.
+
+In this deployment example the TTL is set to 74000 ms which is translated to
seconds in the response.
+
+ <service>
+ <role>CLIENTID</role>
+ <param>
+ <name>clientid.knox.token.ttl</name>
+ <value>74000</value>
+ </param>
+ </service>
+
+ $ curl -ivku guest:guest-password -X POST
"https://localhost:8443/gateway/sandbox/clientid/api/v1/oauth/credentials";
+
{"client_secret":"WXpKaE1qRmlOR0V0TkRBMk5DMDBNelZsTFdFek16RXR....WTVaVFprOjpZelJsTlRJMFlXVXROMlEwTXkwME5EQTVMV0k1WWpJdFlqZ3pOR00xTmpsa01qUXg=","expires_in":74,"client_id":"c2a21b4a-4064-435e-a331-6d6858ef9e6d"}
+
+Note that in both of the above responses that there is a client_id and the
client_secret.
+The key_id may be used in management operations of the API Key lifecycle by
those with appropriate permissions to do so.
\ No newline at end of file
diff --git a/knox-site/docs/config_knox_token.md
b/knox-site/docs/config_knox_token.md
index b7403b429..107cf1ee2 100644
--- a/knox-site/docs/config_knox_token.md
+++ b/knox-site/docs/config_knox_token.md
@@ -14,22 +14,6 @@
See the License for the specific language governing permissions and
limitations under the License.
-->
-<!---
- Licensed to the Apache Software Foundation (ASF) under one or more
- contributor license agreements. See the NOTICE file distributed with
- this work for additional information regarding copyright ownership.
- The ASF licenses this file to You 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
-
- https://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.
--->
## KnoxToken Configuration
### Introduction
@@ -603,5 +587,3 @@ The following table shows the returned token(s) in case
metadata filtering is ad
|md_Uknown=*|Empty list|
You may want to check out [GitHub Pull Request
#542](https://github.com/apache/knox/pull/542) for sample `curl` commands.
-
-
diff --git a/knox-site/docs/index.md b/knox-site/docs/index.md
index ab8008609..2740bf841 100644
--- a/knox-site/docs/index.md
+++ b/knox-site/docs/index.md
@@ -33,6 +33,8 @@
<img src="static/images/knox-logo.gif" alt="Knox" style="width:100%;"/>
+# ***DRAFT - WORK IN PROGRESS***
+
# Apache Knox Documentation Home
## Contributing to Apache Knox Documentation
diff --git a/knox-site/mkdocs.yml b/knox-site/mkdocs.yml
index a983fd8ff..bf319a71e 100644
--- a/knox-site/mkdocs.yml
+++ b/knox-site/mkdocs.yml
@@ -49,39 +49,43 @@ nav:
- Quick Start: quick_start.md
- Client/User Guide:
- Knox Shell: knoxshell-guide/knoxshell_user_guide.md
- - Knox CLI: knox_cli.md
- Discovering Resources: book_client-details.md
- Troubleshooting:
- General Troubleshooting: book_troubleshooting.md
- Client-Specific Troubleshooting: client_troubleshooting.md
- FAQ: faq.md
- Admin Guide:
+ - Knox CLI: knox_cli.md
- Gateway Overview: book_gateway-details.md
- Configuration:
- - Overview: config.md
- - Authentication:
+ - Gateway Config Overview: config.md
+ - Knox Security Config: config_kerberos.md
+ - High Availability: config_ha.md
+ - Mutual Auth SSL: config_mutual_authentication_ssl.md
+ - Metrics: config_metrics.md
+ - Audit: config_audit.md
+ - Authentication Services:
+ - Providers:
- Overview: config_authn.md
- - Kerberos: config_kerberos.md
- - LDAP Authentication Cache: config_ldap_authc_cache.md
- - LDAP Group Lookup: config_ldap_group_lookup.md
- - Advanced LDAP: config_advanced_ldap.md
+ - LDAP:
+ - LDAP Group Lookup: config_ldap_group_lookup.md
+ - Advanced LDAP: config_advanced_ldap.md
+ - LDAP Authentication Cache: config_ldap_authc_cache.md
- PAM Authentication: config_pam_authn.md
- - Knox SSO: config_knox_sso.md
- - Knox Token: config_knox_token.md
- Pre-auth SSO: config_preauth_sso_provider.md
- SSO Cookie: config_sso_cookie_provider.md
- TLS Client Certificate:
config_tls_client_certificate_authentication_provider.md
- PAC4J: config_pac4j_provider.md
- Hadoop Auth: config_hadoop_auth_provider.md
+ - Services/APIs:
+ - Knox SSO: config_knox_sso.md
+ - API Key: config_apikey.md
+ - Client Credentials: config_client_credentials.md
+ - Knox Auth Service: config_knoxauth_service.md
+ - Knox Token: config_knox_token.md
- Authorization: config_authz.md
- Identity Assertion: config_id_assertion.md
- - High Availability: config_ha.md
- - Knox Auth Service: config_knoxauth_service.md
- - Mutual Auth SSL: config_mutual_authentication_ssl.md
- Web App Security: config_webappsec_provider.md
- - Metrics: config_metrics.md
- - Audit: config_audit.md
- - Sandbox: config_sandbox.md
- Service-Specific Configurations:
- Overview: service_config.md
- Default HA: service_default_ha.md
