diff --git a/content/docs/guides/(authentication)/how-to-guides/authentication-methods.mdx b/content/docs/guides/(authentication)/how-to-guides/authentication-methods.mdx index ae1340e..19c4c3b 100644 --- a/content/docs/guides/(authentication)/how-to-guides/authentication-methods.mdx +++ b/content/docs/guides/(authentication)/how-to-guides/authentication-methods.mdx @@ -4,12 +4,14 @@ slug: "authentication-methods" excerpt: "" hidden: false metadata: - image: [] - robots: "index" + image: [] + robots: "index" createdAt: "Thu Aug 03 2023 22:51:23 GMT+0000 (Coordinated Universal Time)" updatedAt: "Fri Aug 25 2023 21:43:12 GMT+0000 (Coordinated Universal Time)" --- +import { Step, Steps } from "fumadocs-ui/components/steps"; + UserClouds supports every major method of authentication, such as social sign in with Google, Facebook and LinkedIn OAuth. The user's accounts will be owned by the Identity Platforms configured in “Underlying Identity Providers”. Adding a Social/Third Party Connection to a login flow can be completed in three steps: @@ -18,28 +20,39 @@ Adding a Social/Third Party Connection to a login flow can be completed in three 2. Connect your tenant to your third party account 3. Turn on that authentication method in your application -## 1. Configure your account with the third party. + + + ## Configure your account with the third party. + + To set up third party OAuth for the first time, you'll need to create your account with the third party providers directly. For more info on this, see the articles below: + + - [Setting up Google OAuth](https://support.google.com/cloud/answer/6158849?hl=en) + - [Setting up Facebook OAuth](https://developers.facebook.com/docs/facebook-login) + - [Setting up Apple OAuth](https://developer.apple.com/sign-in-with-apple/get-started/) + + + + ## Connect your tenant to the third party. -To set up third party OAuth for the first time, you'll need to create your account with the third party providers directly. For more info on this, see the articles below: + Once you have set up your relationship with the third party OAuth provider, it's time to connect your tenant to that provider: -- [Setting up Google OAuth](https://support.google.com/cloud/answer/6158849?hl=en) -- [Setting up Facebook OAuth](https://developers.facebook.com/docs/facebook-login) -- [Setting up Apple OAuth](https://developer.apple.com/sign-in-with-apple/get-started/) + - Go to your Tenant’s Authentication page. + - Select the relevant provider in the Social & 3rd Party Identity Providers card + - Copy over your OAuth Client ID and Client Secret + - Click Save! -## 2. Connect your tenant to the third party. + + -Once you have set up your relationship with the third party OAuth provider, it's time to connect your tenant to that provider: + ## Turn on the authentication method in your application. -- Go to your Tenant’s Authentication page. -- Select the relevant provider in the Social & 3rd Party Identity Providers card -- Copy over your OAuth Client ID and Client Secret -- Click Save! + Now your tenant is connected to the third party, you can add their authentication method to any applications within that tenant. This allows you to serve different login experiences to different users within the same tenant. For example, Uber might prefer to have drivers and riders served by the same tenant, since a driver wants their password to work for both apps. But Uber might also require 2FA for the driver app, since drivers payouts are configured through the driver app. -## 3. Turn on the authentication method in your application. + 1. Navigate to the Application page (Select Tenant > Authentication > Application). + 2. Create social redirect and logout URIs for that application, e.g. `https://tenantname.tenant.userclouds.com/social/callback` + 3. Add these URIs to your account with the third party (see links in part 1). + 4. Select which authentication methods are enabled in the Login Settings card. You can also configure other authentication methods, like Passwordless / Magic Link, from this card. -Now your tenant is connected to the third party, you can add their authentication method to any applications within that tenant. This allows you to serve different login experiences to different users within the same tenant. For example, Uber might prefer to have drivers and riders served by the same tenant, since a driver wants their password to work for both apps. But Uber might also require 2FA for the driver app, since drivers payouts are configured through the driver app. + -1. Navigate to the Application page (Select Tenant > Authentication > Application). -2. Create social redirect and logout URIs for that application, e.g. `https://tenantname.tenant.userclouds.com/social/callback` -3. Add these URIs to your account with the third party (see links in part 1). -4. Select which authentication methods are enabled in the Login Settings card. You can also configure other authentication methods, like Passwordless / Magic Link, from this card. + diff --git a/content/docs/guides/(authentication)/how-to-guides/migrate-from-auth0.mdx b/content/docs/guides/(authentication)/how-to-guides/migrate-from-auth0.mdx index 9b1bd7c..2d0a851 100644 --- a/content/docs/guides/(authentication)/how-to-guides/migrate-from-auth0.mdx +++ b/content/docs/guides/(authentication)/how-to-guides/migrate-from-auth0.mdx @@ -156,7 +156,11 @@ The final step is to switch your active provider back to UserClouds. This must b ### Switch your apps' active providers to UserClouds - In UserClouds, navigate to the Authentication Page - - For each app - Click the app to go into the Application page - In the General Settings card, open the Underlying Identity Provider Apps accordion section - Check the box for your tenant's UserClouds IDP - Click Save + - For each app + 1) Click the app to go into the Application page + 2) In the General Settings card, open the Underlying Identity Provider Apps accordion section + 3) Check the box for your tenant's UserClouds IDP + 4) Click Save You did it! You successfully migrated off Auth0. diff --git a/content/docs/guides/(authentication)/quickstart-guides/add-userclouds-to-your-software.mdx b/content/docs/guides/(authentication)/quickstart-guides/add-userclouds-to-your-software.mdx index 45658c6..93a7af1 100644 --- a/content/docs/guides/(authentication)/quickstart-guides/add-userclouds-to-your-software.mdx +++ b/content/docs/guides/(authentication)/quickstart-guides/add-userclouds-to-your-software.mdx @@ -7,24 +7,34 @@ createdAt: "Thu Aug 03 2023 22:43:44 GMT+0000 (Coordinated Universal Time)" updatedAt: "Mon Nov 04 2024 20:08:29 GMT+0000 (Coordinated Universal Time)" --- +import { Step, Steps } from "fumadocs-ui/components/steps"; + You’ve already created your first application in UserClouds. Nice job! This page shows how to set up UserClouds Authentication on your software. -## 1. Specify your allowed Redirect and Logout URLs + + -In the UserClouds Console, select your tenant, then navigate to Authentication > Login Apps via the sidebar. Select your Default Application to access this Application’s Settings page. From here, you can specify the exact URLs you want to allow as: + ## Specify your allowed Redirect and Logout URLs -- OIDC/OAuth2 callback URLs: this is where UserClouds will redirect your user to after they authenticate. -- Auth logout URLs: this is where UserClouds will redirect your user to after they log out. + In the UserClouds Console, select your tenant, then navigate to Authentication > Login Apps via the sidebar. Select your Default Application to access this Application’s Settings page. From here, you can specify the exact URLs you want to allow as: -Remember to click Save to apply this change! + - OIDC/OAuth2 callback URLs: this is where UserClouds will redirect your user to after they authenticate. + - Auth logout URLs: this is where UserClouds will redirect your user to after they log out. -## 2. Cut and paste your UserClouds settings into the sample app code + Remember to click Save to apply this change! -Each UserClouds application has four key attributes: an application ID, an application name, a client ID and a client secret. You will need your Client ID and Client Secret, when you use your TenantURL to call UserClouds's APIs. -Before you use the sample code elsewhere, make sure you replace the sample app’s instances of these variables with your application’s attributes. You can find these on your Application’s Settings page. + + + ## Cut and paste your UserClouds settings into the sample app code -## 3. Implement UserClouds in your software + Each UserClouds application has four key attributes: an application ID, an application name, a client ID and a client secret. You will need your Client ID and Client Secret, when you use your TenantURL to call UserClouds's APIs. + Before you use the sample code elsewhere, make sure you replace the sample app’s instances of these variables with your application’s attributes. You can find these on your Application’s Settings page. + + + ## Implement UserClouds in your software -Use the sample code (or any other OIDC library you like) as a template to add UserClouds to your application. + Use the sample code (or any other OIDC library you like) as a template to add UserClouds to your application. + + Great job! You’re all set up. diff --git a/content/docs/guides/(data-access)/definitions/access-policies.mdx b/content/docs/guides/(data-access)/definitions/access-policies.mdx index 3a124a3..fca0108 100644 --- a/content/docs/guides/(data-access)/definitions/access-policies.mdx +++ b/content/docs/guides/(data-access)/definitions/access-policies.mdx @@ -20,7 +20,7 @@ In addition, two special types of access policies are available: - **Column Default Access Policies**: These policies are associated with specific columns and are applied by default to all reads that extract data from those columns. They ensure consistent application of access rules for sensitive data, such as automatically applying a role check to the SSN column. They can be overridden for individual accessors. Learn more [here](/docs/protect-a-column-with-defaults). - **Global Baseline Access Policies**: These policies are applied by default to all reads, providing a consistent security baseline. For example, a global policy might always require a valid token or restrict access to trusted IP addresses. They cannot be overridden. Learn more [here](/docs/apply-global-protection-policies). -Access policies provide central, fine-grained control over sensitive data access. They can evaluate purpose, identity, authorization, location, , and more. They can range from simple "always allow resolution" policies to complex evaluations. +Access policies provide central, fine-grained control over sensitive data access. They can evaluate purpose, identity, authorization, location, and more. They can range from simple "always allow resolution" policies to complex evaluations. ![Access policies give you central, fine-grained control over sensitive data access. Policies can evaluate purpose, identity, permissions, location, expiration timelines, rate limits and more.](/assets/images/flow-chart.webp) diff --git a/content/docs/guides/(data-access)/definitions/selectors.mdx b/content/docs/guides/(data-access)/definitions/selectors.mdx index aa0d774..b3fd66e 100644 --- a/content/docs/guides/(data-access)/definitions/selectors.mdx +++ b/content/docs/guides/(data-access)/definitions/selectors.mdx @@ -6,6 +6,7 @@ hidden: false createdAt: "Thu Aug 03 2023 19:28:03 GMT+0000 (Coordinated Universal Time)" updatedAt: "Fri Mar 01 2024 17:20:02 GMT+0000 (Coordinated Universal Time)" --- + Selectors are SQL-like clauses that specify which records an accessor or mutator should act on. Each accessor/mutator is associated with exactly one selector. The selector is specified at accessor/mutator creation time, either as a free text input in the UI, or as a string through the API. A Selector may refer to configured Columns, specified as `{ColumnName}`, where ColumnName is the defined name of the Column. Note that non-system columns used in selectors are subject to purpose checks: each accessor's response will filter out users who have not consented to the accessor's purpose for all columns being retrieved, and all non-system columns used in the selector. @@ -20,165 +21,165 @@ Examples of selectors include: See below for a longer list of examples. -# Syntax +## Syntax There is a special Selector clause, ALL, that directs the selector to retrieve all users, and should be used judiciously. Otherwise, a selector clause may take one of the following three forms: -- `TERM` - e.g. `{FirstName} LIKE ‘Alice’` -- `TERM CONJUNCTION CLAUSE` - e.g. `{FirstName} LIKE ‘Alice’ OR {FirstName} LIKE ‘Bob’` -- `( TERM )` - e.g.`( {FirstName} LIKE ‘Alice’ OR {FirstName} LIKE ‘Bob’ ) AND {FirstName} != ‘Bill'` +- **TERM**: e.g. `{FirstName} LIKE 'Alice'` +- **TERM CONJUNCTION CLAUSE**: e.g. `{FirstName} LIKE 'Alice' OR {FirstName} LIKE 'Bob'` +- **( TERM )**: e.g.`( {FirstName} LIKE 'Alice' OR {FirstName} LIKE 'Bob' ) AND {FirstName} != 'Bill'` -The second form of a selector clause means that you can chain together an unlimited number of TERMs with CONJUNCTIONs (i.e., TERM CONJUNCTION TERM CONJUNCTION … TERM). +The second form of a selector clause means that you can chain together an unlimited number of **TERM**s with **CONJUNCTION**s (i.e., **TERM CONJUNCTION TERM CONJUNCTION** … **TERM**). -A TERM may be any of the following: +A **TERM** may be any of the following: -- COLUMN OPERATOR VALUE - e.g. `{FirstName} LIKE ‘Alice’` -- COLUMN NULL_CHECK - e.g. `{Address} IS NOT NULL` +- **COLUMN OPERATOR VALUE**: e.g. `{FirstName} LIKE 'Alice'` +- **COLUMN NULL_CHECK**: e.g. `{Address} IS NOT NULL` -A COLUMN may be any of the following: +A **COLUMN** may be any of the following: -- COLUMN_IDENTIFIER - e.g. `{Address}` -- NO_ARG_COLUMN_OPERATOR ( COLUMN ) - e.g. `char_length({FirstName})` -- LEFT_ARG_COLUMN_OPERATOR ( VALUE , COLUMN ) - e.g. `date_part( ‘day’, {DateColumn} )` -- RIGHT_ARG_COLUMN_OPERATOR ( COLUMN , VALUE ) - e.g. `mod( {IntColumn}, 4 )` +- **COLUMN_IDENTIFIER**: e.g. `{Address}` +- **NO_ARG_COLUMN_OPERATOR** ( COLUMN ): e.g. `char_length({FirstName})` +- **LEFT_ARG_COLUMN_OPERATOR** ( VALUE , COLUMN ): e.g. `date_part( ‘day’, {DateColumn} )` +- **RIGHT_ARG_COLUMN_OPERATOR** ( COLUMN , VALUE ): e.g. `mod( {IntColumn}, 4 )` -A VALUE may be any of the following: +A **VALUE** may be any of the following: -- VALUE_PLACEHOLDER -- BOOL_VALUE -- INT_VALUE -- QUOTED_VALUE -- ANY ARRAY_VALUE +- **VALUE_PLACEHOLDER** +- **BOOL_VALUE** +- **INT_VALUE** +- **QUOTED_VALUE** +- **ANY ARRAY_VALUE** -ARRAY_VALUE must be any of the following: +**ARRAY_VALUE** must be any of the following: -- VALUE_PLACEHOLDER -- ARRAY [ ARRAY_ELEMENTS ] -- ( ARRAY_VALUE ) +- **VALUE_PLACEHOLDER** +- **ARRAY [ ARRAY_ELEMENTS ]** +- **( ARRAY_VALUE )** -ARRAY_ELEMENTS must either be a VALUE or a comma-separated list of VALUEs. Each VALUE in the list must either be a VALUE_PLACEHOLDER or be of the same data type as the COLUMN. The following are examples of valid and invalid usages of ARRAY_ELEMENTS: +**ARRAY_ELEMENTS** must either be a **VALUE** or a comma-separated list of **VALUE**s. Each **VALUE** in the list must either be a **VALUE_PLACEHOLDER** or be of the same data type as the **COLUMN**. The following are examples of valid and invalid usages of **ARRAY_ELEMENTS**: - `{IntColumn} = ANY ARRAY [ ?, ?, 10 ]` - this is valid, since all array elements are either a VALUE_PLACEHOLDER, or an integer value, same as the column type. - `{StringColumn} = ANY ARRAY [ ?, ‘foo’, ‘bar’ ]` - this is valid, since all array elements are either a VALUE_PLACEHOLDER, or a string value, same as the column type. -- `{IntColumn} = ANY ARRAY [ 10, ‘foo’ ]` - this is invalid, since we are expecting all array elements to be integers, and the second entry is a string. +- `{IntColumn} = ANY ARRAY [ 10, ‘foo’ ]` - this is invalid, since we are expecting all array elements to be integers, and the second entry is a string. Supported Types -# Supported Types +## Supported Types ### BOOL_VALUEs -- Supported values can have an optional suffix of ::BOOL or ::BOOLEAN -- FALSE, ‘FALSE’, ‘OFF’, ‘NO’, ‘0’::BOOL, and ‘0’::BOOLEAN are supported for false -- TRUE, ‘TRUE’, ‘ON’, ‘YES’, ‘1’::BOOL, and ‘1’::BOOLEAN are supported for true -- Lowercase versions are also supported (e.g., false, ‘off’, ‘no’) -- For string representations, prefixes that are unique are also valid (e.g., ‘F’ and ‘N’ are valid, ‘O’ is not) +- Supported values can have an optional suffix of **::BOOL** or **::BOOLEAN** +- `FALSE`, 'FALSE', 'FALSE', 'OFF', 'NO', '0'**::BOOL**, and '0'**::BOOLEAN** are supported for false +- `TRUE`, 'TRUE', 'TRUE', 'ON', 'YES', '1'**::BOOL**, and '1'**::BOOLEAN** are supported for true +- Lowercase versions are also supported (e.g., `false`, 'off', 'no') +- For string representations, prefixes that are unique are also valid (e.g., 'F' and 'N' are valid, 'O' is not) ### CONJUNCTIONs -- AND - This takes the intersection of two CLAUSEs +- **AND** - This takes the intersection of two **CLAUSE**s Also supported: and -- OR - This takes the union of two CLAUSEs +- **OR** - This takes the union of two **CLAUSE**s Also supported: or ### COLUMN_IDENTIFIERs -- `{column_name}` - The selector query will replace the column identifier with the column value for the specific column_name for a given user -- `{column_name}` - ’field_name’ - If column_name refers to a column that has a data type of address or composite, a valid subfield specified by field_name can be referenced in the column identifier. +- `{column_name}`: The selector query will replace the column identifier with the column value for the specific column_name for a given user +- `{column_name}`: `field_name` - If column_name refers to a column that has a data type of address or composite, a valid subfield specified by field_name can be referenced in the column identifier. ### INT_VALUEs -- Supported values can have an optional suffix of ::INT or ::INTEGER +- Supported values can have an optional suffix of **::INT** or **::INTEGER** - Supported values can have an optional sign prefix (- or +) -- Values can be represented as numbers or quoted numbers (e.g., 42, ‘42’, -42, ‘+42’) +- Values can be represented as numbers or quoted numbers (e.g., 42, `42`, -42, `+42`) ### LEFT_ARG_COLUMN_OPERATORs -- This takes a VALUE and a COLUMN as arguments (e.g., DATE_PART(VALUE, COLUMN)) -- DATE_PART - This operates on a timestamp COLUMN, with the first argument being a keyword specifying a part of the timestamp to extract. The supported keywords include: - - ‘day’ - - ‘dow’ - - ‘doy’ - - ‘epoch’ - - ‘hour’ - - ‘microseconds’ - - ‘milliseconds’ - - ‘minute’ - - ‘month’ - - ‘second’ - - ‘timezone’ - - ‘week’ - - ‘year’ +- This takes a **VALUE** and a **COLUMN** as arguments (e.g., **DATE_PART(VALUE, COLUMN)**) +- **DATE_PART**: This operates on a timestamp COLUMN, with the first argument being a keyword specifying a part of the timestamp to extract. The supported keywords include: + - `day` + - `dow` + - `doy` + - `epoch` + - `hour` + - `microseconds` + - `milliseconds` + - `minute` + - `month` + - `second` + - `timezone` + - `week` + - `year` - Also supported: date_part -- DATE_TRUNC - This operates on a timestamp COLUMN, with the first argument being a keyword specifying to what precision to truncate the timestamp. The supported keywords include: - - ‘day’ - - ‘hour’ - - ‘microseconds’ - - ‘milliseconds’ - - ‘minute’ - - ‘month’ - - ‘second’ - - ‘week’ - - ‘year’ +- **DATE_TRUNC**: This operates on a timestamp **COLUMN**, with the first argument being a keyword specifying to what precision to truncate the timestamp. The supported keywords include: + - `day` + - `hour` + - `microseconds` + - `milliseconds` + - `minute` + - `month` + - `second` + - `week` + - `year` - Also supported: date_trunc ### NO_ARG_COLUMN_OPERATORs -- This takes a COLUMN as the sole argument (e.g., ABS(COLUMN)) -- ABS - This operates on an integer column, and returns the absolute value of the associated integer value +- This takes a **COLUMN** as the sole argument (e.g., **ABS(COLUMN)**) +- **ABS**: This operates on an integer column, and returns the absolute value of the associated integer value Also supported: abs -- CHAR_LENGTH - This operates on a string column, and returns the number of characters in the associated string value +- **CHAR_LENGTH**: This operates on a string column, and returns the number of characters in the associated string value Also supported: CHARACTER_LENGTH, char_length, character_length -- LOWER - This operates on a string column, and returns the lowercase version of the associated string value +- **LOWER**: This operates on a string column, and returns the lowercase version of the associated string value Also supported: lower -- UPPER - This operates on a string column, and returns the uppercase version of the associated string value +- **UPPER**: This operates on a string column, and returns the uppercase version of the associated string value Also supported: upper ### NULL_CHECKs -- IS NULL - This tests whether the column value is null - - Also supported: is_null -- IS NOT NULL - This tests whether the column value is not null - - Also supported: is_not_null +- **IS NULL**: This tests whether the column value is null + - Also supported: **is_null** +- **IS NOT NULL**: This tests whether the column value is not null + - Also supported: **is_not_null** ### OPERATORs -- `=` - This operator tests whether the COLUMN value equals the VALUE. The type of the COLUMN value must match the type of the VALUE. -- `!=` - This operator tests whether the COLUMN value is not equal to the VALUE. The type of the COLUMN value must match the type of the VALUE. -- `<=` - This operator is supported for all column types other than address or composite, and tests whether the COLUMN value is less than or equal to the VALUE. The type of the COLUMN value must match the type of the VALUE. -- `>=` - This operator is supported for all column types other than address or composite, and tests whether the COLUMN value is greater than or equal to the VALUE. The type of the COLUMN value must match the type of the VALUE. -- `<` - This operator is supported for all column types other than address or composite, and tests whether the COLUMN value is less than the VALUE. The type of the COLUMN value must match the type of the VALUE. -- `>` - This operator is supported for all column types other than address or composite, and tests whether the COLUMN value is greater than the VALUE. The type of the COLUMN value must match the type of the VALUE. -- `LIKE` - This operator is supported for string columns, and tests whether the pattern specified by VALUE matches the column value. See PSQL documentation for information about the supported format of the VALUE pattern. -- `ILIKE` - This operator is supported for string columns, and tests whether the pattern specified by VALUE matches the column value in a case-insensitive way. See PSQL documentation for information about the supported format of the VALUE pattern. +- `=`: This operator tests whether the **COLUMN** value equals the **VALUE**. The type of the **COLUMN** value must match the type of the **VALUE**. +- `!=`: This operator tests whether the **COLUMN** value is not equal to the **VALUE**. The type of the **COLUMN** value must match the type of the **VALUE**. +- `<=`: This operator is supported for all column types other than address or composite, and tests whether the **COLUMN** value is less than or equal to the **VALUE**. The type of the **COLUMN** value must match the type of the **VALUE**. +- `>=`: This operator is supported for all column types other than address or composite, and tests whether the **COLUMN** value is greater than or equal to the **VALUE**. The type of the **COLUMN** value must match the type of the **VALUE**. +- `<`: This operator is supported for all column types other than address or composite, and tests whether the **COLUMN** value is less than the **VALUE**. The type of the **COLUMN** value must match the type of the **VALUE**. +- `>`: This operator is supported for all column types other than address or composite, and tests whether the **COLUMN** value is greater than the **VALUE**. The type of the **COLUMN** value must match the type of the **VALUE**. +- `LIKE`: This operator is supported for string columns, and tests whether the pattern specified by **VALUE** matches the column value. See PSQL documentation for information about the supported format of the **VALUE** pattern. +- `ILIKE`: This operator is supported for string columns, and tests whether the pattern specified by **VALUE** matches the column value in a case-insensitive way. See PSQL documentation for information about the supported format of the **VALUE** pattern. ### QUOTED_VALUEs -- QUOTED_VALUEs must begin and end with single quote. +- **QUOTED_VALUE**s must begin and end with single quote. - A single quote may be escaped with another single quote (e.g., ‘string with ‘’single quote"’) -- A QUOTED_VALUE for a UUID must be of the form ‘NNNNNNNN-NNNN-NNNN-NNNN-NNNNNNNNNNNN', where N is a valid hex character. -- A QUOTED_VALUE for a timestamp must be a string format accepted by PSQL for a timestamp. -- A QUOTED_VALUE may optionally have one of the following suffixes: - - ::BOOL - - ::BOOLEAN - - ::INT - - ::INTEGER - - ::TIMESTAMP - - ::UUID - - ::VARCHAR +- A **QUOTED_VALUE** for a UUID must be of the form `NNNNNNNN-NNNN-NNNN-NNNN-NNNNNNNNNNNN`, where N is a valid hex character. +- A **QUOTED_VALUE** for a timestamp must be a string format accepted by PSQL for a timestamp. +- A **QUOTED_VALUE** may optionally have one of the following suffixes: + - **::BOOL** + - **::BOOLEAN** + - **::INT** + - **::INTEGER** + - **::TIMESTAMP** + - **::UUID** + - **::VARCHAR** ### RIGHT_ARG_COLUMN_OPERATORs -- This takes a COLUMN and a VALUE as arguments (e.g., DIV(COLUMN,VALUE)) -- DIV - This operates on an integer COLUMN, with the second argument being an integer divisor value and the result being the integer quotient from dividing the COLUMN value by the divisor. +- This takes a **COLUMN** and a **VALUE** as arguments (e.g., DIV(**COLUMN**,**VALUE**)) +- **DIV**: This operates on an integer **COLUMN**, with the second argument being an integer divisor value and the result being the integer quotient from dividing the **COLUMN** value by the divisor. - Also supported: div -- MOD - This operates on an integer COLUMN, with the second argument being an integer divisor value and the result being the integer remainder from dividing the COLUMN value by the divisor. +- **MOD**: This operates on an integer **COLUMN**, with the second argument being an integer divisor value and the result being the integer remainder from dividing the **COLUMN** value by the divisor. - Also supported: mod ### VALUE_PLACEHOLDER -- ? - This signifies a value placeholder. An accessor or mutator caller must provide a value with a compatible type for the associated clause that the VALUE_PLACEHOLDER is a part of. +- ?: This signifies a value placeholder. An accessor or mutator caller must provide a value with a compatible type for the associated clause that the **VALUE_PLACEHOLDER** is a part of. -# Example +## Example The following are all examples of valid selector queries: @@ -196,9 +197,9 @@ The following are all examples of valid selector queries: | `{IntColumn} = ANY ARRAY[3, 4::INT, ?]` | return users where the IntColumn value is either 3, 4, or the parameterized value | | `ABS(MOD({IntColumn},3)) = ?` | return users where the absolute value of IntColumn value mod 3 equals parameterized value | | `DIV({IntColumn}, ?) = ?` | return users where the quotient of dividing the IntColumn value by a parameterized value equals a second parameterized value | -| `{AddressColumn}-’country’ IS NULL` | return users where the country field of AddressColumn is not set | -| `{AddressColumn}-’country’ = ?` | return users where the country field of AddressColumn equals the parameterized value | -| `{AddressColumn}-’country’ = ‘USA’` | return users where the country field AddressColumn is ‘USA’ | +| `{AddressColumn}-’country’ IS NULL` | return users where the country field of AddressColumn is not set | +| `{AddressColumn}-’country’ = ?` | return users where the country field of AddressColumn equals the parameterized value | +| `{AddressColumn}-’country’ = ‘USA’` | return users where the country field AddressColumn is ‘USA’ | | `{StringColumn} LIKE ?` | return users that have a StringColumn value that matches the parameterized pattern | | `{StringColumn} LIKE ‘%foo%’` | return users that have a StringColumn value that contains the string ‘foo’ | | `lower({StringColumn}) = ANY ARRAY[‘foo’,’bar’,’baz’]` | return users that have a StringColumn value that when lower-cased equals either ‘foo’, ‘bar’, or ‘baz’ | @@ -207,14 +208,14 @@ The following are all examples of valid selector queries: | `date_trunc(‘day’, {TimestampColumn}) = ?` | return users that have a TimestampColumn value, truncated to day, that matches a parameterized timestamp | | `{BoolColumn} = TRUE OR {IntColumn} = ?` | return users that have a BoolColumn value that is true or an IntColumn value that equals a parameterized value | -# Best Practices +## Best Practices - **Be Specific**: Aim to make your selectors as specific as possible to avoid unnecessary data retrieval or modification. This improves performance and reduces the risk of unintended side effects. - **Limit Use of the ALL Clause**: Use the ALL clause sparingly, as it can significantly impact performance by retrieving or modifying every record in a dataset. -- **Avoid Unnecessary Complexity**: Keep selector clauses as simple and readable as possible, as you would for a normal SQL query. For example, when filtering based on different possible values for a column, using the LIKE or ILIKE operator for string columns or the ANY operator to compare against a collection of possible values is both more efficient and easier to understand than enumerating the possibilities with a series of terms. +- **Avoid Unnecessary Complexity**: Keep selector clauses as simple and readable as possible, as you would for a normal SQL query. For example, when filtering based on different possible values for a column, using the **LIKE** or **ILIKE** operator for string columns or the ANY operator to compare against a collection of possible values is both more efficient and easier to understand than enumerating the possibilities with a series of terms. - **Test Selectors Thoroughly**: Before deploying selectors in a production environment, test them with various input scenarios to ensure they behave as expected. -# FAQs +## FAQs **Q: What happens if the number of values in SelectorValues doesn't match the number of variables in the selector?** diff --git a/content/docs/guides/(data-access)/definitions/transformers.mdx b/content/docs/guides/(data-access)/definitions/transformers.mdx index ddeaefe..ac65050 100644 --- a/content/docs/guides/(data-access)/definitions/transformers.mdx +++ b/content/docs/guides/(data-access)/definitions/transformers.mdx @@ -52,12 +52,12 @@ A transformer consists of: - `Name` - `Description` -- `id` - a unique transformer identifier, which can be used as a reference when creating accessors and tokens +- `id`: a unique transformer identifier, which can be used as a reference when creating accessors and tokens - `Input Type` - `Output Type` -- `Transform Type` - as described above -- `Transform Function` - a transform function with the signature `func(data Object, parameters Object) (Token | error)` -- `Transform Parameters` - a static JSON object (not containing un-encoded PII) that is available at runtime, allowing you to parameterize and reuse functions like "obfuscate all but the first X letters of these emails" +- `Transform Type`: as described above +- `Transform Function`: a transform function with the signature `func(data Object, parameters Object) (Token | error)` +- `Transform Parameters`: a static JSON object (not containing un-encoded PII) that is available at runtime, allowing you to parameterize and reuse functions like "obfuscate all but the first X letters of these emails" ![The PreserveCommonValue parameter allows you to optionally preserve common email domains (like gmail.com). Rare domains, like userclouds.com, will be obscured.](/assets/images/parameters.webp) diff --git a/content/docs/guides/(data-access)/how-to-guides/create-a-transformer.mdx b/content/docs/guides/(data-access)/how-to-guides/create-a-transformer.mdx index 0110d23..ce1975e 100644 --- a/content/docs/guides/(data-access)/how-to-guides/create-a-transformer.mdx +++ b/content/docs/guides/(data-access)/how-to-guides/create-a-transformer.mdx @@ -48,7 +48,7 @@ To create a transformer in UserClouds, go to the Policies page, accessible from - **An input data type** for the transformer (string, timestamp etc) - **An output data type** for the transformer (string, timestamp etc) - - **A transform type** - for more info on these, see + - **A transform type**: for more info on these, see - **A transform function**, which will receive raw data _as a string_ and return the transformed data - _(Optional)_ **A set of parameters** for that function, which allows you to rapidly create transformers with parallel logic diff --git a/content/docs/guides/(data-access)/how-to-guides/edit-existing-user-data/execute-a-mutator.mdx b/content/docs/guides/(data-access)/how-to-guides/edit-existing-user-data/execute-a-mutator.mdx index d423b18..18e0ff0 100644 --- a/content/docs/guides/(data-access)/how-to-guides/edit-existing-user-data/execute-a-mutator.mdx +++ b/content/docs/guides/(data-access)/how-to-guides/edit-existing-user-data/execute-a-mutator.mdx @@ -23,11 +23,11 @@ When calling the ExecuteMutator API directly you pass: - An array of SelectorValues, which are used to parameterize the mutator's selector to define which users should be edited - Optional client context data, which may be referred to by the mutator access policy - `RowData`, a mapping from mutator column name to a `ValueAndPurposes` record, which captures any requested data or consent changes for that column. `ValueAndPurposes` contains the following attributes, each of which will be explained more fully in the context of FullUpdates and PartialUpdates below: - - `Value` - used for FullUpdates - - `ValueAdditions` - used for PartialUpdates - - `ValueDeletions` - used for PartialUpdates - - `PurposeAdditions` - used for FullUpdates and PartialUpdates - - `PurposeDeletions` - used for FullUpdates and PartialUpdates + - `Value`: used for FullUpdates + - `ValueAdditions`: used for PartialUpdates + - `ValueDeletions`: used for PartialUpdates + - `PurposeAdditions`: used for FullUpdates and PartialUpdates + - `PurposeDeletions`: used for FullUpdates and PartialUpdates ## What happens when you execute a mutator diff --git a/content/docs/guides/(data-tokenization)/definitions/token-access-policies.mdx b/content/docs/guides/(data-tokenization)/definitions/token-access-policies.mdx index 2df7eff..9ad2583 100644 --- a/content/docs/guides/(data-tokenization)/definitions/token-access-policies.mdx +++ b/content/docs/guides/(data-tokenization)/definitions/token-access-policies.mdx @@ -6,14 +6,14 @@ hidden: false createdAt: "Thu Aug 03 2023 22:20:54 GMT+0000 (Coordinated Universal Time)" updatedAt: "Fri Jun 28 2024 22:26:13 GMT+0000 (Coordinated Universal Time)" --- + Token Access Policies control the circumstances in which a token can be resolved. Practically, access policies are functions that receive context data and return true or false according to whether access is allowed or denied. The context can be sent from either the server or the client. Access policies allow you to govern token resolution centrally, even giving you the ability to modify contracts on data use after the data is shared. ![Access policies give you central, fine-grained control and visibility over sensitive data access. Policies can evaluate purpose, identity, authorization, location, expiration timelines and more.](/assets/images/flow-chart.webp) - -Access policies can be as simple as "always allow resolution" to complex evaluations including locations, credentials and purpose. A well-formed access policy can receive context about who is requesting the raw data, when, where and for what purpose. It will evaluate this context against the user’s consents, local laws and the company’s security settings, to determine whether access is permitted. +Access policies can be as simple as "always allow resolution" to complex evaluations including locations, credentials and purpose. A well-formed access policy can receive context about who is requesting the raw data, when, where and for what purpose. It will evaluate this context against the user’s consents, local laws and the company’s security settings, to determine whether access is permitted. ## Examples @@ -30,9 +30,9 @@ Let’s look at four possible access policies applied to a phone number token, t An access policy consists of a tuple of (ID, function, parameters) -- `id` - as described above -- `function` - a function with the signature `func(token Token, parameters Object, context Object)`, where context is passed in from the `ResolveToken()` call. -- `parameters` - a static JSON object (not containing PII) that is available at runtime, allowing you to parameterize and reuse functions like "allow access only from IP range X-Y" +- `id`: as described above +- `function`: a function with the signature `func(token Token, parameters Object, context Object)`, where context is passed in from the `ResolveToken()` call. +- `parameters`: a static JSON object (not containing PII) that is available at runtime, allowing you to parameterize and reuse functions like "allow access only from IP range X-Y" ## Managing access policies diff --git a/content/docs/guides/(data-tokenization)/definitions/token-transformers.mdx b/content/docs/guides/(data-tokenization)/definitions/token-transformers.mdx index 4afb15f..ead0975 100644 --- a/content/docs/guides/(data-tokenization)/definitions/token-transformers.mdx +++ b/content/docs/guides/(data-tokenization)/definitions/token-transformers.mdx @@ -32,9 +32,9 @@ Let’s look at four possible transformers, to see how transformers work. A transformer consists of a tuple of (ID, function, parameters) -- `id` - a unique transformer identifier, which can be used as a reference when creating tokens -- `function` - a transform function with the signature `func(data Object, parameters Object) (Token | error)` -- `parameters` - a static JSON object (not containing un-encoded PII) that is available at runtime, allowing you to parameterize and reuse functions like "obfuscate all but the first X letters of these emails" +- `id`: a unique transformer identifier, which can be used as a reference when creating tokens +- `function`: a transform function with the signature `func(data Object, parameters Object) (Token | error)` +- `parameters`: a static JSON object (not containing un-encoded PII) that is available at runtime, allowing you to parameterize and reuse functions like "obfuscate all but the first X letters of these emails" ## Managing transformers diff --git a/content/docs/guides/(deployment)/managing-configuration.mdx b/content/docs/guides/(deployment)/managing-configuration.mdx index 246b073..1259992 100644 --- a/content/docs/guides/(deployment)/managing-configuration.mdx +++ b/content/docs/guides/(deployment)/managing-configuration.mdx @@ -16,7 +16,7 @@ updatedAt: "Tue Jul 30 2024 19:06:01 GMT+0000 (Coordinated Universal Time)" There are two easy ways to run `ucconfig`: - **Download a Pre-packaged Binary:** - - Download from the Releases page. Note: On macOS, you will likely need to grant an exception to allow the binary to run. + - Download from the Releases page. _Note: On macOS, you will likely need to grant an exception to allow the binary to run._ - **Run with Docker:** - `docker run userclouds/ucconfig [ucconfig args described below...]` - Note: `docker run` may require additional flags to share environment variables or files with the container. See example commands in the Usage section. @@ -155,10 +155,10 @@ resources: ``` -- If a resource has the same UUID in all of your tenants (e.g., you used `ucconfig` to create all resources in all your tenants), then specifying **`__DEFAULT` is sufficient, and you do not need to specify the ID for every tenant. `ucconfig` will use the **`__DEFAULT` key to match live tenant resources to manifest entries. +- If a resource has the same UUID in all of your tenants (e.g., you used `ucconfig` to create all resources in all your tenants), then specifying `__DEFAULT` is sufficient, and you do not need to specify the ID for every tenant. `ucconfig` will use the `__DEFAULT` key to match live tenant resources to manifest entries. - However, if a resource exists with different UUIDs in different tenants (e.g., you already manually created an email column in your staging and production tenants, so they ended up with different IDs), you should list each ID here to ensure that `ucconfig` will match the correct live resources. -When creating a new resource, `ucconfig` will create it with the`__DEFAULT` UUID. +When creating a new resource, `ucconfig` will create it with the `__DEFAULT` UUID. ### Functions diff --git a/content/docs/guides/(deployment)/set-up-guides/eks-set-up-guide.mdx b/content/docs/guides/(deployment)/set-up-guides/eks-set-up-guide.mdx index 7537543..24b1a40 100644 --- a/content/docs/guides/(deployment)/set-up-guides/eks-set-up-guide.mdx +++ b/content/docs/guides/(deployment)/set-up-guides/eks-set-up-guide.mdx @@ -27,7 +27,7 @@ This guide assumes that you are generally familiar with helm usage and have your 2. **Create AWS IAM role for the UserClouds software to use.** The IAM role should use EKS IRSA The following AWS permissions are required by the Userclouds software: - 1. Access to AWS secrets manager - for the DB password mentioned in the previous section. The Userclouds software will also write some secrets to the AWS Secrets manager (mostly DB credentials for databases created on the RDS instance) + 1. Access to AWS secrets manager: for the DB password mentioned in the previous section. The Userclouds software will also write some secrets to the AWS Secrets manager (mostly DB credentials for databases created on the RDS instance) 3. **Add the UserClouds helm chart repo** helm repo add userclouds [https://userclouds.github.io/helm-charts](https://userclouds.github.io/helm-charts) 4. **Ensure your Kubernetes cluster has a secret to authenticate to container registry** diff --git a/content/docs/guides/(deployment)/set-up-guides/vpc-peering-set-up-guide.mdx b/content/docs/guides/(deployment)/set-up-guides/vpc-peering-set-up-guide.mdx index f8c18f9..5efb3ce 100644 --- a/content/docs/guides/(deployment)/set-up-guides/vpc-peering-set-up-guide.mdx +++ b/content/docs/guides/(deployment)/set-up-guides/vpc-peering-set-up-guide.mdx @@ -18,4 +18,4 @@ Peering VPCs is currently a manual process involving several steps: 3. Create a peering request by following the AWS instructions here. 4. UserClouds’ infrastructure team will accept the request 5. Configure the appropriate route tables to ensure data is routed correctly across the peering connection -6. \_(optional) \_Configure internal DNS to point across the VPC peering connection. If you aren’t already running internal DNS, UserClouds can repoint our public DNS to make this work. +6. _(optional)_ Configure internal DNS to point across the VPC peering connection. If you aren’t already running internal DNS, UserClouds can repoint our public DNS to make this work.