From f781e89a692a2d4fa4d279ff6012fe45abd4d708 Mon Sep 17 00:00:00 2001 From: Noopur Parikh Date: Wed, 17 Jun 2026 11:38:05 -0700 Subject: [PATCH 1/6] feat: Add client credentials guide for NGINXaaS Google --- .../security-controls/client-credentials.md | 193 ++++++++++++++++++ 1 file changed, 193 insertions(+) create mode 100644 content/nginxaas-google/quickstart/security-controls/client-credentials.md diff --git a/content/nginxaas-google/quickstart/security-controls/client-credentials.md b/content/nginxaas-google/quickstart/security-controls/client-credentials.md new file mode 100644 index 0000000000..6893bfb8b9 --- /dev/null +++ b/content/nginxaas-google/quickstart/security-controls/client-credentials.md @@ -0,0 +1,193 @@ +--- +title: "Programmatic Authentication With Client Credentials" +description: "Learn how to set up OAuth2 client credentials for programmatic access to the NGINXaaS API." +weight: 100 +toc: true +url: /nginxaas/google/quickstart/security-controls/client-credentials/ +f5-product: NGOOGL +f5-content-type: how-to +f5-keywords: "client credentials, OAuth2, programmatic authentication, API" +--- + +## Overview + +This guide explains how to create and use client credentials to manage some NGINXaaS for Google Cloud APIs programmatically. This allows machine users such as Terraform, CI/CD pipelines, or other automation tools to authenticate and interact with the NGINXaaS API securely. + +Client credentials are scoped to an organization and enable programmatic access to manage Deployments, Configurations, and Certificates APIs. + +## Key features + +- **Secure programmatic access**: Enables programmatic access for machine clients with tokens minted using client credentials +- **Configurable Expiration controls**: Configurable expiration with recommended best practices +- **Limited scope**: Client credentials can only manage Deployments, Configs, and Certificates + +## Prerequisites + +- You must be logged into NGINXaaS Console [https://console.nginxaas.net/](https://console.nginxaas.net/) + +## Creating client credentials + +Follow these steps to create a new client credential through the NGINXaaS console: + +1. Log in to [NGINXaaS Console](https://console.nginxaas.net/) using your Google credentials. +2. Select **Settings** > **Client Credentials** from the left navigation menu. +3. Select **+ Add Client** to create a new credential. +4. Enter a unique name for your client in the text field that appears. +5. Choose an expiration date (maximum 1 year from today; 6 months is recommended). This setting is immutable after creation. +6. Select **Create**. A popup window displays your client secret. + +{{< call-out class="warning" title="Important: Store Your Client Secret Securely" >}} +The client secret appears only once. Save it immediately in a secure location, such as a password manager or secrets vault. If you lose the secret, you must delete this credential and create a new one. +{{< /call-out >}} + +Your client credentials can access the following APIs programmatically: + +- Certificates API +- Configs API +- Deployments API + +### Client limits + +Organizations are limited to a maximum of 10 client credentials. To request an increase to this limit, contact the NGINX Support team. + +## Retrieving client information + +Follow these steps to view your client credentials: + +1. Log in to [NGINXaaS Console](https://console.nginxaas.net/). +2. Select **Settings** > **Client Credentials** from the left navigation menu. +3. The **Client Credentials** page displays all available client credentials for your organization. The table shows the following metadata for each credential: + - Client Name + - Client ID + - Token Endpoint + - Date Created + - Expires On + +4. Check the expiration status indicator next to **Expires On**: + - **Green dot**: Credential is active and valid + - **Red dot**: Credential has expired + +{{< call-out class="note" >}} +Client secrets are not displayed after creation. If you need to use credentials again, you must have saved the secret when you initially created the client. +{{< /call-out >}} + +## Deleting client credentials + +Follow these steps to delete a client credential: + +1. Log in to [NGINXaaS Console](https://console.nginxaas.net/). +2. Select **Settings** > **Client Credentials** from the left navigation menu. +3. Locate the credential to delete in the table. +4. Select the three vertical dots icon (⋮) at the end of the row. +5. Select **Delete** from the menu. + +After deletion: + +- The client can no longer request new access tokens using this credential +- Existing access tokens continue to work until they expire (1 hour from issuance) +- The client ID and secret become permanently invalid + +{{< call-out class="note" >}} +Expired credentials are not automatically removed. You must manually delete credentials that are past their expiration date. +{{< /call-out >}} + +## Using client credentials for authentication + +### Exchange credentials for an access token + +Use the client credentials to obtain an access token from the token endpoint. + +**Endpoint**: `POST https://us.api.nginxaas.net/api/v1/marketplace/auth/token` + +**Example using cURL**: + +```bash +curl -X POST "https://us.api.nginxaas.net/api/v1/marketplace/auth/token" \ + -H "Content-Type: application/json" \ + -d '{ + "client_id": "client_abc123", + "client_secret": "superSecret", + "grant_type": "client_credentials" + }' +``` + +**Response**: + +```json +{ + "access_token": "", + "token_type": "Bearer", + "expires_in": 3600 +} +``` + +### Use the access token + +Include the access token in the Authorization header when making API requests. + +**Example**: + +```bash +curl -X GET "https://us.api.nginxaas.net/api/v1/deployments" \ + -H "Authorization: Bearer " +``` + +### Access token validity + +- **Duration**: Access tokens are valid for 1 hour from issuance +- **Reauthentication**: When a token expires, request a new one using the same client credentials, if the client credentials are still active +- **Scope**: Tokens are also scoped to the organization associated with the client credentials + +## Security best practices + +- **Use separate credentials for different environments**: Create distinct clients for various scopes to keep things logically separate +- **Store secrets securely**: Never commit client secrets to version control +- **Delete unused credentials**: Remove clients that are no longer needed +- **Follow the recommended expiration**: Unless you have a specific reason, use the recommended 6-month expiration + +## Error handling + +### Invalid or expired credentials + +If you attempt to authenticate with invalid or expired credentials, you will receive a `401 Unauthorized` response. In this case: + +- Verify your client ID and secret are correct +- Check if the client has expired +- Create new credentials if necessary + +**Example error response**: + +```json +{ + "error": "unauthorized", + "error_description": "token is expired/invalid" +} +``` + +### Forbidden APIs + +Client credentials can only access the Certificates, Configs, and Deployments APIs. Attempting to access any other API with client credentials returns a `403 Forbidden` response. In this case: + +- Verify you are using the correct API endpoint +- Ensure the API is one of the supported resources (Deployments, Configs, or Certificates) + +**Example error response**: + +```json +{ + "error": "forbidden", + "error_description": "Client credentials do not have permission to access this resource" +} +``` + +## Quick reference + +| Property | Value | +|----------|-------| +| Client secret visibility | Only shown once during creation | +| Default expiration | 6 months (recommended) | +| Maximum expiration | 1 year | +| Client limit per organization | 10 clients (contact NGINX Support to increase) | +| Access token validity | 1 hour | +| Supported resources | Deployments, Configs, Certificates | +| Token endpoint | `https://{region}.api.nginxaas.net/api/v1/marketplace/auth/token` | \ No newline at end of file From ac2739488c5f3c6dc4ec44ac58166053e8045569 Mon Sep 17 00:00:00 2001 From: Noopur Parikh Date: Wed, 17 Jun 2026 16:03:19 -0700 Subject: [PATCH 2/6] Apply suggestions from code review --- .../quickstart/security-controls/_index.md | 2 +- .../security-controls/client-credentials.md | 54 ++++++++++--------- 2 files changed, 31 insertions(+), 25 deletions(-) diff --git a/content/nginxaas-google/quickstart/security-controls/_index.md b/content/nginxaas-google/quickstart/security-controls/_index.md index 8353987b56..1e961cd455 100644 --- a/content/nginxaas-google/quickstart/security-controls/_index.md +++ b/content/nginxaas-google/quickstart/security-controls/_index.md @@ -1,6 +1,6 @@ --- title: Security controls weight: 500 -url: /nginxaas/google/quicksart/security-controls/ +url: /nginxaas/google/quickstart/security-controls/ toc: true --- diff --git a/content/nginxaas-google/quickstart/security-controls/client-credentials.md b/content/nginxaas-google/quickstart/security-controls/client-credentials.md index 6893bfb8b9..70adc9777d 100644 --- a/content/nginxaas-google/quickstart/security-controls/client-credentials.md +++ b/content/nginxaas-google/quickstart/security-controls/client-credentials.md @@ -1,5 +1,5 @@ --- -title: "Programmatic Authentication With Client Credentials" +title: "Programmatic authentication with client credentials" description: "Learn how to set up OAuth2 client credentials for programmatic access to the NGINXaaS API." weight: 100 toc: true @@ -7,25 +7,28 @@ url: /nginxaas/google/quickstart/security-controls/client-credentials/ f5-product: NGOOGL f5-content-type: how-to f5-keywords: "client credentials, OAuth2, programmatic authentication, API" +f5-summary: > + Use this guide to create OAuth2 client credentials in the NGINXaaS Console and exchange + them for an access token that authenticates requests to the NGINXaaS API. + Client credentials enable access for automation toolchains such as CI/CD pipelines, + allowing you to manage Deployments, Configurations, and Certificates APIs. + Credentials are scoped to a single organization. +f5-audience: operator --- ## Overview -This guide explains how to create and use client credentials to manage some NGINXaaS for Google Cloud APIs programmatically. This allows machine users such as Terraform, CI/CD pipelines, or other automation tools to authenticate and interact with the NGINXaaS API securely. +This guide explains how to create and use client credentials for automating access to NGINXaaS APIs. Client credentials enable automation tools such as CI/CD pipelines to manage your deployments, configurations, and certificates without requiring user login. -Client credentials are scoped to an organization and enable programmatic access to manage Deployments, Configurations, and Certificates APIs. +To authenticate, you exchange your client credentials (client ID and secret) for a short-lived access token from the NGINXaaS token endpoint. This access token is then used in the Authorization header of your API requests. Access tokens have limited validity, after which you'll need to request a new one using the same credentials. -## Key features +Client credentials are scoped to an organization and expire after a set period (up to 1 year, 6 months recommended). -- **Secure programmatic access**: Enables programmatic access for machine clients with tokens minted using client credentials -- **Configurable Expiration controls**: Configurable expiration with recommended best practices -- **Limited scope**: Client credentials can only manage Deployments, Configs, and Certificates +## Before you begin -## Prerequisites +- You must be logged in to the [NGINXaaS Console](https://console.nginxaas.net/). -- You must be logged into NGINXaaS Console [https://console.nginxaas.net/](https://console.nginxaas.net/) - -## Creating client credentials +## Create client credentials Follow these steps to create a new client credential through the NGINXaaS console: @@ -40,7 +43,7 @@ Follow these steps to create a new client credential through the NGINXaaS consol The client secret appears only once. Save it immediately in a secure location, such as a password manager or secrets vault. If you lose the secret, you must delete this credential and create a new one. {{< /call-out >}} -Your client credentials can access the following APIs programmatically: +Your client credentials can access the following APIs: - Certificates API - Configs API @@ -50,13 +53,13 @@ Your client credentials can access the following APIs programmatically: Organizations are limited to a maximum of 10 client credentials. To request an increase to this limit, contact the NGINX Support team. -## Retrieving client information +## Retrieve client information Follow these steps to view your client credentials: 1. Log in to [NGINXaaS Console](https://console.nginxaas.net/). 2. Select **Settings** > **Client Credentials** from the left navigation menu. -3. The **Client Credentials** page displays all available client credentials for your organization. The table shows the following metadata for each credential: +3. You can see all the available client credentials for your organization in the **Client Credentials** page. The table shows the following metadata for each credential: - Client Name - Client ID - Token Endpoint @@ -97,16 +100,16 @@ Expired credentials are not automatically removed. You must manually delete cred Use the client credentials to obtain an access token from the token endpoint. -**Endpoint**: `POST https://us.api.nginxaas.net/api/v1/marketplace/auth/token` +**Endpoint**: `POST https://.api.nginxaas.net/api/v1/marketplace/auth/token` **Example using cURL**: ```bash -curl -X POST "https://us.api.nginxaas.net/api/v1/marketplace/auth/token" \ +curl -X POST "https://.api.nginxaas.net/api/v1/marketplace/auth/token" \ -H "Content-Type: application/json" \ -d '{ - "client_id": "client_abc123", - "client_secret": "superSecret", + "client_id": "", + "client_secret": "", "grant_type": "client_credentials" }' ``` @@ -115,7 +118,7 @@ curl -X POST "https://us.api.nginxaas.net/api/v1/marketplace/auth/token" \ ```json { - "access_token": "", + "access_token": "", "token_type": "Bearer", "expires_in": 3600 } @@ -128,8 +131,8 @@ Include the access token in the Authorization header when making API requests. **Example**: ```bash -curl -X GET "https://us.api.nginxaas.net/api/v1/deployments" \ - -H "Authorization: Bearer " +curl -X GET "https://.api.nginxaas.net/api/v1/deployments" \ + -H "Authorization: Bearer " ``` ### Access token validity @@ -140,12 +143,12 @@ curl -X GET "https://us.api.nginxaas.net/api/v1/deployments" \ ## Security best practices -- **Use separate credentials for different environments**: Create distinct clients for various scopes to keep things logically separate +- **Use separate credentials for different environments**: Create distinct clients for various scopes to keep environments logically separate - **Store secrets securely**: Never commit client secrets to version control - **Delete unused credentials**: Remove clients that are no longer needed - **Follow the recommended expiration**: Unless you have a specific reason, use the recommended 6-month expiration -## Error handling +## Troubleshooting ### Invalid or expired credentials @@ -190,4 +193,7 @@ Client credentials can only access the Certificates, Configs, and Deployments AP | Client limit per organization | 10 clients (contact NGINX Support to increase) | | Access token validity | 1 hour | | Supported resources | Deployments, Configs, Certificates | -| Token endpoint | `https://{region}.api.nginxaas.net/api/v1/marketplace/auth/token` | \ No newline at end of file +| Token endpoint | `https://.api.nginxaas.net/api/v1/marketplace/auth/token` | + +## References + From 0556ad3e6113c1e7c292abcbd6b6a021a4148691 Mon Sep 17 00:00:00 2001 From: Noopur Parikh Date: Wed, 17 Jun 2026 16:27:10 -0700 Subject: [PATCH 3/6] add reference section at the end --- .../quickstart/security-controls/client-credentials.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/content/nginxaas-google/quickstart/security-controls/client-credentials.md b/content/nginxaas-google/quickstart/security-controls/client-credentials.md index 70adc9777d..871bb5df43 100644 --- a/content/nginxaas-google/quickstart/security-controls/client-credentials.md +++ b/content/nginxaas-google/quickstart/security-controls/client-credentials.md @@ -195,5 +195,8 @@ Client credentials can only access the Certificates, Configs, and Deployments AP | Supported resources | Deployments, Configs, Certificates | | Token endpoint | `https://.api.nginxaas.net/api/v1/marketplace/auth/token` | -## References +## What's next +[Manage your NGINXaaS deployments]({{< ref "/nginxaas-google/getting-started/create-deployment/deploy-console.md" >}}) + +[Manage your NGINX configurations]({{< ref "/nginxaas-google/getting-started/nginx-configuration/nginx-configuration-console.md" >}}) \ No newline at end of file From c50ac2062554eac28e8c9f2ba7fe0e3b25f3da65 Mon Sep 17 00:00:00 2001 From: Noopur Parikh Date: Sat, 20 Jun 2026 15:19:35 -0700 Subject: [PATCH 4/6] cleanup content in security best practices --- .../security-controls/client-credentials.md | 29 +++++++++---------- 1 file changed, 13 insertions(+), 16 deletions(-) diff --git a/content/nginxaas-google/quickstart/security-controls/client-credentials.md b/content/nginxaas-google/quickstart/security-controls/client-credentials.md index 871bb5df43..28aa4226ea 100644 --- a/content/nginxaas-google/quickstart/security-controls/client-credentials.md +++ b/content/nginxaas-google/quickstart/security-controls/client-credentials.md @@ -32,15 +32,16 @@ Client credentials are scoped to an organization and expire after a set period ( Follow these steps to create a new client credential through the NGINXaaS console: -1. Log in to [NGINXaaS Console](https://console.nginxaas.net/) using your Google credentials. -2. Select **Settings** > **Client Credentials** from the left navigation menu. -3. Select **+ Add Client** to create a new credential. -4. Enter a unique name for your client in the text field that appears. -5. Choose an expiration date (maximum 1 year from today; 6 months is recommended). This setting is immutable after creation. -6. Select **Create**. A popup window displays your client secret. +1. Log in to [NGINXaaS Console](https://console.nginxaas.net/). +1. Select **Settings** > **Client Credentials** from the left navigation menu. +1. Select **+ Add Client** to create a new credential. +1. Enter a unique name for your client in the text field that appears. +1. Choose an expiration date (maximum 1 year from today; 6 months is recommended). This setting is immutable after creation. +1. Select **Create**. +1. A popup window displays your client secret. {{< call-out class="warning" title="Important: Store Your Client Secret Securely" >}} -The client secret appears only once. Save it immediately in a secure location, such as a password manager or secrets vault. If you lose the secret, you must delete this credential and create a new one. +The client secret appears only once. Save it immediately in a secure location, such as a password manager or secrets vault. {{< /call-out >}} Your client credentials can access the following APIs: @@ -51,11 +52,11 @@ Your client credentials can access the following APIs: ### Client limits -Organizations are limited to a maximum of 10 client credentials. To request an increase to this limit, contact the NGINX Support team. +Organizations are limited to a maximum of 10 client credentials. To request an increase to this limit, contact the (NGINX Support team)({{< ref "/nginxaas-google/get-help/support.md" >}}). ## Retrieve client information -Follow these steps to view your client credentials: +Follow these steps to view information about your clients: 1. Log in to [NGINXaaS Console](https://console.nginxaas.net/). 2. Select **Settings** > **Client Credentials** from the left navigation menu. @@ -85,10 +86,7 @@ Follow these steps to delete a client credential: 5. Select **Delete** from the menu. After deletion: - -- The client can no longer request new access tokens using this credential - Existing access tokens continue to work until they expire (1 hour from issuance) -- The client ID and secret become permanently invalid {{< call-out class="note" >}} Expired credentials are not automatically removed. You must manually delete credentials that are past their expiration date. @@ -143,10 +141,9 @@ curl -X GET "https://.api.nginxaas.net/api/v1/deployments" \ ## Security best practices -- **Use separate credentials for different environments**: Create distinct clients for various scopes to keep environments logically separate -- **Store secrets securely**: Never commit client secrets to version control +- **Store secrets securely**: Store client credentials in a secure place - **Delete unused credentials**: Remove clients that are no longer needed -- **Follow the recommended expiration**: Unless you have a specific reason, use the recommended 6-month expiration +- **Follow the recommended expiration**: Avoid using clients with a very long expiration, a good default to begin with is 6 months ## Troubleshooting @@ -190,7 +187,7 @@ Client credentials can only access the Certificates, Configs, and Deployments AP | Client secret visibility | Only shown once during creation | | Default expiration | 6 months (recommended) | | Maximum expiration | 1 year | -| Client limit per organization | 10 clients (contact NGINX Support to increase) | +| Client limit per organization | 10 clients [contact NGINX Support to increase]({{< ref "/nginxaas-google/get-help/support.md" >}}) | | Access token validity | 1 hour | | Supported resources | Deployments, Configs, Certificates | | Token endpoint | `https://.api.nginxaas.net/api/v1/marketplace/auth/token` | From 8059de2d73dd410abcf5c232009c439528167400 Mon Sep 17 00:00:00 2001 From: nparikh03 Date: Mon, 22 Jun 2026 09:17:20 -0700 Subject: [PATCH 5/6] Adding more details to sections Co-authored-by: Jon Torre <78599298+JTorreG@users.noreply.github.com> --- .../quickstart/security-controls/client-credentials.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/content/nginxaas-google/quickstart/security-controls/client-credentials.md b/content/nginxaas-google/quickstart/security-controls/client-credentials.md index 28aa4226ea..f8b0d25117 100644 --- a/content/nginxaas-google/quickstart/security-controls/client-credentials.md +++ b/content/nginxaas-google/quickstart/security-controls/client-credentials.md @@ -94,6 +94,8 @@ Expired credentials are not automatically removed. You must manually delete cred ## Using client credentials for authentication +Learn how to obtain and use access tokens from your client credentials to authenticate API requests. + ### Exchange credentials for an access token Use the client credentials to obtain an access token from the token endpoint. @@ -147,6 +149,8 @@ curl -X GET "https://.api.nginxaas.net/api/v1/deployments" \ ## Troubleshooting +Common issues when authenticating with client credentials and how to resolve them. + ### Invalid or expired credentials If you attempt to authenticate with invalid or expired credentials, you will receive a `401 Unauthorized` response. In this case: From 3fce6862a616ffd6374224c8960274c1b6323144 Mon Sep 17 00:00:00 2001 From: Noopur Parikh Date: Mon, 22 Jun 2026 21:40:23 -0700 Subject: [PATCH 6/6] update auth token endpoint --- .../security-controls/client-credentials.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/content/nginxaas-google/quickstart/security-controls/client-credentials.md b/content/nginxaas-google/quickstart/security-controls/client-credentials.md index f8b0d25117..22be7bc5bc 100644 --- a/content/nginxaas-google/quickstart/security-controls/client-credentials.md +++ b/content/nginxaas-google/quickstart/security-controls/client-credentials.md @@ -18,7 +18,7 @@ f5-audience: operator ## Overview -This guide explains how to create and use client credentials for automating access to NGINXaaS APIs. Client credentials enable automation tools such as CI/CD pipelines to manage your deployments, configurations, and certificates without requiring user login. +This guide explains how to create and use client credentials for automating access to NGINXaaS APIs. Client credentials enable automation tools such as CI/CD pipelines to manage certain NGINXaaS resources without requiring user login. To authenticate, you exchange your client credentials (client ID and secret) for a short-lived access token from the NGINXaaS token endpoint. This access token is then used in the Authorization header of your API requests. Access tokens have limited validity, after which you'll need to request a new one using the same credentials. @@ -46,9 +46,9 @@ The client secret appears only once. Save it immediately in a secure location, s Your client credentials can access the following APIs: -- Certificates API -- Configs API -- Deployments API +- [Certificates API]({{< ref "/nginxaas-google/getting-started/ssl-tls-certificates/ssl-tls-certificates-console.md" >}}) +- [Configs API]({{< ref "/nginxaas-google/getting-started/nginx-configuration/nginx-configuration-console.md" >}}) +- [Deployments API]({{< ref "/nginxaas-google/getting-started/create-deployment/deploy-console.md" >}}) ### Client limits @@ -100,12 +100,12 @@ Learn how to obtain and use access tokens from your client credentials to authen Use the client credentials to obtain an access token from the token endpoint. -**Endpoint**: `POST https://.api.nginxaas.net/api/v1/marketplace/auth/token` +**Endpoint**: `POST https://.api.nginxaas.net/api/v1/auth/token` **Example using cURL**: ```bash -curl -X POST "https://.api.nginxaas.net/api/v1/marketplace/auth/token" \ +curl -X POST "https://.api.nginxaas.net/api/v1/auth/token" \ -H "Content-Type: application/json" \ -d '{ "client_id": "", @@ -173,7 +173,7 @@ If you attempt to authenticate with invalid or expired credentials, you will rec Client credentials can only access the Certificates, Configs, and Deployments APIs. Attempting to access any other API with client credentials returns a `403 Forbidden` response. In this case: - Verify you are using the correct API endpoint -- Ensure the API is one of the supported resources (Deployments, Configs, or Certificates) +- Ensure the API is one of the supported resources **Example error response**: @@ -194,7 +194,7 @@ Client credentials can only access the Certificates, Configs, and Deployments AP | Client limit per organization | 10 clients [contact NGINX Support to increase]({{< ref "/nginxaas-google/get-help/support.md" >}}) | | Access token validity | 1 hour | | Supported resources | Deployments, Configs, Certificates | -| Token endpoint | `https://.api.nginxaas.net/api/v1/marketplace/auth/token` | +| Token endpoint | `https://.api.nginxaas.net/api/v1/auth/token` | ## What's next