From 6b0c0e35ccb77f4d75e2d67fba6b32b89bd5daeb Mon Sep 17 00:00:00 2001 From: Toan Nguyen Date: Thu, 6 Feb 2025 21:01:20 +0700 Subject: [PATCH 1/5] docs: improve JWT configuration page (#873) Co-authored-by: Sean Park-Ross <94021366+seanparkross@users.noreply.github.com> --- docs/auth/jwt/jwt-configuration.mdx | 624 +++++++++++++++++----------- 1 file changed, 376 insertions(+), 248 deletions(-) diff --git a/docs/auth/jwt/jwt-configuration.mdx b/docs/auth/jwt/jwt-configuration.mdx index ddba4dff9..717e8ad52 100644 --- a/docs/auth/jwt/jwt-configuration.mdx +++ b/docs/auth/jwt/jwt-configuration.mdx @@ -21,24 +21,29 @@ This section describes the JSON Web Token (JWT) configuration options available Example JSON Web Token (JWT) payload configuration definition: -```json -{ - "type": "optional-type-of-key", - "key": "optional-key-as-string", - "jwk_url": "optional-url-to-refresh-jwks", - "sub": "optional-string-to-verify-subject", - "claims_namespace": "optional-key-name-in-claims", - "claims_namespace_path": "optional-json-path-to-the-claims", - "claims_format": "json|stringified_json", - "audience": "optional-string-or-list-of-strings-to-verify-audience", - "issuer": "optional-string-to-verify-issuer", - "claims_map": "optional-object-of-session-variable-to-claim-jsonpath-or-literal-value", - "allowed_skew": "optional-number-of-seconds-in-integer", - "header": "optional-key-to-indicate-cookie-or-authorization-header" -} +```yaml title="globals/metadata/auth-config.hml" +kind: AuthConfig +version: v2 +definition: + mode: + jwt: + claimsConfig: + namespace: + claimsFormat: Json + location: /claims.jwt.hasura.io + tokenLocation: + type: BearerAuthorization + key: + fixed: + algorithm: HS256 + key: + value: ultra-secret-very-secret-super-secret-key + audience: ["myapp-1234", "myapp-6789"] + allowedSkew: 60 + issuer: https://my-auth-server.com ``` -As a minimum, either the `type` **and** `key` values OR the `jwk_url` value **have to be present**. +As a minimum, either the `claimsConfig`, `tokenLocation`, **and** `key` values **have to be present**. ## Example Decoded Payload @@ -73,7 +78,7 @@ of this example JWT token. The signature secret to verify this token with the HS The `x-hasura-role` value can be sent as a plain **header** in the request to indicate the role which should be used. When your auth server generates the JWT, the custom claims in the JWT **must contain the following** in a custom -namespace. This namespace can be any string you choose, as long as it matches the `claims_namespace` defined in your +namespace. This namespace can be any string you choose, as long as it matches the `namespace.location` defined in your AuthConfig. Using `claims.jwt.hasura.io` will match our examples. 1. A `x-hasura-default-role` field. The role that will be used when the optional `x-hasura-role` _header_ is **not @@ -128,55 +133,32 @@ your auth provider. ## Hasura JWT configuration options -### type {#jwt-json-type} +### claimsConfig -This specifies the cryptographic signing algorithm which is used to sign the JWTs. Valid values are : `HS256`, `HS384`, -`HS512`, `RS256`, `RS384`, `RS512`, `ES256`, `ES384`, `PS256`, `PS384`, `PS512`, `EdDSA`. +You can specify where the engine should look for the claims within the decoded token either with one of `namespace` and `locations` options. -### key {#jwt-json-key} +#### namespace {#jwt-claims-config-namespace} -- In the case of a symmetric key (i.e. a HMAC-based key), just the key as is. (e.g. -"abcdef..."). The key must be long - enough for the chosen algorithm, (e.g. for HS256 it must be at least 32 characters long). -- In the case of an asymmetric key (RSA, EdDSA, ECDSA etc.), only the **public** key, in a PEM-encoded string or as an - X509 certificate. - -This is an optional field. You can also provide a URL to fetch JWKs from using the `jwk_url` field. - -### jwk_url {#jwt-json-jwk_url} - -An URL where a provider publishes their JWKs (JSON Web Keys - which are used for signing the JWTs). The URL **must** -publish the JWKs in the standard format as described [here](https://tools.ietf.org/html/rfc7517). - -This is optional as you have the alternative of also providing the key (certificate, PEM-encoded public key) as a -string - in the [`key`](#jwt-json-key) field along with the [`type`](#jwt-json-type). - -DDN does not currently support rotating JWKs. +The `namespace` option is used when all of the Hasura claims are present in a single object within the decoded JWT. +Our example uses `claims.jwt.hasura.io` in the [Example Decoded Payload](#example-decoded-payload). -### JWK publisher URLs - -- Auth0 publishes their JWK url at: `https://.auth0.com`. -- Firebase publishes their JWK url at: - `https://www.googleapis.com/service_accounts/v1/jwk/securetoken@system.gserviceaccount.com`. - -### claims_namespace {#claims-namespace} - -This namespace can be any string you choose, as long as it matches the `claims_namespace` defined in your AuthConfig. -Using `claims.jwt.hasura.io` will match our examples. - -### claims_format - -This is an optional field, with only the following possible values allowed: `json`, `stringified_json` +```yaml +claimsConfig: + namespace: + claimsFormat: Json + location: /claims.jwt.hasura.io +``` -The default is `json`. +The `location` field indicates the location of the namespace object that uses [RFC 6901 JSON Pointer](https://datatracker.ietf.org/doc/html/rfc6901) string syntax. -This is to indicate whether the Hasura-specific claims are a regular JSON object or a stringified JSON. +The `claimsFormat` field indicates whether the Hasura-specific claims are a regular JSON object or a stringified JSON. The following possible values are allowed: `Json`, `StringifiedJson`. This is required because providers like AWS Cognito only allow strings in the JWT claims. [See #1176](https://github.com/hasura/graphql-engine/issues/1176). -Example: +**Example**: -If `claims_format` is `json` then the JWT claims should look like: +If `claimsFormat` is `Json` then the JWT claims should look like: ```json { @@ -194,7 +176,7 @@ If `claims_format` is `json` then the JWT claims should look like: } ``` -If `claims_format` is `stringified_json` then the JWT claims should look like: +If `claimsFormat` is `StringifiedJson` then the JWT claims should look like: ```json { @@ -206,107 +188,18 @@ If `claims_format` is `stringified_json` then the JWT claims should look like: } ``` -### audience - -This is an optional field. Certain providers might set a claim which indicates the intended audience for the JWT. This -can be checked by setting this field. - -When this field is set, during the verification process of the JWT, the `aud` claim in the JWT will be checked to see -whether it is equal to the `audience` field given in the configuration. If they are not equal then the JWT will be -rejected. - -See the [RFC](https://tools.ietf.org/html/rfc7519#section-4.1.3) for more details. - -This field can be a string, or a list of strings. - -Examples: - -```json -{ - "jwk_url": "https://......", - "audience": "myapp-1234" -} -``` - -or - -```json -{ - "jwk_url": "https://......", - "audience": ["myapp-1234", "myapp-6789"] -} -``` - -:::danger Audience Security Vulnerability - -Certain JWT providers share JWKs between multiple tenants. They use the `aud` claim of the JWT to specify the intended -audience. Setting the `audience` field in the Hasura JWT configuration will make sure that the `aud` claim from the JWT -is also checked during verification. Not doing this check will allow JWTs issued for other tenants to be valid as well. - -In these cases, you **MUST** set the `audience` field to the appropriate value. Failing to do so is a **major security -vulnerability**. - -::: - -### issuer - -This is an optional field. It takes a string value. - -When this field is set, during the verification process of the JWT, the `iss` claim in the JWT will be checked to see -whether it is equal to the `issuer` field given in the configuration. If they are not equal then the JWT will be -rejected. - -See [RFC](https://tools.ietf.org/html/rfc7519#section-4.1.1) for more details. - -Examples: - -```json -{ - "jwk_url": "https://......", - "issuer": "https://my-auth-server.com" -} -``` - -#### Issuer Notes +#### locations {#jwt-claims-config-locations} -- Certain providers require you to verify the `iss` claim on the JWT. To do that you can set this field to the - appropriate value. -- A JWT configuration without an issuer will match any issuer field present in an incoming JWT. -- An incoming JWT without an issuer specified will match a configuration even if it specifies an issuer. - -### claims_map +This `locations` option can be used when Hasura claims are not all present in the single object, but individual claims are provided a JSON pointer within the decoded JWT. +In this option, you can indicate: +- a literal value. +- or a JSON pointer path for individual claims and an optional default value if the claim doesn't exist. -This is an optional field. Certain providers might not allow adding custom claims. In such a case, you can map Hasura -session variables with existing JWT claims using `claims_map`. The `claims_map` is a JSON object where keys are session -variables and values can be a JSON path (with a default value option, when the key specified by the JSON path doesn't -exist) or a literal value. +`x-hasura-default-role` and `x-hasura-allowed-roles` claims are required. Other custom claims are optionally configured. The literal values should be of type `String`, except for the `x-hasura-allowed-roles` claim which expects a string array. -The value of a claim referred by a JSON path must be a string. To use the JSON path value, the path needs to be given in -a JSON object with `path` as the key and the JSON path as the value: - -```json -{ - "path": "$.user.all_roles" -} -``` - -```json -{ - "path": "$.roles.default", - "default": "user" -} -``` - -:::info Claims map precedence - -If `claims_map` is provided in the JWT config, `claims_namespace`/`claims_namespace_path` and `claims_format` will be -ignored. - -::: - **Example: JWT config with JSON path values** ```json @@ -325,18 +218,20 @@ ignored. ``` The mapping for `x-hasura-allowed-roles`, `x-hasura-default-role` and `x-hasura-user-id` session variables can be -specified in the `claims_map` configuration as follows: +specified in the `locations` configuration as follows: -```json -{ - "type": "RS512", - "key": "-----BEGIN PUBLIC KEY-----\nMIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDdlatRjRjogo3WojgGHFHYLugd\nUWAY9iR3fy4arWNA1KoS8kVw33cJibXr8bvwUAUparCwlvdbH6dvEOfou0/gCFQs\nHUfQrSDv+MuSUMAe8jzKE4qW+jK+xQU9a03GUnKHkkle+Q0pX/g6jXZ7r1/xAK5D\no2kQ+X5xK9cipRgEKwIDAQAB\n-----END PUBLIC KEY-----\n", - "claims_map": { - "x-hasura-allowed-roles": { "path": "$.hasura.all_roles" }, - "x-hasura-default-role": { "path": "$.hasura.all_roles[0]" }, - "x-hasura-user-id": { "path": "$.user.id" } - } -} +```yaml +claimsConfig: + locations: + x-hasura-default-role: + path: + path: /hasura/all_roles/0 + x-hasura-allowed-roles: + path: + path: /hasura/all_roles + x-hasura-user-id: + path: + path: /user/id ``` **Example: JWT config with JSON path values and default values** @@ -353,20 +248,23 @@ specified in the `claims_map` configuration as follows: } ``` -```json -{ - "type": "RS512", - "key": "-----BEGIN PUBLIC KEY-----\nMIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDdlatRjRjogo3WojgGHFHYLugd\nUWAY9iR3fy4arWNA1KoS8kVw33cJibXr8bvwUAUparCwlvdbH6dvEOfou0/gCFQs\nHUfQrSDv+MuSUMAe8jzKE4qW+jK+xQU9a03GUnKHkkle+Q0pX/g6jXZ7r1/xAK5D\no2kQ+X5xK9cipRgEKwIDAQAB\n-----END PUBLIC KEY-----\n", - "claims_map": { - "x-hasura-allowed-roles": { "path": "$.hasura.all_roles" }, - "x-hasura-default-role": { "path": "$.hasura.all_roles[0]" }, - "x-hasura-user-id": { "path": "$.user.id", "default": "ujdh739kd" } - } -} +```yaml +claimsConfig: + locations: + x-hasura-default-role: + path: + path: /hasura/all_roles/0 + x-hasura-allowed-roles: + path: + path: /hasura/all_roles + x-hasura-user-id: + path: + path: /user/id + default: ujdh739kd ``` -In the above case, since the `$.user.id` doesn't exist in the JWT token, the default value of the `x-hasura-user-id` i.e -"ujdh739kd" will be used +In the above case, since the `/user/id` doesn't exist in the JWT token, the default value of the `x-hasura-user-id` i.e +`ujdh739kd` will be used **Example: JWT config containing literal values** @@ -384,66 +282,191 @@ In the above case, since the `$.user.id` doesn't exist in the JWT token, the def The corresponding JWT config should be: -```json -{ - "type": "RS512", - "key": "-----BEGIN PUBLIC KEY-----\nMIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDdlatRjRjogo3WojgGHFHYLugd\nUWAY9iR3fy4arWNA1KoS8kVw33cJibXr8bvwUAUparCwlvdbH6dvEOfou0/gCFQs\nHUfQrSDv+MuSUMAe8jzKE4qW+jK+xQU9a03GUnKHkkle+Q0pX/g6jXZ7r1/xAK5D\no2kQ+X5xK9cipRgEKwIDAQAB\n-----END PUBLIC KEY-----\n", - "claims_map": { - "x-hasura-allowed-roles": ["user", "editor"], - "x-hasura-default-role": "user", - "x-hasura-user-id": { "path": "$.user.id" } - } -} +```yaml +claimsConfig: + locations: + x-hasura-default-role: + literal: user + x-hasura-allowed-roles: + literal: ["user", "editor"] + x-hasura-user-id: + path: + path: /user/id ``` In the above example, the `x-hasura-allowed-roles` and `x-hasura-default-role` values are set in the JWT config and the value of the `x-hasura-user-id` is a JSON path to the value in the JWT token. -### allowed_skew +### tokenLocation -`allowed_skew` is an optional field to provide some leeway (to account for clock skews) while comparing the JWT expiry -time. This field expects an integer value which will be the number of seconds of the skew value. +Indicates the token location where request header to read the JWT from. + +The following are the possible values: -### header +#### BearerAuthorization -This is an optional field, which indicates which request header to read the JWT from. This field is a stringified JSON -object. +In this mode, Hasura expects an `Authorization` header with a `Bearer` token. -The following are the possible values: +```yaml +tokenLocation: + type: BearerAuthorization +``` -- `{"type": "Authorization"}` -- `{"type": "Cookie", "name": "cookie_name" }` -- `{"type": "CustomHeader", "name": "header_name" }` +The JWT header should look like: -Default is `{"type": "Authorization"}`. +```none +Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWI... +``` -In the default mode, Hasura expects an `Authorization` header with a `Bearer` token. +#### Cookie In the cookie mode, Hasura will try to parse the cookie header with the given cookie name. The value of the cookie should be the exact JWT. -In the custom header mode, Hasura expects a `header_name` header with the exact JWT token value. - -Example: +```yaml +tokenLocation: + type: Cookie + name: cookie_name +``` -If `header` is `{"type": "Authorization"}` then JWT header should look like: +The JWT header should look like: ```none -Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWI... +Cookie: cookie_name=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWI... ``` -If `header` is `{"type": "Cookie", "name": "cookie_name" }` then JWT header should look like: +#### Header -```none -Cookie: cookie_name=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWI... +In the custom header mode, Hasura expects a `header_name` header with the exact JWT token value. + +```yaml +tokenLocation: + type: Header + name: header_name ``` -If `header` is `{"type": "CustomHeader", "name": "header_name" }` then JWT header should look like: +The JWT header should look like: ```none header_name: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWI... ``` +### key {#jwt-json-key} + +This field specifies the JWT key configuration according to which the incoming JWT will be decoded. +You can configure either a `fixed` algorithm key or a remote JWK URL. + +#### fixed {#jwt-json-key-fixed} + +In this option, you must indicate a JWT key and its algorithm so the engine can decode and verify the JWT token. + +```yaml +key: + fixed: + algorithm: HS256 + key: + value: ultra-secret-very-secret-super-secret-key + # valueFromEnv: AUTH_JWT_KEY +``` + +The `algorithm` field specifies the cryptographic signing algorithm which is used to sign the JWTs. Valid values are: `HS256`, `HS384`, +`HS512`, `RS256`, `RS384`, `RS512`, `ES256`, `ES384`, `PS256`, `PS384`, `PS512`, `EdDSA`. + +The `key` field can be a literal value or an environment variable name. + +- In the case of a symmetric key (i.e. a HMAC-based key), just the key as is. (e.g. -"abcdef..."). The key must be long + enough for the chosen algorithm, (e.g. for HS256 it must be at least 32 characters long). +- In the case of an asymmetric key (RSA, EdDSA, ECDSA etc.), only the **public** key, in a PEM-encoded string or as an + X509 certificate. + +#### jwkFromUrl {#jwt-json-jwk_url} + +An URL where a provider publishes their JWKs (JSON Web Keys - which are used for signing the JWTs). The URL **must** +publish the JWKs in the standard format as described [here](https://tools.ietf.org/html/rfc7517). + +For example: + +- Auth0 publishes their JWK url at: `https://.auth0.com`. +- Firebase publishes their JWK url at: + `https://www.googleapis.com/service_accounts/v1/jwk/securetoken@system.gserviceaccount.com`. + +```yaml +key: + jwkFromUrl: https://www.googleapis.com/service_accounts/v1/jwk/securetoken@system.gserviceaccount.com +``` + +DDN does not currently support rotating JWKs. + +### audience + +This is an optional field. Certain providers might set a claim which indicates the intended audience for the JWT. This +can be checked by setting this field. + +When this field is set, during the verification process of the JWT, the `aud` claim in the JWT will be checked to see +whether it is equal to the `audience` field given in the configuration. If they are not equal then the JWT will be +rejected. + +See the [RFC](https://tools.ietf.org/html/rfc7519#section-4.1.3) for more details. + +This field must be a list of strings. + +Examples: + +```yaml +kind: AuthConfig +version: v2 +definition: + mode: + jwt: + # ... + audience: ["myapp-1234", "myapp-6789"] +``` + +:::danger Audience Security Vulnerability + +Certain JWT providers share JWKs between multiple tenants. They use the `aud` claim of the JWT to specify the intended +audience. Setting the `audience` field in the Hasura JWT configuration will make sure that the `aud` claim from the JWT +is also checked during verification. Not doing this check will allow JWTs issued for other tenants to be valid as well. + +In these cases, you **MUST** set the `audience` field to the appropriate value. Failing to do so is a **major security +vulnerability**. + +::: + +### issuer + +This is an optional field. It takes a string value. + +When this field is set, during the verification process of the JWT, the `iss` claim in the JWT will be checked to see +whether it is equal to the `issuer` field given in the configuration. If they are not equal then the JWT will be +rejected. + +See [RFC](https://tools.ietf.org/html/rfc7519#section-4.1.1) for more details. + +Examples: + +```yaml +kind: AuthConfig +version: v2 +definition: + mode: + jwt: + # ... + issuer: https://my-auth-server.com +``` + +#### Issuer Notes + +- Certain providers require you to verify the `iss` claim on the JWT. To do that you can set this field to the + appropriate value. +- A JWT configuration without an issuer will match any issuer field present in an incoming JWT. +- An incoming JWT without an issuer specified will match a configuration even if it specifies an issuer. + +### allowed_skew + +`allowedSkew` is an optional field to provide some leeway (to account for clock skews) while comparing the JWT expiry +time. This field expects an integer value which will be the number of seconds of the skew value. + ### Hasura JWT Config Examples #### HMAC-SHA based @@ -451,11 +474,23 @@ header_name: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWI... Your auth server is using HMAC-SHA algorithms to sign JWTs, and is using a 256-bit key. In this case, the JWT config will look like: -```json -{ - "type": "HS256", - "key": "3EK6FD+o0+c7tzBNVfjpMkNDi2yARAAKzQlk8O2IKoxQu4nF7EdAh8s3TwpHwrdWT6R" -} +```yaml +kind: AuthConfig +version: v2 +definition: + mode: + jwt: + claimsConfig: + namespace: + claimsFormat: Json + location: /claims.jwt.hasura.io + tokenLocation: + type: BearerAuthorization + key: + fixed: + algorithm: HS256 + key: + value: 3EK6FD+o0+c7tzBNVfjpMkNDi2yARAAKzQlk8O2IKoxQu4nF7EdAh8s3TwpHwrdWT6R ``` The `key` is the actual shared secret, which is used by Hasura and the external auth server. @@ -467,28 +502,62 @@ have the public key. **Example 1**: public key in PEM format (not OpenSSH format): -```json -{ - "type": "RS512", - "key": "-----BEGIN PUBLIC KEY-----\nMIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDdlatRjRjogo3WojgGHFHYLugd\nUWAY9iR3fy4arWNA1KoS8kVw33cJibXr8bvwUAUparCwlvdbH6dvEOfou0/gCFQs\nHUfQrSDv+MuSUMAe8jzKE4qW+jK+xQU9a03GUnKHkkle+Q0pX/g6jXZ7r1/xAK5D\no2kQ+X5xK9cipRgEKwIDAQAB\n-----END PUBLIC KEY-----\n" -} +```yaml +kind: AuthConfig +version: v2 +definition: + mode: + jwt: + claimsConfig: + namespace: + claimsFormat: Json + location: /claims.jwt.hasura.io + tokenLocation: + type: BearerAuthorization + key: + fixed: + algorithm: RS512 + key: + value: '-----BEGIN PUBLIC KEY-----\nMIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDdlatRjRjogo3WojgGHFHYLugd\nUWAY9iR3fy4arWNA1KoS8kVw33cJibXr8bvwUAUparCwlvdbH6dvEOfou0/gCFQs\nHUfQrSDv+MuSUMAe8jzKE4qW+jK+xQU9a03GUnKHkkle+Q0pX/g6jXZ7r1/xAK5D\no2kQ+X5xK9cipRgEKwIDAQAB\n-----END PUBLIC KEY-----\n' ``` **Example 2**: public key as X509 certificate: -```json -{ - "type": "RS512", - "key": "-----BEGIN CERTIFICATE-----\nMIIDHDCCAgSgAwIBAgIINw9gva8BPPIwDQYJKoZIhvcNAQEFBQAwMTEvMC0GA1UE\nAxMmc2VjdXJldG9rZW4uc3lzdGVtLmdzZXJ2aWNlYWNjb3VudC5jb20wHhcNMTgQt7dIsMTIU9k1SUrFviZOGnmHWtIAw\nmtYBcM9I0f9/ka45JIRp5Y1NKpAMFSShs7Wv0m1JS1kXQHdJsPSmjmDKcwnBe3R/\nTU3foRRywR/3AJRM15FNjTqvUm7TeaW16LkkRoECAwEAAaM4MDYwDAYDVR0TAQH/\nBAIwADAOBgNVHQ8BAf8EBAMCB4AwFgYDVR0lAQH/BAwwCgYIKwYBBQUHAwIwDQYJ\nKoZIhvcNAQEFBQADggEBADfY2DEmc2gb8/pqMNWHYq/nTYfJPpK4VA9A0lFTNeoq\nzmnbGwhKj24X+Nw8trsvkrKxHvCI1alDgBaCyzjGGvgOrh8X0wLtymp1yj6PWwee\nR2ZPdUaB62TCzO0iRv7W6o39ey+mU/FyYRtxF0ecxG2a0KNsIyFkciXUAeC5UVDo\nBNp678/SDDx9Ltuxc6h56a/hpBGf9Yzhr0RvYy3DmjBs6eopiGFmjnOKNxQrZ5t2\n339JWR+yiGEAtoHqk/fINMf1An6Rung1xYowrm4guhCIVi5unAvQ89fq0I6mzPg6\nLhTpeP0o+mVYrBmtYVpDpv0e71cfYowSJCCkod/9YbY=\n-----END CERTIFICATE-----" -} +```yaml +kind: AuthConfig +version: v2 +definition: + mode: + jwt: + claimsConfig: + namespace: + claimsFormat: Json + location: /claims.jwt.hasura.io + tokenLocation: + type: BearerAuthorization + key: + fixed: + algorithm: RS512 + key: + value: '-----BEGIN CERTIFICATE-----\nMIIDHDCCAgSgAwIBAgIINw9gva8BPPIwDQYJKoZIhvcNAQEFBQAwMTEvMC0GA1UE\nAxMmc2VjdXJldG9rZW4uc3lzdGVtLmdzZXJ2aWNlYWNjb3VudC5jb20wHhcNMTgQt7dIsMTIU9k1SUrFviZOGnmHWtIAw\nmtYBcM9I0f9/ka45JIRp5Y1NKpAMFSShs7Wv0m1JS1kXQHdJsPSmjmDKcwnBe3R/\nTU3foRRywR/3AJRM15FNjTqvUm7TeaW16LkkRoECAwEAAaM4MDYwDAYDVR0TAQH/\nBAIwADAOBgNVHQ8BAf8EBAMCB4AwFgYDVR0lAQH/BAwwCgYIKwYBBQUHAwIwDQYJ\nKoZIhvcNAQEFBQADggEBADfY2DEmc2gb8/pqMNWHYq/nTYfJPpK4VA9A0lFTNeoq\nzmnbGwhKj24X+Nw8trsvkrKxHvCI1alDgBaCyzjGGvgOrh8X0wLtymp1yj6PWwee\nR2ZPdUaB62TCzO0iRv7W6o39ey+mU/FyYRtxF0ecxG2a0KNsIyFkciXUAeC5UVDo\nBNp678/SDDx9Ltuxc6h56a/hpBGf9Yzhr0RvYy3DmjBs6eopiGFmjnOKNxQrZ5t2\n339JWR+yiGEAtoHqk/fINMf1An6Rung1xYowrm4guhCIVi5unAvQ89fq0I6mzPg6\nLhTpeP0o+mVYrBmtYVpDpv0e71cfYowSJCCkod/9YbY=\n-----END CERTIFICATE-----' ``` **Example 3**: public key published as JWKs: -```json -{ - "jwk_url": "https://www.googleapis.com/service_accounts/v1/jwk/securetoken@system.gserviceaccount.com" -} +```yaml +kind: AuthConfig +version: v2 +definition: + mode: + jwt: + claimsConfig: + namespace: + claimsFormat: Json + location: /claims.jwt.hasura.io + tokenLocation: + type: BearerAuthorization + key: + jwkFromUrl: https://www.googleapis.com/service_accounts/v1/jwk/securetoken@system.gserviceaccount.com ``` #### EdDSA based @@ -498,20 +567,44 @@ the public key. **Example 1**: public key in PEM format (not OpenSSH format): -```json -{ - "type": "Ed25519", - "key": "-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEAG9I+toAAJicilbPt36tiC4wi7E1Dp9rMmfnwdKyVXi0=\n-----END PUBLIC KEY-----" -} +```yaml +kind: AuthConfig +version: v2 +definition: + mode: + jwt: + claimsConfig: + namespace: + claimsFormat: Json + location: /claims.jwt.hasura.io + tokenLocation: + type: BearerAuthorization + key: + fixed: + algorithm: Ed25519 + key: + value: '-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEAG9I+toAAJicilbPt36tiC4wi7E1Dp9rMmfnwdKyVXi0=\n-----END PUBLIC KEY-----' ``` **Example 2**: public key as X509 certificate: -```json -{ - "type": "Ed25519", - "key": "-----BEGIN CERTIFICATE REQUEST-----\nMIIBAzCBtgIBADAnMQswCQYDVQQGEwJERTEYMBYGA1UEAwwPd3d3LmV4YW1wbGUu\nY29tMCowBQYDK2VwAyEA/9DV/InajW02Q0tC/tyr9mCSbSnNP1txICXVJrTGKDSg\nXDBaBgkqhkiG9w0BCQ4xTTBLMAsGA1UdDwQEAwIEMDATBgNVHSUEDDAKBggrBgEF\nBQcDATAnBgNVHREEIDAegg93d3cuZXhhbXBsZS5jb22CC2V4YW1wbGUuY29tMAUG\nAytlcANBAKbTqnTyPcf4ZkVuq2tC108pBGY19VgyoI+PP2wD2KaRz4QAO7Bjd+7S\nljyJoN83UDdtdtgb7aFgb611gx9W4go=\n-----END CERTIFICATE REQUEST-----" -} +```yaml +kind: AuthConfig +version: v2 +definition: + mode: + jwt: + claimsConfig: + namespace: + claimsFormat: Json + location: /claims.jwt.hasura.io + tokenLocation: + type: BearerAuthorization + key: + fixed: + algorithm: Ed25519 + key: + value: '-----BEGIN CERTIFICATE REQUEST-----\nMIIBAzCBtgIBADAnMQswCQYDVQQGEwJERTEYMBYGA1UEAwwPd3d3LmV4YW1wbGUu\nY29tMCowBQYDK2VwAyEA/9DV/InajW02Q0tC/tyr9mCSbSnNP1txICXVJrTGKDSg\nXDBaBgkqhkiG9w0BCQ4xTTBLMAsGA1UdDwQEAwIEMDATBgNVHSUEDDAKBggrBgEF\nBQcDATAnBgNVHREEIDAegg93d3cuZXhhbXBsZS5jb22CC2V4YW1wbGUuY29tMAUG\nAytlcANBAKbTqnTyPcf4ZkVuq2tC108pBGY19VgyoI+PP2wD2KaRz4QAO7Bjd+7S\nljyJoN83UDdtdtgb7aFgb611gx9W4go=\n-----END CERTIFICATE REQUEST-----' ``` #### EC based @@ -521,28 +614,63 @@ needs to have the public key. **Example 1**: public key in PEM format (not OpenSSH format): -```json -{ - "type": "ES256", - "key": "-----BEGIN PUBLIC KEY-----\nMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEEVs/o5+uQbTjL3chynL4wXgUg2R9\nq9UU8I5mEovUf86QZ7kOBIjJwqnzD1omageEHWwHdBO6B+dFabmdT9POxg==\n-----END PUBLIC KEY-----" -} +```yaml +kind: AuthConfig +version: v2 +definition: + mode: + jwt: + claimsConfig: + namespace: + claimsFormat: Json + location: /claims.jwt.hasura.io + tokenLocation: + type: BearerAuthorization + key: + fixed: + algorithm: ES256 + key: + value: '-----BEGIN PUBLIC KEY-----\nMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEEVs/o5+uQbTjL3chynL4wXgUg2R9\nq9UU8I5mEovUf86QZ7kOBIjJwqnzD1omageEHWwHdBO6B+dFabmdT9POxg==\n-----END PUBLIC KEY-----' ``` **Example 2**: public key as X509 certificate: -```json -{ - "type": "ES256", - "key": "-----BEGIN CERTIFICATE-----\nMIIBbjCCARWgAwIBAgIUGn02F6Y6s88dDGmIfwiNxWxDjhswCgYIKoZIzj0EAwIw\nDTELMAkGA1UEBhMCSU4wHhcNMjMwNTI0MTAzNTI4WhcNMjgwNTIyMTAzNTI4WjAN\nMQswCQYDVQQGEwJJTjBZMBMGByqGSM49AgEGCCqGSM49AwEHA0IABBFbP6OfrkG0\n4y93Icpy+MF4FINkfavVFPCOZhKL1H/OkGe5DgSIycKp8w9aJmoHhB1sB3QTugfn\nRWm5nU/TzsajUzBRMB0GA1UdDgQWBBSaqFjzps1qG+x2DPISjaXTWsTOdDAfBgNV\nHSMEGDAWgBSaqFjzps1qG+x2DPISjaXTWsTOdDAPBgNVHRMBAf8EBTADAQH/MAoG\nCCqGSM49BAMCA0cAMEQCIBDHHWa/uLAVdGFEk82auTmw995+MsRwv52VXLw2Z+ji\nAiAXzOWIcGN8p25uhUN/7v9gEcADGIS4yUiv8gsn/Jk2ow==\n-----END CERTIFICATE-----" -} + +```yaml +kind: AuthConfig +version: v2 +definition: + mode: + jwt: + claimsConfig: + namespace: + claimsFormat: Json + location: /claims.jwt.hasura.io + tokenLocation: + type: BearerAuthorization + key: + fixed: + algorithm: ES256 + key: + value: '"-----BEGIN CERTIFICATE-----\nMIIBbjCCARWgAwIBAgIUGn02F6Y6s88dDGmIfwiNxWxDjhswCgYIKoZIzj0EAwIw\nDTELMAkGA1UEBhMCSU4wHhcNMjMwNTI0MTAzNTI4WhcNMjgwNTIyMTAzNTI4WjAN\nMQswCQYDVQQGEwJJTjBZMBMGByqGSM49AgEGCCqGSM49AwEHA0IABBFbP6OfrkG0\n4y93Icpy+MF4FINkfavVFPCOZhKL1H/OkGe5DgSIycKp8w9aJmoHhB1sB3QTugfn\nRWm5nU/TzsajUzBRMB0GA1UdDgQWBBSaqFjzps1qG+x2DPISjaXTWsTOdDAfBgNV\nHSMEGDAWgBSaqFjzps1qG+x2DPISjaXTWsTOdDAPBgNVHRMBAf8EBTADAQH/MAoG\nCCqGSM49BAMCA0cAMEQCIBDHHWa/uLAVdGFEk82auTmw995+MsRwv52VXLw2Z+ji\nAiAXzOWIcGN8p25uhUN/7v9gEcADGIS4yUiv8gsn/Jk2ow==\n-----END CERTIFICATE-----' ``` **Example 3**: public key published as JWKs: -```json -{ - "jwk_url": "https://www.gstatic.com/iap/verify/public_key-jwk" -} +```yaml +kind: AuthConfig +version: v2 +definition: + mode: + jwt: + claimsConfig: + namespace: + claimsFormat: Json + location: /claims.jwt.hasura.io + tokenLocation: + type: BearerAuthorization + key: + jwkFromUrl: https://www.gstatic.com/iap/verify/public_key-jwk ``` ## Security considerations From bb2139e819fdb71c0b4f15fdcd7c1e91f76d1cc0 Mon Sep 17 00:00:00 2001 From: hasura-bot Date: Fri, 7 Feb 2025 00:14:56 +0530 Subject: [PATCH 2/5] Chore: Update CLI docs (#883) Co-authored-by: hasura-bot Co-authored-by: Krushan Bauva --- docs/reference/cli/commands/ddn.mdx | 5 ++-- docs/reference/cli/commands/ddn_auth.mdx | 8 ++--- .../reference/cli/commands/ddn_auth_login.mdx | 7 +++-- ...at.mdx => ddn_auth_print-access-token.mdx} | 26 ++++++++-------- docs/reference/cli/commands/ddn_codemod.mdx | 30 +++++++------------ .../ddn_codemod_rename-graphql-prefixes.mdx | 3 +- docs/reference/cli/commands/ddn_command.mdx | 9 ++---- .../cli/commands/ddn_command_list.mdx | 3 +- .../cli/commands/ddn_connector-link.mdx | 9 ++---- docs/reference/cli/commands/ddn_connector.mdx | 9 ++---- .../cli/commands/ddn_connector_build.mdx | 12 +++----- .../cli/commands/ddn_connector_env.mdx | 3 +- .../cli/commands/ddn_connector_init.mdx | 2 +- .../cli/commands/ddn_connector_remove.mdx | 3 +- docs/reference/cli/commands/ddn_context.mdx | 6 ++-- .../cli/commands/ddn_context_unset.mdx | 2 +- docs/reference/cli/commands/ddn_doctor.mdx | 3 +- docs/reference/cli/commands/ddn_model.mdx | 9 ++---- docs/reference/cli/commands/ddn_plugins.mdx | 6 ++-- .../cli/commands/ddn_plugins_install.mdx | 3 +- .../cli/commands/ddn_plugins_list.mdx | 3 +- .../cli/commands/ddn_plugins_uninstall.mdx | 3 +- .../cli/commands/ddn_plugins_upgrade.mdx | 3 +- docs/reference/cli/commands/ddn_project.mdx | 9 ++---- .../cli/commands/ddn_project_init.mdx | 4 +-- .../cli/commands/ddn_project_subgraph.mdx | 6 ++-- .../cli/commands/ddn_relationship.mdx | 6 ++-- .../cli/commands/ddn_subgraph_build.mdx | 3 +- .../cli/commands/ddn_supergraph_build.mdx | 21 +++++-------- 29 files changed, 80 insertions(+), 136 deletions(-) rename docs/reference/cli/commands/{ddn_auth_print-pat.mdx => ddn_auth_print-access-token.mdx} (55%) diff --git a/docs/reference/cli/commands/ddn.mdx b/docs/reference/cli/commands/ddn.mdx index 5146b347c..f3259a917 100644 --- a/docs/reference/cli/commands/ddn.mdx +++ b/docs/reference/cli/commands/ddn.mdx @@ -17,9 +17,9 @@ DDN Command Line Interface. ``` + - -DDDDDDD\ DDDDDDD\ NN\ NN\ +DDDDDDD\ DDDDDDD\ NN\ NN\ DD __DD\ DD __DD\ NNN\ NN | DD | DD | DD | DD | NNNN\ NN | DD | DD | DD | DD | NN NN\NN | @@ -63,3 +63,4 @@ ddn [flags] --out string Output format. Can be table, json or yaml. (default "table") --timeout int Request timeout in seconds [env: HASURA_DDN_TIMEOUT] (default 100) ``` + diff --git a/docs/reference/cli/commands/ddn_auth.mdx b/docs/reference/cli/commands/ddn_auth.mdx index d099666f1..1e4ac5a92 100644 --- a/docs/reference/cli/commands/ddn_auth.mdx +++ b/docs/reference/cli/commands/ddn_auth.mdx @@ -20,13 +20,11 @@ Manage Hasura DDN CLI Auth ## Available operations -- [ddn auth generate-promptql-secret-key](/reference/cli/commands/ddn_auth_generate-promptql-secret-key) - Generates the - project's PromptQL secret key and saves to global config +- [ddn auth generate-promptql-secret-key](/reference/cli/commands/ddn_auth_generate-promptql-secret-key) - Generates the project's PromptQL secret key and saves to global config - [ddn auth login](/reference/cli/commands/ddn_auth_login) - Login to DDN - [ddn auth logout](/reference/cli/commands/ddn_auth_logout) - Logout from DDN -- [ddn auth print-pat](/reference/cli/commands/ddn_auth_print-pat) - Prints the PAT to STDOUT -- [ddn auth print-promptql-secret-key](/reference/cli/commands/ddn_auth_print-promptql-secret-key) - Prints the - project's PromptQL secret key to STDOUT +- [ddn auth print-access-token](/reference/cli/commands/ddn_auth_print-access-token) - Prints the access token to STDOUT +- [ddn auth print-promptql-secret-key](/reference/cli/commands/ddn_auth_print-promptql-secret-key) - Prints the project's PromptQL secret key to STDOUT ## Options diff --git a/docs/reference/cli/commands/ddn_auth_login.mdx b/docs/reference/cli/commands/ddn_auth_login.mdx index 2468fbbd9..03bee538f 100644 --- a/docs/reference/cli/commands/ddn_auth_login.mdx +++ b/docs/reference/cli/commands/ddn_auth_login.mdx @@ -29,14 +29,15 @@ ddn auth login [flags] ddn auth login # Login with Personal Access Token - ddn auth login --pat + ddn auth login --access-token ``` ## Options ```sass --h, --help help for login - --pat string Personal Access token [env: HASURA_DDN_PAT] + --access-token string The Personal Access Token or Service Account Token [env: HASURA_DDN_ACCESS_TOKEN] +-h, --help help for login + --pat string Personal Access token [env: HASURA_DDN_PAT] (DEPRECATED: use --access-token instead) ``` ## Options inherited from parent operations diff --git a/docs/reference/cli/commands/ddn_auth_print-pat.mdx b/docs/reference/cli/commands/ddn_auth_print-access-token.mdx similarity index 55% rename from docs/reference/cli/commands/ddn_auth_print-pat.mdx rename to docs/reference/cli/commands/ddn_auth_print-access-token.mdx index 1dc1d1bf1..1bb695fa2 100644 --- a/docs/reference/cli/commands/ddn_auth_print-pat.mdx +++ b/docs/reference/cli/commands/ddn_auth_print-access-token.mdx @@ -1,43 +1,43 @@ --- -sidebar_label: ddn auth print-pat +sidebar_label: ddn auth print-access-token sidebar_position: 6 -description: Prints the PAT to STDOUT using the DDN CLI +description: Prints the access token to STDOUT using the DDN CLI keywords: - hasura - DDN - docs - CLI - - ddn auth print-pat + - ddn auth print-access-token --- -# DDN CLI: ddn auth print-pat +# DDN CLI: ddn auth print-access-token -Prints the PAT to STDOUT. +Prints the access token to STDOUT. ## Synopsis -Prints the PAT to STDOUT +Prints the access token to STDOUT ```bash -ddn auth print-pat [flags] +ddn auth print-access-token [flags] ``` -**Alias:** pp +**Alias:** pp, print-pat ## Examples ```bash -# Print the PAT as a string to STDOUT - ddn auth print-pat +# Print the access token as a string to STDOUT + ddn auth print-access-token -# Print PAT as a JSON to STDOUT - ddn auth print-pat --out json +# Print access token as a JSON to STDOUT + ddn auth print-access-token --out json ``` ## Options ```sass --h, --help help for print-pat +-h, --help help for print-access-token ``` ## Options inherited from parent operations diff --git a/docs/reference/cli/commands/ddn_codemod.mdx b/docs/reference/cli/commands/ddn_codemod.mdx index 5fe1f00e7..e352cbc94 100644 --- a/docs/reference/cli/commands/ddn_codemod.mdx +++ b/docs/reference/cli/commands/ddn_codemod.mdx @@ -20,26 +20,16 @@ Perform transformations on your Hasura project directory ## Available operations -- [ddn codemod configure-header-forwarding](/reference/cli/commands/ddn_codemod_configure-header-forwarding) - Configure - headers to be forwarded to your connector -- [ddn codemod fix-traces-env-var](/reference/cli/commands/ddn_codemod_fix-traces-env-var) - Fix env var used for - configuring traces for connectors -- [ddn codemod rename-graphql-prefixes](/reference/cli/commands/ddn_codemod_rename-graphql-prefixes) - Rename GraphQL - root field and type name prefixes in metadata -- [ddn codemod upgrade-context-v2-to-v3](/reference/cli/commands/ddn_codemod_upgrade-context-v2-to-v3) - Upgrade - project's context config from v2 to v3 -- [ddn codemod upgrade-graphqlconfig-aggregate](/reference/cli/commands/ddn_codemod_upgrade-graphqlconfig-aggregate) - - Upgrade GraphqlConfig to support aggregates -- [ddn codemod upgrade-graphqlconfig-subscriptions](/reference/cli/commands/ddn_codemod_upgrade-graphqlconfig-subscriptions) - - Upgrade GraphqlConfig to support subscriptions -- [ddn codemod upgrade-model-v1-to-v2](/reference/cli/commands/ddn_codemod_upgrade-model-v1-to-v2) - Upgrade model from - "version" "v1" to "v2" in metadata -- [ddn codemod upgrade-object-boolean-expression-types](/reference/cli/commands/ddn_codemod_upgrade-object-boolean-expression-types) - - Upgrade object boolean expression types metadata -- [ddn codemod upgrade-project-config-v2-to-v3](/reference/cli/commands/ddn_codemod_upgrade-project-config-v2-to-v3) - - Upgrade project directory from version v2 to v3 -- [ddn codemod upgrade-supergraph-config-v1-to-v2](/reference/cli/commands/ddn_codemod_upgrade-supergraph-config-v1-to-v2) - - Upgrade all Supergraph config files at the root of the project directory from v1 to v2 +- [ddn codemod configure-header-forwarding](/reference/cli/commands/ddn_codemod_configure-header-forwarding) - Configure headers to be forwarded to your connector +- [ddn codemod fix-traces-env-var](/reference/cli/commands/ddn_codemod_fix-traces-env-var) - Fix env var used for configuring traces for connectors +- [ddn codemod rename-graphql-prefixes](/reference/cli/commands/ddn_codemod_rename-graphql-prefixes) - Rename GraphQL root field and type name prefixes in metadata +- [ddn codemod upgrade-context-v2-to-v3](/reference/cli/commands/ddn_codemod_upgrade-context-v2-to-v3) - Upgrade project's context config from v2 to v3 +- [ddn codemod upgrade-graphqlconfig-aggregate](/reference/cli/commands/ddn_codemod_upgrade-graphqlconfig-aggregate) - Upgrade GraphqlConfig to support aggregates +- [ddn codemod upgrade-graphqlconfig-subscriptions](/reference/cli/commands/ddn_codemod_upgrade-graphqlconfig-subscriptions) - Upgrade GraphqlConfig to support subscriptions +- [ddn codemod upgrade-model-v1-to-v2](/reference/cli/commands/ddn_codemod_upgrade-model-v1-to-v2) - Upgrade model from "version" "v1" to "v2" in metadata +- [ddn codemod upgrade-object-boolean-expression-types](/reference/cli/commands/ddn_codemod_upgrade-object-boolean-expression-types) - Upgrade object boolean expression types metadata +- [ddn codemod upgrade-project-config-v2-to-v3](/reference/cli/commands/ddn_codemod_upgrade-project-config-v2-to-v3) - Upgrade project directory from version v2 to v3 +- [ddn codemod upgrade-supergraph-config-v1-to-v2](/reference/cli/commands/ddn_codemod_upgrade-supergraph-config-v1-to-v2) - Upgrade all Supergraph config files at the root of the project directory from v1 to v2 ## Options diff --git a/docs/reference/cli/commands/ddn_codemod_rename-graphql-prefixes.mdx b/docs/reference/cli/commands/ddn_codemod_rename-graphql-prefixes.mdx index ff9e446bd..2068c3930 100644 --- a/docs/reference/cli/commands/ddn_codemod_rename-graphql-prefixes.mdx +++ b/docs/reference/cli/commands/ddn_codemod_rename-graphql-prefixes.mdx @@ -16,8 +16,7 @@ Rename GraphQL root field and type name prefixes in metadata. ## Synopsis -Rename GraphQL root field and type name prefixes in metadata. The from prefix will be stripped if provided, and the new -prefix will be added. If the new prefix is already present, it will not be reapplied. +Rename GraphQL root field and type name prefixes in metadata. The from prefix will be stripped if provided, and the new prefix will be added. If the new prefix is already present, it will not be reapplied. By default, subgraph.yaml is updated with the new prefixes. diff --git a/docs/reference/cli/commands/ddn_command.mdx b/docs/reference/cli/commands/ddn_command.mdx index 351a73565..7fac32812 100644 --- a/docs/reference/cli/commands/ddn_command.mdx +++ b/docs/reference/cli/commands/ddn_command.mdx @@ -23,12 +23,9 @@ Perform Command related operations ## Available operations - [ddn command add](/reference/cli/commands/ddn_command_add) - Add new Commands to the local metadata -- [ddn command list](/reference/cli/commands/ddn_command_list) - Lists details about the functions/procedures of - DataConnectorLink, and their corresponding Commands -- [ddn command remove](/reference/cli/commands/ddn_command_remove) - Removes Commands (and related metadata) in the - local metadata -- [ddn command show](/reference/cli/commands/ddn_command_show) - Show diff between the command and its corresponding ndc - function/procedure +- [ddn command list](/reference/cli/commands/ddn_command_list) - Lists details about the functions/procedures of DataConnectorLink, and their corresponding Commands +- [ddn command remove](/reference/cli/commands/ddn_command_remove) - Removes Commands (and related metadata) in the local metadata +- [ddn command show](/reference/cli/commands/ddn_command_show) - Show diff between the command and its corresponding ndc function/procedure - [ddn command update](/reference/cli/commands/ddn_command_update) - Update Commands in the local metadata ## Options diff --git a/docs/reference/cli/commands/ddn_command_list.mdx b/docs/reference/cli/commands/ddn_command_list.mdx index c412f6a2a..b0e3a2f2e 100644 --- a/docs/reference/cli/commands/ddn_command_list.mdx +++ b/docs/reference/cli/commands/ddn_command_list.mdx @@ -1,8 +1,7 @@ --- sidebar_label: ddn command list sidebar_position: 22 -description: - Lists details about the functions/procedures of DataConnectorLink, and their corresponding Commands using the DDN CLI +description: Lists details about the functions/procedures of DataConnectorLink, and their corresponding Commands using the DDN CLI keywords: - hasura - DDN diff --git a/docs/reference/cli/commands/ddn_connector-link.mdx b/docs/reference/cli/commands/ddn_connector-link.mdx index 9402d612b..0c861c9bf 100644 --- a/docs/reference/cli/commands/ddn_connector-link.mdx +++ b/docs/reference/cli/commands/ddn_connector-link.mdx @@ -23,13 +23,10 @@ Perform DataConnectorLink related operations ## Available operations - [ddn connector-link add](/reference/cli/commands/ddn_connector-link_add) - Add a new DataConnectorLink to a Subgraph -- [ddn connector-link add-resources](/reference/cli/commands/ddn_connector-link_add-resources) - Add all models, - commands and relationships from a DataConnectorLink's schema -- [ddn connector-link remove](/reference/cli/commands/ddn_connector-link_remove) - Remove a DataConnectorLink from a - Subgraph +- [ddn connector-link add-resources](/reference/cli/commands/ddn_connector-link_add-resources) - Add all models, commands and relationships from a DataConnectorLink's schema +- [ddn connector-link remove](/reference/cli/commands/ddn_connector-link_remove) - Remove a DataConnectorLink from a Subgraph - [ddn connector-link show](/reference/cli/commands/ddn_connector-link_show) - Show DataConnectorLink details -- [ddn connector-link update](/reference/cli/commands/ddn_connector-link_update) - Fetch NDC details from the Connector - and update the DataConnectorLink +- [ddn connector-link update](/reference/cli/commands/ddn_connector-link_update) - Fetch NDC details from the Connector and update the DataConnectorLink ## Options diff --git a/docs/reference/cli/commands/ddn_connector.mdx b/docs/reference/cli/commands/ddn_connector.mdx index d8116dd54..2cacd1430 100644 --- a/docs/reference/cli/commands/ddn_connector.mdx +++ b/docs/reference/cli/commands/ddn_connector.mdx @@ -25,13 +25,10 @@ Perform Connector related operations - [ddn connector build](/reference/cli/commands/ddn_connector_build) - Perform ConnectorBuild related operations - [ddn connector env](/reference/cli/commands/ddn_connector_env) - Manage environment variables for Connectors - [ddn connector init](/reference/cli/commands/ddn_connector_init) - Add a new Connector -- [ddn connector introspect](/reference/cli/commands/ddn_connector_introspect) - Introspect the Connector data source to - update the Connector configuration +- [ddn connector introspect](/reference/cli/commands/ddn_connector_introspect) - Introspect the Connector data source to update the Connector configuration - [ddn connector plugin](/reference/cli/commands/ddn_connector_plugin) - Run a subcommand from a Connector plugin -- [ddn connector remove](/reference/cli/commands/ddn_connector_remove) - Remove a Connector, its corresponding - DataConnectorLink and all its associated metadata objects -- [ddn connector setenv](/reference/cli/commands/ddn_connector_setenv) - Run specified command with environment - variables set +- [ddn connector remove](/reference/cli/commands/ddn_connector_remove) - Remove a Connector, its corresponding DataConnectorLink and all its associated metadata objects +- [ddn connector setenv](/reference/cli/commands/ddn_connector_setenv) - Run specified command with environment variables set - [ddn connector show-resources](/reference/cli/commands/ddn_connector_show-resources) - Show resources of a Connector ## Options diff --git a/docs/reference/cli/commands/ddn_connector_build.mdx b/docs/reference/cli/commands/ddn_connector_build.mdx index 037b4c890..f08b133ce 100644 --- a/docs/reference/cli/commands/ddn_connector_build.mdx +++ b/docs/reference/cli/commands/ddn_connector_build.mdx @@ -20,14 +20,10 @@ Perform ConnectorBuild related operations ## Available operations -- [ddn connector build create](/reference/cli/commands/ddn_connector_build_create) - Create a ConnectorBuild on Hasura - DDN -- [ddn connector build delete](/reference/cli/commands/ddn_connector_build_delete) - Delete a ConnectorBuild from a - Project -- [ddn connector build get](/reference/cli/commands/ddn_connector_build_get) - List ConnectorBuilds or get details of a - specific one from Hasura DDN -- [ddn connector build logs](/reference/cli/commands/ddn_connector_build_logs) - Get logs of a ConnectorBuild from - Hasura DDN +- [ddn connector build create](/reference/cli/commands/ddn_connector_build_create) - Create a ConnectorBuild on Hasura DDN +- [ddn connector build delete](/reference/cli/commands/ddn_connector_build_delete) - Delete a ConnectorBuild from a Project +- [ddn connector build get](/reference/cli/commands/ddn_connector_build_get) - List ConnectorBuilds or get details of a specific one from Hasura DDN +- [ddn connector build logs](/reference/cli/commands/ddn_connector_build_logs) - Get logs of a ConnectorBuild from Hasura DDN ## Options diff --git a/docs/reference/cli/commands/ddn_connector_env.mdx b/docs/reference/cli/commands/ddn_connector_env.mdx index 596a8a45d..14d37b92c 100644 --- a/docs/reference/cli/commands/ddn_connector_env.mdx +++ b/docs/reference/cli/commands/ddn_connector_env.mdx @@ -20,8 +20,7 @@ Manage environment variables for Connectors ## Available operations -- [ddn connector env add](/reference/cli/commands/ddn_connector_env_add) - Add environment variables and its - corresponding mapping to a Connector +- [ddn connector env add](/reference/cli/commands/ddn_connector_env_add) - Add environment variables and its corresponding mapping to a Connector ## Options diff --git a/docs/reference/cli/commands/ddn_connector_init.mdx b/docs/reference/cli/commands/ddn_connector_init.mdx index 88a4db4e3..2eab1fd67 100644 --- a/docs/reference/cli/commands/ddn_connector_init.mdx +++ b/docs/reference/cli/commands/ddn_connector_init.mdx @@ -35,7 +35,7 @@ ddn connector init [connector-name] --hub-connector [flags] ddn connector init mydb --dir ./connector --hub-connector hasura/postgres # Initialize a NodeJS Connector "mylambda" in the Subgraph "app" on port 8765 - ddn connector init mylambda --subgraph ./app/subgraph.yaml --hub-connector hasura/nodejs --configure-port 8765 + ddn connector init mylambda --subgraph ./app/subgraph.yaml --hub-connector hasura/nodejs --configure-port 8765 ``` ## Options diff --git a/docs/reference/cli/commands/ddn_connector_remove.mdx b/docs/reference/cli/commands/ddn_connector_remove.mdx index 1c1e99588..72920778a 100644 --- a/docs/reference/cli/commands/ddn_connector_remove.mdx +++ b/docs/reference/cli/commands/ddn_connector_remove.mdx @@ -1,8 +1,7 @@ --- sidebar_label: ddn connector remove sidebar_position: 37 -description: - Remove a Connector, its corresponding DataConnectorLink and all its associated metadata objects using the DDN CLI +description: Remove a Connector, its corresponding DataConnectorLink and all its associated metadata objects using the DDN CLI keywords: - hasura - DDN diff --git a/docs/reference/cli/commands/ddn_context.mdx b/docs/reference/cli/commands/ddn_context.mdx index c633253b8..81282e642 100644 --- a/docs/reference/cli/commands/ddn_context.mdx +++ b/docs/reference/cli/commands/ddn_context.mdx @@ -22,10 +22,8 @@ Manage default value of keys to be used in DDN CLI commands - [ddn context create-context](/reference/cli/commands/ddn_context_create-context) - Create a new context - [ddn context get](/reference/cli/commands/ddn_context_get) - Get the value of a key in the context -- [ddn context get-context](/reference/cli/commands/ddn_context_get-context) - List contexts or get details of a - specific context -- [ddn context get-current-context](/reference/cli/commands/ddn_context_get-current-context) - Get name and contents of - current context +- [ddn context get-context](/reference/cli/commands/ddn_context_get-context) - List contexts or get details of a specific context +- [ddn context get-current-context](/reference/cli/commands/ddn_context_get-current-context) - Get name and contents of current context - [ddn context set](/reference/cli/commands/ddn_context_set) - Set the value of a key in the context - [ddn context set-current-context](/reference/cli/commands/ddn_context_set-current-context) - Set the current context - [ddn context unset](/reference/cli/commands/ddn_context_unset) - Unset the value of a key in the context diff --git a/docs/reference/cli/commands/ddn_context_unset.mdx b/docs/reference/cli/commands/ddn_context_unset.mdx index d3d3b204a..8a6b28dc8 100644 --- a/docs/reference/cli/commands/ddn_context_unset.mdx +++ b/docs/reference/cli/commands/ddn_context_unset.mdx @@ -19,7 +19,7 @@ Unset the value of a key in the context. Unset the value of a key in the context ```bash -ddn context unset (Allowed keys: selfHostedDataPlane, project, supergraph, subgraph, localEnvFile, cloudEnvFile) [flags] +ddn context unset (Allowed keys: localEnvFile, cloudEnvFile, selfHostedDataPlane, project, supergraph, subgraph) [flags] ``` ## Examples diff --git a/docs/reference/cli/commands/ddn_doctor.mdx b/docs/reference/cli/commands/ddn_doctor.mdx index b86d6c131..1fa0ac267 100644 --- a/docs/reference/cli/commands/ddn_doctor.mdx +++ b/docs/reference/cli/commands/ddn_doctor.mdx @@ -16,8 +16,7 @@ Check if the dependencies of DDN CLI are present. ## Synopsis -Check if the dependencies (Docker and Docker Compose) of DDN CLI are installed, are of the required version and if they -are running. +Check if the dependencies (Docker and Docker Compose) of DDN CLI are installed, are of the required version and if they are running. ```bash ddn doctor [flags] diff --git a/docs/reference/cli/commands/ddn_model.mdx b/docs/reference/cli/commands/ddn_model.mdx index 389e50947..6f20276ba 100644 --- a/docs/reference/cli/commands/ddn_model.mdx +++ b/docs/reference/cli/commands/ddn_model.mdx @@ -23,12 +23,9 @@ Perform Model related operations ## Available operations - [ddn model add](/reference/cli/commands/ddn_model_add) - Add new Models to the local metadata -- [ddn model list](/reference/cli/commands/ddn_model_list) - Lists details about the collections of DataConnectorLink, - and their corresponding Models -- [ddn model remove](/reference/cli/commands/ddn_model_remove) - Removes Models (and related metadata) in the local - metadata -- [ddn model show](/reference/cli/commands/ddn_model_show) - Show diff between the model and its corresponding ndc - collection +- [ddn model list](/reference/cli/commands/ddn_model_list) - Lists details about the collections of DataConnectorLink, and their corresponding Models +- [ddn model remove](/reference/cli/commands/ddn_model_remove) - Removes Models (and related metadata) in the local metadata +- [ddn model show](/reference/cli/commands/ddn_model_show) - Show diff between the model and its corresponding ndc collection - [ddn model update](/reference/cli/commands/ddn_model_update) - Update Models in the local metadata ## Options diff --git a/docs/reference/cli/commands/ddn_plugins.mdx b/docs/reference/cli/commands/ddn_plugins.mdx index 4ce837697..62cd38311 100644 --- a/docs/reference/cli/commands/ddn_plugins.mdx +++ b/docs/reference/cli/commands/ddn_plugins.mdx @@ -16,8 +16,7 @@ Manage plugins for the CLI. ## Synopsis -The functionality of the CLI can be extended by using plugins. For a list of all available plugins, run -`ddn plugins list`, or visit this repository: https://github.com/hasura/cli-plugins-index. +The functionality of the CLI can be extended by using plugins. For a list of all available plugins, run ``ddn plugins list``, or visit this repository: https://github.com/hasura/cli-plugins-index. If you're interested in contributing, please open a PR against this repo. @@ -26,8 +25,7 @@ If you're interested in contributing, please open a PR against this repo. ## Available operations - [ddn plugins install](/reference/cli/commands/ddn_plugins_install) - Install a plugin from the index -- [ddn plugins list](/reference/cli/commands/ddn_plugins_list) - List all available plugins with index, versions and - installation status +- [ddn plugins list](/reference/cli/commands/ddn_plugins_list) - List all available plugins with index, versions and installation status - [ddn plugins uninstall](/reference/cli/commands/ddn_plugins_uninstall) - Uninstall a plugin - [ddn plugins upgrade](/reference/cli/commands/ddn_plugins_upgrade) - Upgrade a plugin to a newer version diff --git a/docs/reference/cli/commands/ddn_plugins_install.mdx b/docs/reference/cli/commands/ddn_plugins_install.mdx index 3d4336fc3..260f143ec 100644 --- a/docs/reference/cli/commands/ddn_plugins_install.mdx +++ b/docs/reference/cli/commands/ddn_plugins_install.mdx @@ -16,8 +16,7 @@ Install a plugin from the index. ## Synopsis -To install plugins that extend the functionality of the DDN CLI, you can use the install command. This command will -install the plugin from the index and add it to your configuration file. +To install plugins that extend the functionality of the DDN CLI, you can use the install command. This command will install the plugin from the index and add it to your configuration file. ```bash ddn plugins install [flags] diff --git a/docs/reference/cli/commands/ddn_plugins_list.mdx b/docs/reference/cli/commands/ddn_plugins_list.mdx index 57a083da4..d9e384cf1 100644 --- a/docs/reference/cli/commands/ddn_plugins_list.mdx +++ b/docs/reference/cli/commands/ddn_plugins_list.mdx @@ -16,8 +16,7 @@ List all available plugins with index, versions and installation status. ## Synopsis -Run the plugins list command to see a list of all the available plugins which extend the functionality of the CLI, their -versions and installation status. +Run the plugins list command to see a list of all the available plugins which extend the functionality of the CLI, their versions and installation status. ```bash ddn plugins list [flags] diff --git a/docs/reference/cli/commands/ddn_plugins_uninstall.mdx b/docs/reference/cli/commands/ddn_plugins_uninstall.mdx index 31deca15d..8043d94b8 100644 --- a/docs/reference/cli/commands/ddn_plugins_uninstall.mdx +++ b/docs/reference/cli/commands/ddn_plugins_uninstall.mdx @@ -16,8 +16,7 @@ Uninstall a plugin. ## Synopsis -To uninstall a plugin, run the uninstall command with the name of the plugin as an argument. If unsure of the plugin's -name, you can run the `ddn plugins list` command to see a list of all the available plugins. +To uninstall a plugin, run the uninstall command with the name of the plugin as an argument. If unsure of the plugin's name, you can run the `ddn plugins list` command to see a list of all the available plugins. ```bash ddn plugins uninstall [flags] diff --git a/docs/reference/cli/commands/ddn_plugins_upgrade.mdx b/docs/reference/cli/commands/ddn_plugins_upgrade.mdx index 39585e6ba..936f1144e 100644 --- a/docs/reference/cli/commands/ddn_plugins_upgrade.mdx +++ b/docs/reference/cli/commands/ddn_plugins_upgrade.mdx @@ -16,8 +16,7 @@ Upgrade a plugin to a newer version. ## Synopsis -To upgrade a plugin, run the upgrade command with the name of the plugin as an argument. If unsure of the plugin's name, -you can run the `ddn plugins list` command to see a list of all the available plugins. +To upgrade a plugin, run the upgrade command with the name of the plugin as an argument. If unsure of the plugin's name, you can run the `ddn plugins list` command to see a list of all the available plugins. ```bash ddn plugins upgrade [flags] diff --git a/docs/reference/cli/commands/ddn_project.mdx b/docs/reference/cli/commands/ddn_project.mdx index 816d650fa..8d9c33fba 100644 --- a/docs/reference/cli/commands/ddn_project.mdx +++ b/docs/reference/cli/commands/ddn_project.mdx @@ -23,12 +23,9 @@ Manage Hasura DDN Project - [ddn project create](/reference/cli/commands/ddn_project_create) - Create a new Project on Hasura DDN - [ddn project delete](/reference/cli/commands/ddn_project_delete) - Delete a Project on Hasura DDN - [ddn project get](/reference/cli/commands/ddn_project_get) - List Hasura DDN Projects or get details of a specific one -- [ddn project init](/reference/cli/commands/ddn_project_init) - Configure the local directory to use a Hasura DDN - project, creating a DDN project and subgraphs as necessary -- [ddn project set-api-access-mode](/reference/cli/commands/ddn_project_set-api-access-mode) - Set the API access mode - for a Project on Hasura DDN -- [ddn project set-self-hosted-engine-url](/reference/cli/commands/ddn_project_set-self-hosted-engine-url) - Set the - engine's URL for a project in a self hosted data plane. +- [ddn project init](/reference/cli/commands/ddn_project_init) - Configure the local directory to use a Hasura DDN project, creating a DDN project and subgraphs as necessary +- [ddn project set-api-access-mode](/reference/cli/commands/ddn_project_set-api-access-mode) - Set the API access mode for a Project on Hasura DDN +- [ddn project set-self-hosted-engine-url](/reference/cli/commands/ddn_project_set-self-hosted-engine-url) - Set the engine's URL for a project in a self hosted data plane. - [ddn project subgraph](/reference/cli/commands/ddn_project_subgraph) - Manage Subgraphs in a Hasura DDN Project ## Options diff --git a/docs/reference/cli/commands/ddn_project_init.mdx b/docs/reference/cli/commands/ddn_project_init.mdx index f9344f143..459da518c 100644 --- a/docs/reference/cli/commands/ddn_project_init.mdx +++ b/docs/reference/cli/commands/ddn_project_init.mdx @@ -1,9 +1,7 @@ --- sidebar_label: ddn project init sidebar_position: 76 -description: - Configure the local directory to use a Hasura DDN project, creating a DDN project and subgraphs as necessary using the - DDN CLI +description: Configure the local directory to use a Hasura DDN project, creating a DDN project and subgraphs as necessary using the DDN CLI keywords: - hasura - DDN diff --git a/docs/reference/cli/commands/ddn_project_subgraph.mdx b/docs/reference/cli/commands/ddn_project_subgraph.mdx index 4a42fea6d..c558d8bc6 100644 --- a/docs/reference/cli/commands/ddn_project_subgraph.mdx +++ b/docs/reference/cli/commands/ddn_project_subgraph.mdx @@ -20,11 +20,9 @@ Manage Subgraphs in a Hasura DDN Project ## Available operations -- [ddn project subgraph create](/reference/cli/commands/ddn_project_subgraph_create) - Create a new Subgraph in a Hasura - DDN Project +- [ddn project subgraph create](/reference/cli/commands/ddn_project_subgraph_create) - Create a new Subgraph in a Hasura DDN Project - [ddn project subgraph delete](/reference/cli/commands/ddn_project_subgraph_delete) - Delete a Subgraph from a Project -- [ddn project subgraph get](/reference/cli/commands/ddn_project_subgraph_get) - List Subgraphs for a Hasura DDN Project - or get details of a specific one +- [ddn project subgraph get](/reference/cli/commands/ddn_project_subgraph_get) - List Subgraphs for a Hasura DDN Project or get details of a specific one ## Options diff --git a/docs/reference/cli/commands/ddn_relationship.mdx b/docs/reference/cli/commands/ddn_relationship.mdx index 506d8b88d..a8b5b6a45 100644 --- a/docs/reference/cli/commands/ddn_relationship.mdx +++ b/docs/reference/cli/commands/ddn_relationship.mdx @@ -22,10 +22,8 @@ Perform Relationship related operations ## Available operations -- [ddn relationship add](/reference/cli/commands/ddn_relationship_add) - Adds Relationships from foreign keys on - collection-name or targeting collection-name -- [ddn relationship list](/reference/cli/commands/ddn_relationship_list) - Lists Relationships for a given - DataConnectorLink +- [ddn relationship add](/reference/cli/commands/ddn_relationship_add) - Adds Relationships from foreign keys on collection-name or targeting collection-name +- [ddn relationship list](/reference/cli/commands/ddn_relationship_list) - Lists Relationships for a given DataConnectorLink ## Options diff --git a/docs/reference/cli/commands/ddn_subgraph_build.mdx b/docs/reference/cli/commands/ddn_subgraph_build.mdx index 238ea02b5..a3380938d 100644 --- a/docs/reference/cli/commands/ddn_subgraph_build.mdx +++ b/docs/reference/cli/commands/ddn_subgraph_build.mdx @@ -22,8 +22,7 @@ Perform SubgraphBuild related operations - [ddn subgraph build apply](/reference/cli/commands/ddn_subgraph_build_apply) - Apply a Subgraph build on Hasura DDN - [ddn subgraph build create](/reference/cli/commands/ddn_subgraph_build_create) - Create a SubgraphBuild on Hasura DDN -- [ddn subgraph build get](/reference/cli/commands/ddn_subgraph_build_get) - List SubgraphBuilds or get details of a - specific one +- [ddn subgraph build get](/reference/cli/commands/ddn_subgraph_build_get) - List SubgraphBuilds or get details of a specific one ## Options diff --git a/docs/reference/cli/commands/ddn_supergraph_build.mdx b/docs/reference/cli/commands/ddn_supergraph_build.mdx index b1287ec7e..c78bc887d 100644 --- a/docs/reference/cli/commands/ddn_supergraph_build.mdx +++ b/docs/reference/cli/commands/ddn_supergraph_build.mdx @@ -20,20 +20,13 @@ Perform SupergraphBuild related operations ## Available operations -- [ddn supergraph build apply](/reference/cli/commands/ddn_supergraph_build_apply) - Apply a SupergraphBuild to its - Project on Hasura DDN -- [ddn supergraph build create](/reference/cli/commands/ddn_supergraph_build_create) - Create a SupergraphBuild on - Hasura DDN -- [ddn supergraph build delete](/reference/cli/commands/ddn_supergraph_build_delete) - Delete a SupergraphBuild from a - Project -- [ddn supergraph build diff](/reference/cli/commands/ddn_supergraph_build_diff) - See changes made to the GraphQL - schema from one build version to another. -- [ddn supergraph build get](/reference/cli/commands/ddn_supergraph_build_get) - List SupergraphBuilds or get details of - a specific one -- [ddn supergraph build local](/reference/cli/commands/ddn_supergraph_build_local) - Build the Supergraph and generate - assets to run the local Engine -- [ddn supergraph build set-self-hosted-engine-url](/reference/cli/commands/ddn_supergraph_build_set-self-hosted-engine-url) - - Set the engine's URL for a build for a project in a self hosted data plane. +- [ddn supergraph build apply](/reference/cli/commands/ddn_supergraph_build_apply) - Apply a SupergraphBuild to its Project on Hasura DDN +- [ddn supergraph build create](/reference/cli/commands/ddn_supergraph_build_create) - Create a SupergraphBuild on Hasura DDN +- [ddn supergraph build delete](/reference/cli/commands/ddn_supergraph_build_delete) - Delete a SupergraphBuild from a Project +- [ddn supergraph build diff](/reference/cli/commands/ddn_supergraph_build_diff) - See changes made to the GraphQL schema from one build version to another. +- [ddn supergraph build get](/reference/cli/commands/ddn_supergraph_build_get) - List SupergraphBuilds or get details of a specific one +- [ddn supergraph build local](/reference/cli/commands/ddn_supergraph_build_local) - Build the Supergraph and generate assets to run the local Engine +- [ddn supergraph build set-self-hosted-engine-url](/reference/cli/commands/ddn_supergraph_build_set-self-hosted-engine-url) - Set the engine's URL for a build for a project in a self hosted data plane. ## Options From 83b3522e6e6d995b34183c84109057e5055af261 Mon Sep 17 00:00:00 2001 From: Krushan Bauva Date: Fri, 7 Feb 2025 09:47:06 +0530 Subject: [PATCH 3/5] docs: update references to "PAT" with "access token" (#871) --- docs/collaboration/service-accounts.mdx | 2 +- docs/deployment/self-hosted/docker-compose-simple.mdx | 4 ++-- docs/plugins/allowlist/how-to.mdx | 2 +- docs/plugins/restified-endpoints/how-to.mdx | 2 +- .../upgrading-project-config/upgrade-context-v3.mdx | 4 ++-- .../project-config/independent-connector-deployment.mdx | 4 ++-- docs/reference/cli/faq.mdx | 4 ++-- 7 files changed, 11 insertions(+), 11 deletions(-) diff --git a/docs/collaboration/service-accounts.mdx b/docs/collaboration/service-accounts.mdx index 7174dd625..8b01decb7 100644 --- a/docs/collaboration/service-accounts.mdx +++ b/docs/collaboration/service-accounts.mdx @@ -100,7 +100,7 @@ collaborator. ### Step 1. Login via CLI ```bash -ddn auth login --pat +ddn auth login --access-token ``` ### Step 2. Create and apply supergraph build diff --git a/docs/deployment/self-hosted/docker-compose-simple.mdx b/docs/deployment/self-hosted/docker-compose-simple.mdx index 34fe6b075..a29c29156 100644 --- a/docs/deployment/self-hosted/docker-compose-simple.mdx +++ b/docs/deployment/self-hosted/docker-compose-simple.mdx @@ -77,13 +77,13 @@ browser, you will need to use a personal access token. On your local machine, once you are logged in with `ddn auth login` run: ```bash -ddn auth print-pat +ddn auth print-access-token ``` This will print out your personal access token. Copy it and on the cloud server run: ```bash -ddn auth login --pat +ddn auth login --access-token ``` This will authenticate the DDN CLI with your Hasura account. diff --git a/docs/plugins/allowlist/how-to.mdx b/docs/plugins/allowlist/how-to.mdx index 736e0f4a8..3760c4653 100644 --- a/docs/plugins/allowlist/how-to.mdx +++ b/docs/plugins/allowlist/how-to.mdx @@ -175,7 +175,7 @@ OTEL_EXPORTER_PAT = "" ``` Replace `` with the Personal Access Token (PAT) for the Hasura Cloud account. You can generate this using the -`ddn auth print-pat` command. +`ddn auth print-access-token` command. ## Step 7. Deploy the plugin diff --git a/docs/plugins/restified-endpoints/how-to.mdx b/docs/plugins/restified-endpoints/how-to.mdx index 75413c74a..901d5a0d9 100644 --- a/docs/plugins/restified-endpoints/how-to.mdx +++ b/docs/plugins/restified-endpoints/how-to.mdx @@ -221,7 +221,7 @@ OTEL_EXPORTER_PAT = "" ``` Replace `` with the Personal Access Token (PAT) for the Hasura Cloud account. You can display this using the -`ddn auth print-pat` command. +`ddn auth print-access-token` command. ## Step 7. Deploy the plugin diff --git a/docs/project-configuration/upgrading-project-config/upgrade-context-v3.mdx b/docs/project-configuration/upgrading-project-config/upgrade-context-v3.mdx index e1e3999a3..998239087 100644 --- a/docs/project-configuration/upgrading-project-config/upgrade-context-v3.mdx +++ b/docs/project-configuration/upgrading-project-config/upgrade-context-v3.mdx @@ -49,8 +49,8 @@ definition: localEnvFile: ../.env scripts: docker-start: - bash: HASURA_DDN_PAT=$(ddn auth print-pat) docker compose --env-file .env up --build --pull always -d - powershell: $Env:HASURA_DDN_PAT = (ddn auth print-pat); docker compose --env-file .env up --build --pull always -d + bash: HASURA_DDN_PAT=$(ddn auth print-access-token) docker compose --env-file .env up --build --pull always -d + powershell: $Env:HASURA_DDN_PAT = (ddn auth print-access-token); docker compose --env-file .env up --build --pull always -d ``` #### Running Scripts diff --git a/docs/recipes/project-config/independent-connector-deployment.mdx b/docs/recipes/project-config/independent-connector-deployment.mdx index c335e3866..231c7c179 100644 --- a/docs/recipes/project-config/independent-connector-deployment.mdx +++ b/docs/recipes/project-config/independent-connector-deployment.mdx @@ -138,8 +138,8 @@ definition: default: ... scripts: docker-start: - bash: HASURA_DDN_PAT=$(ddn auth print-pat) docker compose --env-file .env up --build --pull always -d - powershell: $Env:HASURA_DDN_PAT = (ddn auth print-pat); docker compose --env-file .env up --build --pull always -d + bash: HASURA_DDN_PAT=$(ddn auth print-access-token) docker compose --env-file .env up --build --pull always -d + powershell: $Env:HASURA_DDN_PAT = (ddn auth print-access-token); docker compose --env-file .env up --build --pull always -d #highlight-start build-supergraph: bash: diff --git a/docs/reference/cli/faq.mdx b/docs/reference/cli/faq.mdx index 804ab283e..6f87700b2 100644 --- a/docs/reference/cli/faq.mdx +++ b/docs/reference/cli/faq.mdx @@ -153,12 +153,12 @@ Traces are then exported to a cloud endpoint by the OpenTelemetry container as d If you are not able to see traces during local development: -1. Make sure you are logged in to the DDN CLI. You can check this with `ddn auth print-pat`. If not, log in by running +1. Make sure you are logged in to the DDN CLI. You can check this with `ddn auth print-access-token`. If not, log in by running `ddn auth login`. 2. Make sure that your OpenTelemetry Collector container is running. 3. If you are running the docker compose command directly, then make sure that the environment variable `HASURA_DDN_PAT` is passed to the OpenTelemetry Collector container. The value for this env var would be the output of the - `ddn auth print-pat` command. If you are running `ddn run docker-start`, then this is already handled for you. + `ddn auth print-access-token` command. If you are running `ddn run docker-start`, then this is already handled for you. 4. If you are seeing the issue when running `ddn run docker-start`, then it could be due to the `docker-start` script using a [different binary to the one defined in the current shell](#docker-start-different-binary). From dc1bfa9fc30c73360d908207efe504c12720d600 Mon Sep 17 00:00:00 2001 From: pranshi06 <85474619+pranshi06@users.noreply.github.com> Date: Fri, 7 Feb 2025 18:31:37 +0530 Subject: [PATCH 4/5] Initial MySQL configuration docs (#881) Co-authored-by: py --- docs/reference/connectors/index.mdx | 3 +- .../connectors/mysql/_category_.json | 4 + .../connectors/mysql/configuration.mdx | 219 ++++++++++++++++++ docs/reference/connectors/mysql/index.mdx | 25 ++ docs/reference/connectors/oracle/index.mdx | 2 +- .../connectors/postgresql/_category_.json | 2 +- 6 files changed, 252 insertions(+), 3 deletions(-) create mode 100644 docs/reference/connectors/mysql/_category_.json create mode 100644 docs/reference/connectors/mysql/configuration.mdx create mode 100644 docs/reference/connectors/mysql/index.mdx diff --git a/docs/reference/connectors/index.mdx b/docs/reference/connectors/index.mdx index bf9e94f12..2cb8e3340 100644 --- a/docs/reference/connectors/index.mdx +++ b/docs/reference/connectors/index.mdx @@ -27,5 +27,6 @@ If you're getting started with a connector and want to connect it to your data s - [ClickHouse](/reference/connectors/clickhouse/index.mdx) - [MongoDB](/reference/connectors/mongodb/index.mdx) -- [PostgreSQL](/reference/connectors/postgresql/index.mdx) +- [MySQL](/reference/connectors/mysql/index.mdx) - [Oracle](/reference/connectors/oracle/index.mdx) +- [PostgreSQL](/reference/connectors/postgresql/index.mdx) diff --git a/docs/reference/connectors/mysql/_category_.json b/docs/reference/connectors/mysql/_category_.json new file mode 100644 index 000000000..0d54f8f1c --- /dev/null +++ b/docs/reference/connectors/mysql/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "MySQL", + "position": 3 +} \ No newline at end of file diff --git a/docs/reference/connectors/mysql/configuration.mdx b/docs/reference/connectors/mysql/configuration.mdx new file mode 100644 index 000000000..ca2c91c1c --- /dev/null +++ b/docs/reference/connectors/mysql/configuration.mdx @@ -0,0 +1,219 @@ +--- +sidebar_position: 2 +sidebar_label: Configuration +description: + "Reference documentation for the setup process for the Hasura MySQL connector, including connection URI details, and + native queries." +keywords: + - mysql + - configuration +--- + +# Configuration Reference + +## Introduction + +The configuration is a metadata object that lists all the database entities — such as tables — that the data connector +has to know about in order to serve queries. It never changes during the lifetime of the data connector service +instance. When your database schema changes you will have to update the configuration accordingly, see +[updating with introspection](#updating-with-introspection). + +## Structure + +The configuration object is a JSON object with the following fields: + +```json +{ + "jdbcUrl": "", + "jdbcProperties": {}, + "schemas": [], + "tables": [], + "functions": [], + "nativeQueries": {} +} +``` + +### Property: JDBC URL + +The JDBC connection URL to connect to the MySQL database. This is a required field. + +The value can either be a literal string, or a reference to an environment variable: + +```json +{ + "jdbcUrl": "jdbc:MySQL:thin:@//localhost:1521/xe?user=foo&password=bar", + "jdbcUrl": { "variable": "MYSQL_JDBC_URL" } +} +``` + +### Property: JDBC Properties + +This is a JSON object containing key-value pairs of additional properties to be passed to the JDBC driver. For example, +with MySQL to enable running multiple statements in a given query: + +```json +{ + "jdbcProperties": { "allowMultiQueries": "true" } +} +``` + +### Property: Schemas + +This is an optional array of schema names to include in the introspection process. If not provided, all schemas will be +included. + +Example: + +```json +{ + "schemas": ["public", "other_schema"] +} +``` + +### Property: Tables + +This is an array of table definitions, generated automatically during introspection. + +Example: + +```json +{ + "tableName": "Album", + "tableType": "TABLE", + "description": "", + "columns": [ + { + "name": "AlbumId", + "description": "", + "type": "int", + "numeric_scale": 0, + "nullable": false, + "auto_increment": true, + "is_primarykey": true + }, + { + "name": "Title", + "description": "", + "type": "varchar", + "numeric_scale": null, + "nullable": false, + "auto_increment": false, + "is_primarykey": false + }, + { + "name": "ArtistId", + "description": "", + "type": "int", + "numeric_scale": 0, + "nullable": false, + "auto_increment": false, + "is_primarykey": false + } + ], + "pks": ["AlbumId"], + "fks": { + "FK_AlbumArtistId": { + "foreign_collection": "Artist", + "column_mapping": { + "ArtistId": "ArtistId" + } + } + } +} +``` + +### Property: Functions + +This is an array of function definitions. + +Example: + +```json +{ + "function_catalog": "public", + "function_schema": "public", + "function_name": "add", + "argument_signature": "(N NUMBER, M NUMBER)", + "data_type": "TABLE (N NUMBER, M NUMBER)", + "comment": "Adds two numbers" +} +``` + +### Property: Native Queries + +This is a JSON object containing key-value pairs of Native Queries to be used in the data connector. + +Two types of Native Queries are supported: **Inline** and **Parameterized**. + +Example: + +```json +{ + "native_query_inline": { + "sql": { + "parts": [ + { + "type": "text", + "value": "SELECT 1 AS result FROM DUAL" + } + ] + }, + "columns": { + "result": { + "type": "named", + "name": "INT" + } + }, + "arguments": {}, + "description": "" + }, + "ArtistById_parameterized": { + "sql": { + "parts": [ + { + "type": "text", + "value": "SELECT * FROM CHINOOK.ARTIST WHERE ARTISTID = " + }, + { + "type": "parameter", + "value": "ARTISTID" + } + ] + }, + "columns": { + "ARTISTID": { + "type": "named", + "name": "INT" + }, + "NAME": { + "type": "nullable", + "underlying_type": { + "type": "named", + "name": "STRING" + } + } + }, + "arguments": { + "ARTISTID": { + "description": null, + "type": { + "type": "named", + "name": "INT" + } + } + }, + "description": null, + "isProcedure": false + } +``` + +## Updating with introspection + +Whenever the schema of your database changes you will need to update your data connector configuration accordingly to +reflect those changes. + +Running `update` in a configuration directory will do the following: + +- Connect to the database with the specified `jdbcUrl`, and then overwrite all data in the `tables` field + +- Fill in default values for any fields absent from the configuration diff --git a/docs/reference/connectors/mysql/index.mdx b/docs/reference/connectors/mysql/index.mdx new file mode 100644 index 000000000..27bec034d --- /dev/null +++ b/docs/reference/connectors/mysql/index.mdx @@ -0,0 +1,25 @@ +--- +title: MySQL +sidebar_position: 1 +description: + "Learn how to configure the MySQL connector and utilize native operations to extend your API's capability." +sidebar_label: MySQL +keywords: + - mysql + - configuration + - connector +seoFrontMatterUpdated: false +--- + +# MySQL + +## Introduction + +Hasura DDN includes a Native Data Connector for MySQL, providing integration with MySQL databases. This connector +allows you to leverage MySQL’s powerful relational database capabilities while taking advantage of Hasura’s +metadata-driven approach. Here, we’ll explore the key features of the MySQL connector and walk through the +configuration process within a Hasura DDN project. + +## MySQL docs + +- [Connector configuration](/reference/connectors/mysql/configuration.mdx) diff --git a/docs/reference/connectors/oracle/index.mdx b/docs/reference/connectors/oracle/index.mdx index 83af353e4..d5c8bb3c8 100644 --- a/docs/reference/connectors/oracle/index.mdx +++ b/docs/reference/connectors/oracle/index.mdx @@ -1,6 +1,6 @@ --- title: Oracle -sidebar_position: 4 +sidebar_position: 1 description: "Learn how to configure the Oracle connector and utilize native operations to extend your API's capability." sidebar_label: Oracle diff --git a/docs/reference/connectors/postgresql/_category_.json b/docs/reference/connectors/postgresql/_category_.json index efa776c12..53b0b5bd8 100644 --- a/docs/reference/connectors/postgresql/_category_.json +++ b/docs/reference/connectors/postgresql/_category_.json @@ -1,4 +1,4 @@ { "label": "PostgreSQL", - "position": 3 + "position": 5 } From c6b283755b338b5b0f2776e00befc58c87d3c714 Mon Sep 17 00:00:00 2001 From: Daniel Chambers Date: Sat, 8 Feb 2025 00:08:16 +1100 Subject: [PATCH 5/5] Update compatibility config with new dates (#885) --- .../compatibility-config.mdx | 47 +++++++++++++++++++ 1 file changed, 47 insertions(+) diff --git a/docs/reference/metadata-reference/compatibility-config.mdx b/docs/reference/metadata-reference/compatibility-config.mdx index 5a030904a..f716d31f9 100644 --- a/docs/reference/metadata-reference/compatibility-config.mdx +++ b/docs/reference/metadata-reference/compatibility-config.mdx @@ -31,6 +31,53 @@ will be disabled. To enable these features, simply increase your `date` to a new The following is a list of dates at which backwards-incompatible changes were added to Hasura DDN. Projects with CompatibilityConfig `date`s prior to these dates will have these features disabled. +#### 2025-02-08 + +##### Disallow unsupported orderable relationships + +Build errors are now raised if unsupported orderable relationships are defined on OrderByExpressions. Specifically: + +- If the relationship is a remote relationship +- If the data connector does not support performing relationships +- If the target Model or Command of the relationship does not have a source defined + +##### Disallow relationships where the data connector does not support relationships or remote relationships + +A build error is now raised if a Relationship is defined between an ObjectType and a Model or Command that are sourced +from the same data connector, but that data connector does not support performing relationships or support remote +relationships. + +#### 2025-02-04 + +##### Command and argument preset typechecking + +A build error is now raised if an argument preset defined in CommandPermissions or ModelPermissions or a field preset in +TypePermissions specifies a literal value that does not match the type of the argument or field it is supposed to be +presetting. + +##### Disallow scalar type mismatch in object type fields + +A build error is now raised if an ObjectType's field's scalar type does not match the scalar type of the underlying data +connector's object type field. The field's specified scalar type must have a DataConnectorScalarRepresentation defined +that specifies it as the representation for the data connector's scalar type. + +##### Disallow unknown ObjectType field types + +A build error is now raised if an ObjectType's field's type is an unknown type. + +##### Disallow orderable fields that have field arguments + +A build error is now raised if an orderable field on an OrderByExpression has field arguments. This scenario is not +supported. + +#### 2025-01-25 + +##### Disallow duplicate scalar type aggregate functions + +A build error is now raised if a data connector scalar type has multiple aggregate functions of the same type (for +example, two sum functions for the same scalar type). This ensures that there is no ambiguity when choosing an aggregate +function for a particular purpose (for example, performing a sum aggregate). + #### 2025-01-07 ##### Disallow duplicate operator definitions for scalar type