From affcb5ae1a528f8106040040f2f17236d288cc5d Mon Sep 17 00:00:00 2001 From: Rob Dominguez Date: Mon, 21 Oct 2024 07:24:02 -0500 Subject: [PATCH] Handfix authconfig --- docs/supergraph-modeling/auth-config.mdx | 322 +++++++++++++++++- .../hml_schema_resolved.json | 40 ++- 2 files changed, 351 insertions(+), 11 deletions(-) diff --git a/docs/supergraph-modeling/auth-config.mdx b/docs/supergraph-modeling/auth-config.mdx index 646329f95..1b0898861 100644 --- a/docs/supergraph-modeling/auth-config.mdx +++ b/docs/supergraph-modeling/auth-config.mdx @@ -121,12 +121,12 @@ Definition of the authentication configuration used by the API server. | Value | Description | |-----|-----| -| [AuthConfigV1](#authconfig-authconfigv1) | Definition of the authentication configuration v1, used by the API server. | -| [AuthConfigV2](#authconfig-authconfigv2) | Definition of the authentication configuration v2, used by the API server. | +| [AuthConfig1](#authconfig-authconfig1) | Definition of the authentication configuration v1, used by the API server. | +| [AuthConfig2](#authconfig-authconfig2) | Definition of the authentication configuration v2, used by the API server. | -#### AuthConfigV2 {#authconfig-authconfigv2} +#### AuthConfig2 {#authconfig-authconfig2} Definition of the authentication configuration v2, used by the API server. @@ -138,7 +138,17 @@ Definition of the authentication configuration v2, used by the API server. -#### AuthConfigV1 {#authconfig-authconfigv1} +#### AuthConfigV2 {#authconfig-authconfigv2} + +Definition of the authentication configuration v2, used by the API server. + +| Key | Value | Required | Description | +|-----|-----|-----|-----| +| `mode` | [AuthModeConfig](#authconfig-authmodeconfig) | true | | + + + +#### AuthConfig1 {#authconfig-authconfig1} Definition of the authentication configuration v1, used by the API server. @@ -147,3 +157,307 @@ Definition of the authentication configuration v1, used by the API server. | `kind` | `AuthConfig` | true | | | `version` | `v1` | true | | | `definition` | [AuthConfigV1](#authconfig-authconfigv1) | true | Definition of the authentication configuration v1, used by the API server. | + + + +#### AuthConfigV1 {#authconfig-authconfigv1} + +Definition of the authentication configuration v1, used by the API server. + +| Key | Value | Required | Description | +|-----|-----|-----|-----| +| `allowRoleEmulationBy` | [Role](#authconfig-role) / null | false | | +| `mode` | [AuthModeConfig](#authconfig-authmodeconfig) | true | The configuration for the authentication mode to use - webhook, JWT or NoAuth. | + + + +#### AuthModeConfig {#authconfig-authmodeconfig} + +The configuration for the authentication mode to use - webhook, JWT or NoAuth. + + +**Must have exactly one of the following fields:** + +| Key | Value | Required | Description | +|-----|-----|-----|-----| +| `webhook` | [AuthHookConfig](#authconfig-authhookconfig) | false | The configuration of the authentication webhook. | +| `jwt` | [JWTConfig](#authconfig-jwtconfig) | false | JWT config according to which the incoming JWT will be verified and decoded to extract the session variable claims. | +| `noAuth` | [NoAuthConfig](#authconfig-noauthconfig) | false | Configuration used when running engine without authentication | + + + +#### NoAuthConfig {#authconfig-noauthconfig} + +Configuration used when running engine without authentication + +| Key | Value | Required | Description | +|-----|-----|-----|-----| +| `role` | [Role](#authconfig-role) | true | role to assume whilst running the engine | +| `sessionVariables` | [SessionVariables](#authconfig-sessionvariables) | true | static session variables to use whilst running the engine | + + **Example:** + +```yaml +role: admin +sessionVariables: + x-hasura-user-id: '100' +``` + + +#### SessionVariables {#authconfig-sessionvariables} + +static session variables to use whilst running the engine + +| Key | Value | Required | Description | +|-----|-----|-----|-----| +| `` | string | false | Value of a session variable | + + + +#### JWTConfig {#authconfig-jwtconfig} + +JWT config according to which the incoming JWT will be verified and decoded to extract the session variable claims. + +| Key | Value | Required | Description | +|-----|-----|-----|-----| +| `audience` | [string] / null | false | Optional validation to check that the `aud` field is a member of the `audience` received, otherwise will throw error. | +| `issuer` | string / null | false | Optional validation to check that the `iss` field is a member of the `iss` received, otherwise will throw error. | +| `allowedSkew` | integer / null | false | Allowed leeway (in seconds) to the `exp` validation to account for clock skew. | +| `claimsConfig` | [JWTClaimsConfig](#authconfig-jwtclaimsconfig) | true | Claims config. Either specified via `claims_mappings` or `claims_namespace_path` | +| `tokenLocation` | [JWTTokenLocation](#authconfig-jwttokenlocation) | true | Source of the JWT authentication token. | +| `key` | [JWTKey](#authconfig-jwtkey) | true | Mode according to which the JWT auth is configured. | + + **Example:** + +```yaml +audience: null +issuer: null +allowedSkew: null +claimsConfig: + namespace: + claimsFormat: Json + location: /claims.jwt.hasura.io +tokenLocation: + type: BearerAuthorization +key: + fixed: + algorithm: HS256 + key: + value: token +``` + + +#### JWTKey {#authconfig-jwtkey} + +JWT key configuration according to which the incoming JWT will be decoded. + + +**Must have exactly one of the following fields:** + +| Key | Value | Required | Description | +|-----|-----|-----|-----| +| `fixed` | [JWTKeyConfig](#authconfig-jwtkeyconfig) | false | JWT Secret config according to which the incoming JWT will be decoded. | +| `jwkFromUrl` | string | false | | + + + +#### JWTKeyConfig {#authconfig-jwtkeyconfig} + +JWT Secret config according to which the incoming JWT will be decoded. + +| Key | Value | Required | Description | +|-----|-----|-----|-----| +| `algorithm` | [JWTAlgorithm](#authconfig-jwtalgorithm) | true | The algorithm used to decode the JWT. | +| `key` | [EnvironmentValue](#authconfig-environmentvalue) | true | The key to use for decoding the JWT. | + + + +#### EnvironmentValue {#authconfig-environmentvalue} + +Either a literal string or a reference to a Hasura secret + + +**Must have exactly one of the following fields:** + +| Key | Value | Required | Description | +|-----|-----|-----|-----| +| `value` | string | false | | +| `valueFromEnv` | string | false | | + + + +#### JWTAlgorithm {#authconfig-jwtalgorithm} + +The algorithm used to decode the JWT. + + +**One of the following values:** + +| Value | Description | +|-----|-----| +| `HS256` | HMAC using SHA-256 | +| `HS384` | HMAC using SHA-384 | +| `HS512` | HMAC using SHA-512 | +| `ES256` | ECDSA using SHA-256 | +| `ES384` | ECDSA using SHA-384 | +| `RS256` | RSASSA-PKCS1-v1_5 using SHA-256 | +| `RS384` | RSASSA-PKCS1-v1_5 using SHA-384 | +| `RS512` | RSASSA-PKCS1-v1_5 using SHA-512 | +| `PS256` | RSASSA-PSS using SHA-256 | +| `PS384` | RSASSA-PSS using SHA-384 | +| `PS512` | RSASSA-PSS using SHA-512 | +| `EdDSA` | Edwards-curve Digital Signature Algorithm (EdDSA) | + + + +#### JWTTokenLocation {#authconfig-jwttokenlocation} + +Source of the Authorization token + + +**One of the following values:** + +| Value | Description | +|-----|-----| +| [JWTBearerAuthorizationLocation](#authconfig-jwtbearerauthorizationlocation) | Get the bearer token from the `Authorization` header. | +| [JWTCookieLocation](#authconfig-jwtcookielocation) | Get the token from the Cookie header under the specified cookie name. | +| [JWTHeaderLocation](#authconfig-jwtheaderlocation) | Custom header from where the header should be parsed from. | + + + +#### JWTHeaderLocation {#authconfig-jwtheaderlocation} + +Custom header from where the header should be parsed from. + +| Key | Value | Required | Description | +|-----|-----|-----|-----| +| `type` | `Header` | true | | +| `name` | string | true | | + + + +#### JWTCookieLocation {#authconfig-jwtcookielocation} + +Get the token from the Cookie header under the specified cookie name. + +| Key | Value | Required | Description | +|-----|-----|-----|-----| +| `type` | `Cookie` | true | | +| `name` | string | true | | + + + +#### JWTBearerAuthorizationLocation {#authconfig-jwtbearerauthorizationlocation} + +Get the bearer token from the `Authorization` header. + +| Key | Value | Required | Description | +|-----|-----|-----|-----| +| `type` | `BearerAuthorization` | true | | + + + +#### JWTClaimsConfig {#authconfig-jwtclaimsconfig} + +Config to describe how/where the engine should look for the claims within the decoded token. + + +**Must have exactly one of the following fields:** + +| Key | Value | Required | Description | +|-----|-----|-----|-----| +| `locations` | [JWTClaimsMap](#authconfig-jwtclaimsmap) | false | 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 and optionally a default value. | +| `namespace` | [JWTClaimsNamespace](#authconfig-jwtclaimsnamespace) | false | Used when all of the Hasura claims are present in a single object within the decoded JWT. | + + + +#### JWTClaimsNamespace {#authconfig-jwtclaimsnamespace} + +Used when all of the Hasura claims are present in a single object within the decoded JWT. + +| Key | Value | Required | Description | +|-----|-----|-----|-----| +| `claimsFormat` | [JWTClaimsFormat](#authconfig-jwtclaimsformat) | true | Format in which the Hasura claims will be present. | +| `location` | string | true | Pointer to lookup the Hasura claims within the decoded claims. | + + + +#### JWTClaimsFormat {#authconfig-jwtclaimsformat} + +Format in which the Hasura claims will be present. + + +**One of the following values:** + +| Value | Description | +|-----|-----| +| `Json` | Claims will be in the JSON format. | +| `StringifiedJson` | Claims will be in the Stringified JSON format. | + + + +#### JWTClaimsMap {#authconfig-jwtclaimsmap} + +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 and optionally a default value. + +| Key | Value | Required | Description | +|-----|-----|-----|-----| +| `x-hasura-default-role` | [JWTClaimsMappingEntry](#authconfig-jwtclaimsmappingentry) | true | JSON pointer to lookup the default role within the decoded JWT. | +| `x-hasura-allowed-roles` | [JWTClaimsMappingEntry](#authconfig-jwtclaimsmappingentry) | true | JSON pointer to lookup the allowed roles within the decoded JWT. | + + + +#### JWTClaimsMappingEntry {#authconfig-jwtclaimsmappingentry} + +JSON pointer to lookup the default role within the decoded JWT. + + +**Must have exactly one of the following fields:** + +| Key | Value | Required | Description | +|-----|-----|-----|-----| +| `literal` | [Role](#authconfig-role) | false | | +| `path` | [JWTClaimsMappingPathEntry](#authconfig-jwtclaimsmappingpathentry) | false | Entry to lookup the Hasura claims at the specified JSON Pointer | + + + +#### JWTClaimsMappingPathEntry {#authconfig-jwtclaimsmappingpathentry} + +Entry to lookup the Hasura claims at the specified JSON Pointer + +| Key | Value | Required | Description | +|-----|-----|-----|-----| +| `path` | string | true | JSON pointer to find the particular claim in the decoded JWT token. | +| `default` | [Role](#authconfig-role) / null | false | Default value to be used when no value is found when looking up the value using the `path`. | + + + +#### AuthHookConfig {#authconfig-authhookconfig} + +The configuration of the authentication webhook. + +| Key | Value | Required | Description | +|-----|-----|-----|-----| +| `url` | string | true | The URL of the authentication webhook. | +| `method` | [AuthHookMethod](#authconfig-authhookmethod) | true | The HTTP method to be used to make the request to the auth hook. | + + **Example:** + +```yaml +url: http://auth_hook:3050/validate-request +method: Post +``` + + +#### AuthHookMethod {#authconfig-authhookmethod} + +The HTTP method to be used to make the request to the auth hook. + + +**Value:** `Get` / `Post` + + +#### Role {#authconfig-role} + + +**Value:** string \ No newline at end of file diff --git a/utilities/generate-metadata-docs/hml_schema_resolved.json b/utilities/generate-metadata-docs/hml_schema_resolved.json index 8561c68d9..44d0cf879 100644 --- a/utilities/generate-metadata-docs/hml_schema_resolved.json +++ b/utilities/generate-metadata-docs/hml_schema_resolved.json @@ -48,7 +48,7 @@ "description": "Definition of the authentication configuration used by the API server.", "oneOf": [ { - "title": "AuthConfigV1", + "title": "AuthConfig1", "description": "Definition of the authentication configuration v1, used by the API server.", "type": "object", "required": ["definition", "kind", "version"], @@ -595,7 +595,7 @@ "additionalProperties": false }, { - "title": "AuthConfigV2", + "title": "AuthConfig2", "description": "Definition of the authentication configuration v2, used by the API server.", "type": "object", "required": ["definition", "kind", "version"], @@ -785,7 +785,13 @@ "$schema": "http://json-schema.org/draft-07/schema#", "title": "Schema Response", "type": "object", - "required": ["collections", "functions", "object_types", "procedures", "scalar_types"], + "required": [ + "collections", + "functions", + "object_types", + "procedures", + "scalar_types" + ], "properties": { "scalar_types": { "description": "A list of scalar types which will be used as the types of collection columns", @@ -1304,7 +1310,13 @@ "CollectionInfo": { "title": "Collection Info", "type": "object", - "required": ["arguments", "foreign_keys", "name", "type", "uniqueness_constraints"], + "required": [ + "arguments", + "foreign_keys", + "name", + "type", + "uniqueness_constraints" + ], "properties": { "name": { "description": "The name of the collection\n\nNote: these names are abstract - there is no requirement that this name correspond to the name of an actual collection in the database.", @@ -2638,7 +2650,13 @@ "title": "ObjectBooleanExpressionTypeV1", "description": "Definition of a type representing a boolean expression on an Open DD object type. Deprecated in favour of `BooleanExpressionType`.", "type": "object", - "required": ["comparableFields", "dataConnectorName", "dataConnectorObjectType", "name", "objectType"], + "required": [ + "comparableFields", + "dataConnectorName", + "dataConnectorObjectType", + "name", + "objectType" + ], "properties": { "name": { "description": "The name to give this object boolean expression type, used to refer to it elsewhere in the metadata. Must be unique across all types defined in this subgraph.", @@ -2991,7 +3009,11 @@ "title": "DataConnectorOperatorMapping", "description": "Mapping between OpenDD operator names and the names used in the data connector schema", "type": "object", - "required": ["dataConnectorName", "dataConnectorScalarType", "operatorMapping"], + "required": [ + "dataConnectorName", + "dataConnectorScalarType", + "operatorMapping" + ], "properties": { "dataConnectorName": { "description": "Name of the data connector this mapping applies to", @@ -3408,7 +3430,11 @@ "title": "DataConnectorAggregationFunctionMapping", "description": "Definition of how to map an aggregate expression's aggregation functions to data connector aggregation functions.", "type": "object", - "required": ["dataConnectorName", "dataConnectorScalarType", "functionMapping"], + "required": [ + "dataConnectorName", + "dataConnectorScalarType", + "functionMapping" + ], "properties": { "dataConnectorName": { "description": "The data connector being mapped to",