From 8da2e4b9112abda26c533aac208eec671483291a Mon Sep 17 00:00:00 2001 From: cortex-mt Date: Wed, 12 Jun 2024 13:53:21 +0100 Subject: [PATCH 1/7] Added LogonType, and updated other pages. --- .../execute-data-command-block-1.md | 9 + .../block-properties/common-properties.md | 8 +- .../data-types/credentials/logontype.md | 169 ++++++++++++++++++ .../data-types/credentials/usercredentials.md | 18 +- data/urls.toml | 4 + 5 files changed, 206 insertions(+), 2 deletions(-) create mode 100644 content/en/docs/2024.3/Reference/data-types/credentials/logontype.md diff --git a/content/en/docs/2024.3/Reference/Blocks/data/execute-data-command/execute-data-command-block-1.md b/content/en/docs/2024.3/Reference/Blocks/data/execute-data-command/execute-data-command-block-1.md index a284879cd..4e11298f0 100644 --- a/content/en/docs/2024.3/Reference/Blocks/data/execute-data-command/execute-data-command-block-1.md +++ b/content/en/docs/2024.3/Reference/Blocks/data/execute-data-command/execute-data-command-block-1.md @@ -698,6 +698,12 @@ As a result, any issues with using the [Result][Result Property] (i.e. trying to If it is desirable to have any issues reported as messages when trying to debug the flow, the user can [cast][Object Casting] the [Result][Result Property] to its correct type. +### RunAs + +If no credentials are provided in the [ConnectionDetails][], then the [RunAsProperty][] can be used to authenticate with. Some [ConnectionDetails][], do require the connection string to contain `Trusted_Connection=True;` or `userid=;` to make use of the [UserCredentials][]. + +If you are using [UserCredentials][] to authenticate in the [RunAsProperty][], then it should be noted that the [LogonType][] is used to identify the method of impersonation. The default is `LogonType.Network`, which should be used for accessing a local database, however if you are trying to access a remote database, then `LogonType.NewCredentials` would be the correct [LogonType][] to use. + ### Known Limitations When using a [Parameterised Command][Parameterised Commands] to execute a stored procedure, it is not possible to write back to output parameters. @@ -782,6 +788,9 @@ When using a [Parameterised Command][Parameterised Commands] to execute a stored [SqlException]: {{< url path="MSDocs.SqlServer.SqlException" >}} [Variables]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Variables.MainDoc" >}} [Object Casting]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Objects.ObjectCasting.MainDoc" >}} +[UserCredentials]: {{< url path="Cortex.Reference.DataTypes.Credentials.UserCredentials.MainDoc" >}} +[RunAsProperty]: {{< url path="Cortex.Reference.DataTypes.Credentials.UserCredentials.LogonType" >}} +[LogonType]: {{< url path="Cortex.Reference.DataTypes.Credentials.LogonType.MainDoc" >}} [Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2024.3/Reference/Concepts/fundamentals/blocks/block-properties/common-properties.md b/content/en/docs/2024.3/Reference/Concepts/fundamentals/blocks/block-properties/common-properties.md index afba65a28..a4f28c15d 100644 --- a/content/en/docs/2024.3/Reference/Concepts/fundamentals/blocks/block-properties/common-properties.md +++ b/content/en/docs/2024.3/Reference/Concepts/fundamentals/blocks/block-properties/common-properties.md @@ -55,12 +55,17 @@ Once the [block][] has finished executing, the next block to execute will run as The default value of `null` also results in the [block][] executing as the user the [Execution Service][] is running as. -If [UserCredentials][] has an invalid domain, username or password, a [RunAsException][] will be thrown when the [block][] is executed. +If [UserCredentials][] has an invalid domain, username, password or [LogonType][], a [RunAsException][] will be thrown when the [block][] is executed. If [UserCredentials][] has a `null` username or password, a [PropertyNullException][] will be thrown when the [block][] is executed. {{< figure src="/images/set-variable/set-variable-run-as.svg" >}} +The [LogonType][] is used to identify the method of impersonation. The default is `LogonType.Network`, and does not need to be declared in the constructor, but can be changed. + +For example, if you are trying to access a remote machine, then `LogonType.Network` would be the correct [LogonType][]. +Whereas if you are trying to access a database on a remote machine, then `LogonType.NewCredentails` would be the correct [LogonType][]. + ## Block Timeout Property The Block Timeout property is an [advanced property][Advanced Properties] available on most [blocks][All Blocks]. It is used to set a duration of time (using a [TimePeriod][]) that the [block][] must complete its action within, otherwise a [BlockTimeoutException][] is raised. @@ -126,6 +131,7 @@ None [Executions]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Executions.WhatIsAnExecution.MainDoc" >}} [WhatIsBlock]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.WhatIsABlock.MainDoc" >}} [Execution Service]: {{< url path="Cortex.Guides.CortexInnovation.ExecutionApplication.Services.ExecutionService.MainDoc" >}} +[LogonType]: {{< url path="Cortex.Reference.DataTypes.Credentials.LogonType.MainDoc" >}} [Exceptions]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Exceptions.MainDoc" >}} diff --git a/content/en/docs/2024.3/Reference/data-types/credentials/logontype.md b/content/en/docs/2024.3/Reference/data-types/credentials/logontype.md new file mode 100644 index 000000000..ab06a4075 --- /dev/null +++ b/content/en/docs/2024.3/Reference/data-types/credentials/logontype.md @@ -0,0 +1,169 @@ +--- +title: "LogonType" +linkTitle: "LogonType" +description: "Used to represent the Logon type used for the UserCredentials." +--- + +# {{% param title %}} + +

(Cortex.DataTypes.Credentials.LogonType)

+ +## Summary + +The `LogonType` data type is used to represent the Logon type for the [UserCredentials][]. + +`LogonType` is an [enum][Working with Enums] data type, which means it has a defined set of values, where each value has an associated [String][] name and [Int32][] value. + +| | | +|---------------------|------------------------------------------------------------------------------------------------------------------------------------| +| **Category:** | Credentials | +| **Name:** | `LogonType` | +| **Full Name:** | `Cortex.DataTypes.Credentials.LogonType` | +| **Alias:** | N/A | +| **Description:** | Used to represent the Logon type of the [UserCredentials][]. | +| **Default Value:** | `LogonType.Network` | +| **Can be used as:** | `LogonType`, `Object`, `dynamic` | +| **Can be cast to:** | `Int16` (e.g. `(Int16)LogonType.Network` or `(System.Int16)LogonType.Network` or `(short)LogonType.Network`) | +| | `Int32` (e.g. `(Int32)LogonType.Network` or `(System.Int32)LogonType.Network` or `(int)LogonType.Network`) | +| | `Int64` (e.g. `(Int64)LogonType.Network` or `(System.Int64)LogonType.Network` or `(long)LogonType.Network`) | +| | `Single` (e.g. `(Single)LogonType.Network` or `(System.Single)LogonType.Network` or `(float)LogonType.Network`) | +| | `Double` (e.g. `(Double)LogonType.Network` or `(System.Double)LogonType.Network` or `(double)LogonType.Network`) | + +## Values + +### Network + +| | | +|------------|----------------------------| +| **Name:** | Network | +| **Value:** | [Int32][] with value `3` | +| **Notes:** | The security principal is logging on using a network. This allows for NET USE, RPC calls, Remote Registry, IIS integrated Windows auth, and local SQL Windows auth. | + +### NetworkCleartext + +| | | +|------------|----------------------------| +| **Name:** | NetworkCleartext | +| **Value:** | [Int32][] with value `8` | +| **Notes:** | The logon is a Network logon with plaintext credentials. | + +### NewCredentials + +| | | +|------------|----------------------------| +| **Name:** | NewCredentials | +| **Value:** | [Int32][] with value `9` | +| **Notes:** | Allows the caller to clone its current logon token and specify new credentials for outbound connections. The new logon session has the same local identity but uses different credentials for other network connections. This logon type should be used when authenticating against a remote database. | + +## Remarks + +### Create LogonType + +The following table shows some of the ways that `LogonType` can be created using the expression editor. + +| Method | Example | Result | Editor Support | Notes | +|-|-|-|-|-| +| Use a `LogonType` expression | `LogonType.Network` | `LogonType.Network`| Expression | | +| | `LogonType.NetworkCleartext` | `LogonType.NetworkCleartext` | Expression | | +| | `LogonType.NewCredentials` | `LogonType.NewCredentials` | Expression | | +| Use [Explicit Casting][] | `(LogonType)3` | `LogonType.Network`| Expression | | +| | `(LogonType)8` | `LogonType.NetworkCleartext` | Expression | | +| | `(LogonType)9` | `LogonType.NewCredentials` | Expression | | +| Use `Enum.Parse` | `(LogonType)Enum.Parse(typeof(LogonType), "Network")` | `LogonType.Network`| Expression | Parses `"Network"` and converts it to `LogonType.Network`. See [Enum.Parse][] | +| | `(LogonType)Enum.Parse(typeof(LogonType), "NetworkCleartext")` | `LogonType.NetworkCleartext`| Expression | Parses `"NetworkCleartext"` and converts it to `LogonType.NetworkCleartext`. See [Enum.Parse][] | +| | `(LogonType)Enum.Parse(typeof(LogonType), "NewCredentials")` | `LogonType.NewCredentials`| Expression | Parses `"NewCredentials"` and converts it to `LogonType.NewCredentials`. See [Enum.Parse][] | +| Use `Enum.ToObject` | `(LogonType)Enum.ToObject(typeof(LogonType), 3)` | `LogonType.Network`| Expression | Converts `3` to `LogonType.Network` value. See [Enum.ToObject][] | +| | `(LogonType)Enum.ToObject(typeof(LogonType), 8)` | `LogonType.NetworkCleartext` | Expression | Converts `8` to `LogonType.NetworkCleartext` value. See [Enum.ToObject][] | +| | `(LogonType)Enum.ToObject(typeof(LogonType), 9)` | `LogonType.NewCredentials` | Expression | Converts `9` to `LogonType.NewCredentials` value. See [Enum.ToObject][] | + +Please see [Instantiating an enumeration type][] for further information. + +### Convert LogonType to Text + +The following table shows some of the ways that a `LogonType` can be converted to text. + +| Method | Example | Result | Editor Support | Notes | +|-|-|-|-|-| +| Use `ToString` | `LogonType.Network.ToString()` | `"Network"` | Expression | Converts `LogonType.Network` to `"Network"`. See [Enum.ToString][] | +| | `LogonType.NetworkCleartext.ToString()` | `"NetworkCleartext"` | Expression | Converts `LogonType.NetworkCleartext` to `"NetworkCleartext"`. See [Enum.ToString][] | +| | `LogonType.NewCredentials.ToString()` | `"NewCredentials"` | Expression | Converts `LogonType.NewCredentials` to `"NewCredentials"`. See [Enum.ToString][] | +| Use `Convert.ToString` | `Convert.ToString(LogonType.Network)` | `"Network"` | Expression | Converts `LogonType.Network` to `"Network"`. See [Convert.ToString][] | +| | `Convert.ToString(LogonType.NetworkCleartext)` | `"NetworkCleartext"` | Expression | Converts `LogonType.NetworkCleartext` to `"NetworkCleartext"`. See [Convert.ToString][] | +| | `Convert.ToString(LogonType.NewCredentials)` | `"NewCredentials"` | Expression | Converts `LogonType.NewCredentials` to `"NewCredentials"`. See [Convert.ToString][] | +| Use `Convert Object To Text` block | where `Object` property has a value of `LogonType.Network` | `"Network"` | N/A | Converts `LogonType.Network` to `"Network"`. See [Convert Object To Text][] | +| | where `Object` property has a value of `LogonType.NetworkCleartext` | `"NetworkCleartext"` | N/A | Converts `LogonType.NetworkCleartext` to `"NetworkCleartext"`. See [Convert Object To Text][] | +| | where `Object` property has a value of `LogonType.NewCredentials` | `"NewCredentials"` | N/A | Converts `LogonType.NewCredentials` to `"NewCredentials"`. See [Convert Object To Text][] | +| Use `Convert Object To Json` block | where `Object` property has a value of `LogonType.Network` | `"3"` | N/A | Converts `LogonType.Network` to `"3"`. See [Convert Object To Json][] | +| | where `Object` property has a value of `LogonType.NetworkCleartext` | `"8"` | N/A | Converts `LogonType.NetworkCleartext` to `"8"`. See [Convert Object To Json][] | +| | where `Object` property has a value of `LogonType.NewCredentials` | `"9"` | N/A | Converts `LogonType.NewCredentials` to `"9"`. See [Convert Object To Json][] | + +Please see [Formatting enumeration values][] for further information. + +### Convert LogonType to a Number + +The following table shows some of the ways that a `LogonType` can be converted to a number. + +| Method | Example | Result | Editor Support | Notes | +|-|-|-|-|-| +| Use [Explicit Casting][] | `(Int32)LogonType.Network` | `3` | Expression | [Casts][Explicit Casting] `LogonType.Network` to `3` | +| | `(Int32)LogonType.NetworkCleartext` | `8` | Expression | [Casts][Explicit Casting] `LogonType.NetworkCleartext` to `8` | +| | `(Int32)LogonType.NewCredentials` | `9` | Expression | [Casts][Explicit Casting] `LogonType.NewCredentials` to `9` | +| Use `Convert.ToInt32` | `Convert.ToInt32(LogonType.Network)` | `3` | Expression | Converts `LogonType.Network` to `3`. See [Convert.ToInt32][] | +| | `Convert.ToInt32(LogonType.NetworkCleartext)` | `8` | Expression | Converts `LogonType.NetworkCleartext` to `8`. See [Convert.ToInt32][] | +| | `Convert.ToInt32(LogonType.NewCredentials)` | `9` | Expression | Converts `LogonType.NewCredentials` to `9`. See [Convert.ToInt32][] | + +### Property Editor Support + +- The Expression Editor is available for [Input][] properties where the data type is `LogonType`. +- The Literal Editor is available for [Input][] properties where the data type is `LogonType`. +- The Variable Editor is available for [Input][], [InputOutput][] and [Output][] properties where the data type is `LogonType`. + +### Known Limitations + +- When [LogonType][] is set to `LogonType.NewCredentials` and trying to connect to a localhost database, it will not recognise the UserCredentials. To fix this use `LogonType.Network` as the [LogonType][]. + +## See Also + +### Related Data Types + +- [Int32][] +- [String][] +- [UserCredentials][] + +### Related Concepts + +- [Explicit Casting][] +- [Working with Enums][] + +### External Documentation + +- [LogonTypes][] +- [System.Enum][] + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} + +[LogonTypes]: {{< url path="MSDocs.Windows.WindowsServer.LogonTypes" >}} +[System.Enum]: {{< url path="MSDocs.DotNet.Api.System.Enum.MainDoc" >}} + +[Working with Enums]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Enums.MainDoc" >}} +[Explicit Casting]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Objects.ObjectCasting.ExplicitCast" >}} + +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} +[Formatting enumeration values]: {{< url path="MSDocs.DotNet.Api.System.Enum.FormattingEnumerationValues" >}} +[Convert Object To Text]: {{< url path="Cortex.Reference.Blocks.Objects.ConvertObject.ConvertObjectToText.MainDoc" >}} +[Convert Object To Json]: {{< url path="Cortex.Reference.Blocks.Json.ConvertJson.ConvertObjectToJson.MainDoc" >}} +[Working with Enums]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Enums.MainDoc" >}} +[Explicit Casting]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Objects.ObjectCasting.ExplicitCast" >}} +[Enum.Parse]: {{< url path="MSDocs.DotNet.Api.System.Enum.Parse" >}} +[Enum.ToObject]: {{< url path="MSDocs.DotNet.Api.System.Enum.ToObject" >}} +[Enum.ToString]: {{< url path="MSDocs.DotNet.Api.System.Enum.ToString" >}} +[Convert.ToInt32]: {{< url path="MSDocs.DotNet.Api.System.Convert.ToInt32" >}} +[Convert.ToString]: {{< url path="MSDocs.DotNet.Api.System.Convert.ToString" >}} +[LogonType]: {{< url path="Cortex.Reference.DataTypes.Credentials.LogonType.MainDoc" >}} +[UserCredentials]: {{< url path="Cortex.Reference.DataTypes.Credentials.UserCredentials.MainDoc" >}} + +[Instantiating an enumeration type]: {{< url path="MSDocs.DotNet.Api.System.Enum.InstantiatingAnEnum" >}} +[Formatting enumeration values]: {{< url path="MSDocs.DotNet.Api.System.Enum.FormattingEnumerationValues" >}} \ No newline at end of file diff --git a/content/en/docs/2024.3/Reference/data-types/credentials/usercredentials.md b/content/en/docs/2024.3/Reference/data-types/credentials/usercredentials.md index 9c2103e4d..4351f2c53 100644 --- a/content/en/docs/2024.3/Reference/data-types/credentials/usercredentials.md +++ b/content/en/docs/2024.3/Reference/data-types/credentials/usercredentials.md @@ -63,6 +63,17 @@ The Password is used to define the password of the user to authenticate as. This | Default Editor | [Expression][] | | Default Value | [EncryptedText][] with value `""` | +### LogonType + +The LogonType is used to define what type of logon method to use. This property is a [LogonType][] which is an enum. + +| | | +|--------------------|---------------------------| +| Data Type | [LogonType][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | [LogonType][] with value `LogonType.Network` | + ## Remarks ### Create a UserCredentials @@ -73,6 +84,8 @@ The following table shows some of the ways that `UserCredentials` can be created |-|-|-|-|-| | Use a `UserCredentials` constructor | `new UserCredentials(domain: "domain", username: "username", password: "encryptedPassword")` | `{"Domain": "domain", "Username": "username", "Password": "encryptedPassword"}` | Expression | Domain specified | | | `new UserCredentials(username: "username", password: "encryptedPassword")` | `{"Domain": null, "Username": "username", "Password": "encryptedPassword"}` | Expression | Domain not specified | +| | `new UserCredentials(domain: "domain", username: "username", password: "encryptedPassword", logontype: LogonType.Network)` | `{"Domain": "domain", "Username": "username", "Password": "encryptedPassword", "LogonType": LogonType.Network}` | Expression | Domain and LogonType specified | +| | `new UserCredentials(username: "username", password: "encryptedPassword", logontype: LogonType.Network)` | `{"Domain": null, "Username": "username", "Password": "encryptedPassword", "LogonType": LogonType.Network}` | Expression | Domain and LogonType not specified | A `UserCredentials` can also be created using the Literal Editor by filling in the necessary values for the following properties: @@ -81,12 +94,13 @@ A `UserCredentials` can also be created using the Literal Editor by filling in t | `Domain` | `EncryptableText` | `"domain"` | [Domain][Domain Property] defines the domain or server to authenticate with. | | `Username` | `EncryptableText` | `"username"` | [Username][Username Property] defines the user to authenticate as. | | `Password` | `EncryptedText` | `"encryptedPassword"` | [Password][Password Property] defines the password of the user to authenticate as. | +| `LogonType` | `LogonType` | `LogonType.Network` | [LogonType][LogonType Property] defines the logon type of the user to authenticate as. | ### Convert UserCredentials to Text | Method | Example | Result | Editor Support | Notes | |-|-|-|-|-| -| Use `Convert Object To Json` block | where `Object` property has a value of `{"Domain": "domain", "Username": "username", "Password": "encryptedPassword"}` | `"{\r\n \"Domain\": \"domain\",\r\n \"Username\": \"username\",\r\n \"Password\": \"encryptedPassword\"\r\n}"` | N/A | See [Convert Object To Json][] | +| Use `Convert Object To Json` block | where `Object` property has a value of `{"Domain": "domain", "Username": "username", "Password": "encryptedPassword", "LogonType": LogonType.Network}` | `"{\r\n \"Domain\": \"domain\",\r\n \"Username\": \"username\",\r\n \"Password\": \"encryptedPassword\",\r\n \"LogonType\": 3\r\n}"` | N/A | See [Convert Object To Json][] | ### Property Editor Support @@ -126,6 +140,7 @@ None [Domain Property]: {{< ref "#domain" >}} [Username Property]: {{< ref "#username" >}} [Password Property]: {{< ref "#password" >}} +[LogonType Property]: {{< ref "#logontype" >}} [Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} [Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} @@ -143,6 +158,7 @@ None [ISshCredentials]: {{< url path="Cortex.Reference.DataTypes.Ssh.Authentication.ISshCredentials.MainDoc" >}} [SshCredentials]: {{< url path="Cortex.Reference.DataTypes.Ssh.Authentication.SshCredentials.MainDoc" >}} [SshUserCredentials]: {{< url path="Cortex.Reference.DataTypes.Ssh.Authentication.SshUserCredentials.MainDoc" >}} +[LogonType]: {{< url path="Cortex.Reference.DataTypes.Credentials.LogonType.MainDoc" >}} [NetworkCredential]: {{< url path="MSDocs.DotNet.Api.System.Net.NetworkCredential" >}} diff --git a/data/urls.toml b/data/urls.toml index ea18c6222..493db32f0 100644 --- a/data/urls.toml +++ b/data/urls.toml @@ -1446,6 +1446,9 @@ Domain = "/docs/reference/data-types/credentials/usercredentials/#domain" Username = "/docs/reference/data-types/credentials/usercredentials/#username" Password = "/docs/reference/data-types/credentials/usercredentials/#password" + LogonType = "/docs/reference/data-types/credentials/usercredentials/#logontype" + [Cortex.Reference.DataTypes.Credentials.LogonType] + MainDoc = "/docs/reference/data-types/credentials/logontype" [Cortex.Reference.DataTypes.Data] MainDoc = "/docs/reference/data-types/data/" [Cortex.Reference.DataTypes.Data.DataCommand] @@ -2530,6 +2533,7 @@ NamingConventions = "https://learn.microsoft.com/en-us/windows/win32/fileio/naming-a-file#naming-conventions" Paths = "https://learn.microsoft.com/en-us/windows/win32/fileio/naming-a-file#paths" [MSDocs.Windows.WindowsServer] + LogonTypes = "https://learn.microsoft.com/en-us/windows-server/identity/securing-privileged-access/reference-tools-logon-types" NamingConventions = "https://learn.microsoft.com/en-us/troubleshoot/windows-server/active-directory/naming-conventions-for-computer-domain-site-ou" [MSDotNet] [MSDotNet.Framework471] From 4b24ef789f5ca994cc0362bd94edf41f06317249 Mon Sep 17 00:00:00 2001 From: cortex-jk Date: Tue, 18 Jun 2024 16:39:44 +0100 Subject: [PATCH 2/7] Updated usercredentials.md and logontype.md --- .../Reference/data-types/credentials/logontype.md | 13 ++++++++----- .../data-types/credentials/usercredentials.md | 10 +++++----- 2 files changed, 13 insertions(+), 10 deletions(-) diff --git a/content/en/docs/2024.3/Reference/data-types/credentials/logontype.md b/content/en/docs/2024.3/Reference/data-types/credentials/logontype.md index ab06a4075..de21d1fa9 100644 --- a/content/en/docs/2024.3/Reference/data-types/credentials/logontype.md +++ b/content/en/docs/2024.3/Reference/data-types/credentials/logontype.md @@ -10,7 +10,7 @@ description: "Used to represent the Logon type used for the UserCredentials." ## Summary -The `LogonType` data type is used to represent the Logon type for the [UserCredentials][]. +The `LogonType` data type is used to represent the type of logon method to use to authenticate a user. `LogonType` is an [enum][Working with Enums] data type, which means it has a defined set of values, where each value has an associated [String][] name and [Int32][] value. @@ -20,7 +20,7 @@ The `LogonType` data type is used to represent the Logon type for the [UserCrede | **Name:** | `LogonType` | | **Full Name:** | `Cortex.DataTypes.Credentials.LogonType` | | **Alias:** | N/A | -| **Description:** | Used to represent the Logon type of the [UserCredentials][]. | +| **Description:** | Used to represent the type of logon method to use to authenticate a user. | | **Default Value:** | `LogonType.Network` | | **Can be used as:** | `LogonType`, `Object`, `dynamic` | | **Can be cast to:** | `Int16` (e.g. `(Int16)LogonType.Network` or `(System.Int16)LogonType.Network` or `(short)LogonType.Network`) | @@ -37,7 +37,7 @@ The `LogonType` data type is used to represent the Logon type for the [UserCrede |------------|----------------------------| | **Name:** | Network | | **Value:** | [Int32][] with value `3` | -| **Notes:** | The security principal is logging on using a network. This allows for NET USE, RPC calls, Remote Registry, IIS integrated Windows auth, and local SQL Windows auth. | +| **Notes:** | Represents a network logon. This should be used in most cases, including when connecting to a local database as a Windows user. If connecting to a remote database as a Windows user, [NewCredentials][] should be used. | ### NetworkCleartext @@ -45,7 +45,7 @@ The `LogonType` data type is used to represent the Logon type for the [UserCrede |------------|----------------------------| | **Name:** | NetworkCleartext | | **Value:** | [Int32][] with value `8` | -| **Notes:** | The logon is a Network logon with plaintext credentials. | +| **Notes:** | Represents a network logon. This differs from [Network][] as the user's password will be passed as cleartext. This should be used when authenticating with IIS using Basic Auth, and Windows PowerShell with CredSSP. | ### NewCredentials @@ -53,7 +53,7 @@ The `LogonType` data type is used to represent the Logon type for the [UserCrede |------------|----------------------------| | **Name:** | NewCredentials | | **Value:** | [Int32][] with value `9` | -| **Notes:** | Allows the caller to clone its current logon token and specify new credentials for outbound connections. The new logon session has the same local identity but uses different credentials for other network connections. This logon type should be used when authenticating against a remote database. | +| **Notes:** | Represents a clone of the user's current logon. For local operations, it uses the same local identity. For network operations, it uses the identity of the credentials supplied. This should be used when authenticating against a remote database as a Windows User. Allows the caller to clone its current logon token and specify new credentials for outbound connections. The new logon session has the same local identity but uses different credentials for other network connections. This logon type should be used when authenticating against a remote database. | ## Remarks @@ -140,6 +140,9 @@ The following table shows some of the ways that a `LogonType` can be converted t - [LogonTypes][] - [System.Enum][] +[Network]: {{< ref "#network" >}} +[NewCredentials]: {{< ref "#newcredentials" >}} + [Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} [Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} [InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} diff --git a/content/en/docs/2024.3/Reference/data-types/credentials/usercredentials.md b/content/en/docs/2024.3/Reference/data-types/credentials/usercredentials.md index 4351f2c53..1a0a5b4ba 100644 --- a/content/en/docs/2024.3/Reference/data-types/credentials/usercredentials.md +++ b/content/en/docs/2024.3/Reference/data-types/credentials/usercredentials.md @@ -65,7 +65,7 @@ The Password is used to define the password of the user to authenticate as. This ### LogonType -The LogonType is used to define what type of logon method to use. This property is a [LogonType][] which is an enum. +The LogonType is used to define what type of logon method to use to authenticate the user. This property is a [LogonType][] which is an enum. | | | |--------------------|---------------------------| @@ -84,8 +84,8 @@ The following table shows some of the ways that `UserCredentials` can be created |-|-|-|-|-| | Use a `UserCredentials` constructor | `new UserCredentials(domain: "domain", username: "username", password: "encryptedPassword")` | `{"Domain": "domain", "Username": "username", "Password": "encryptedPassword"}` | Expression | Domain specified | | | `new UserCredentials(username: "username", password: "encryptedPassword")` | `{"Domain": null, "Username": "username", "Password": "encryptedPassword"}` | Expression | Domain not specified | -| | `new UserCredentials(domain: "domain", username: "username", password: "encryptedPassword", logontype: LogonType.Network)` | `{"Domain": "domain", "Username": "username", "Password": "encryptedPassword", "LogonType": LogonType.Network}` | Expression | Domain and LogonType specified | -| | `new UserCredentials(username: "username", password: "encryptedPassword", logontype: LogonType.Network)` | `{"Domain": null, "Username": "username", "Password": "encryptedPassword", "LogonType": LogonType.Network}` | Expression | Domain and LogonType not specified | +| | `new UserCredentials(domain: "domain", username: "username", password: "encryptedPassword", logonType: LogonType.Network)` | `{"Domain": "domain", "Username": "username", "encryptedPassword", "LogonType": "LogonType.Network"}` | Expression | Domain and LogonType specified | +| | `new UserCredentials(username: "username", password: "encryptedPassword", logonType: LogonType.Network)` | `{"Domain": null, "Username": "username", "Password": "encryptedPassword", "LogonType": "LogonType.Network"}` | Expression | Domain and LogonType not specified | A `UserCredentials` can also be created using the Literal Editor by filling in the necessary values for the following properties: @@ -94,13 +94,13 @@ A `UserCredentials` can also be created using the Literal Editor by filling in t | `Domain` | `EncryptableText` | `"domain"` | [Domain][Domain Property] defines the domain or server to authenticate with. | | `Username` | `EncryptableText` | `"username"` | [Username][Username Property] defines the user to authenticate as. | | `Password` | `EncryptedText` | `"encryptedPassword"` | [Password][Password Property] defines the password of the user to authenticate as. | -| `LogonType` | `LogonType` | `LogonType.Network` | [LogonType][LogonType Property] defines the logon type of the user to authenticate as. | +| `LogonType` | `LogonType` | `LogonType.Network` | [LogonType][LogonType Property] defines what type of logon method to use to authenticate the user. | ### Convert UserCredentials to Text | Method | Example | Result | Editor Support | Notes | |-|-|-|-|-| -| Use `Convert Object To Json` block | where `Object` property has a value of `{"Domain": "domain", "Username": "username", "Password": "encryptedPassword", "LogonType": LogonType.Network}` | `"{\r\n \"Domain\": \"domain\",\r\n \"Username\": \"username\",\r\n \"Password\": \"encryptedPassword\",\r\n \"LogonType\": 3\r\n}"` | N/A | See [Convert Object To Json][] | +| Use `Convert Object To Json` block | where `Object` property has a value of `{"Domain": "domain", "Username": "username", "Password": "encryptedPassword", "LogonType": "LogonType.Network"}` | `"{\r\n \"Domain\": \"domain\",\r\n \"Username\": \"username\",\r\n \"Password\": \"encryptedPassword\",\r\n \"LogonType\": 3\r\n}"` | N/A | See [Convert Object To Json][] | ### Property Editor Support From b0dd1f382874218e02b4fc083e3d1043a89bb7b4 Mon Sep 17 00:00:00 2001 From: cortex-jk Date: Mon, 24 Jun 2024 17:03:08 +0100 Subject: [PATCH 3/7] Updated logontype.md and common-properties.md. --- .../blocks/block-properties/common-properties.md | 7 ++----- .../2024.3/Reference/data-types/credentials/logontype.md | 3 ++- 2 files changed, 4 insertions(+), 6 deletions(-) diff --git a/content/en/docs/2024.3/Reference/Concepts/fundamentals/blocks/block-properties/common-properties.md b/content/en/docs/2024.3/Reference/Concepts/fundamentals/blocks/block-properties/common-properties.md index a4f28c15d..38bfeb64f 100644 --- a/content/en/docs/2024.3/Reference/Concepts/fundamentals/blocks/block-properties/common-properties.md +++ b/content/en/docs/2024.3/Reference/Concepts/fundamentals/blocks/block-properties/common-properties.md @@ -59,12 +59,9 @@ If [UserCredentials][] has an invalid domain, username, password or [LogonType][ If [UserCredentials][] has a `null` username or password, a [PropertyNullException][] will be thrown when the [block][] is executed. -{{< figure src="/images/set-variable/set-variable-run-as.svg" >}} - -The [LogonType][] is used to identify the method of impersonation. The default is `LogonType.Network`, and does not need to be declared in the constructor, but can be changed. +By default, the type of logon method used to authenticate the Run As user is `LogonType.Network`; this works for most scenarios. For scenarios that require a different type of logon method (e.g. connecting to a remote database), the correct [LogonType][] (e.g. `LogonType.NewCredentials`) can be specified as part of the [UserCredentials][]. -For example, if you are trying to access a remote machine, then `LogonType.Network` would be the correct [LogonType][]. -Whereas if you are trying to access a database on a remote machine, then `LogonType.NewCredentails` would be the correct [LogonType][]. +{{< figure src="/images/set-variable/set-variable-run-as.svg" >}} ## Block Timeout Property diff --git a/content/en/docs/2024.3/Reference/data-types/credentials/logontype.md b/content/en/docs/2024.3/Reference/data-types/credentials/logontype.md index de21d1fa9..b71cd6f70 100644 --- a/content/en/docs/2024.3/Reference/data-types/credentials/logontype.md +++ b/content/en/docs/2024.3/Reference/data-types/credentials/logontype.md @@ -53,7 +53,7 @@ The `LogonType` data type is used to represent the type of logon method to use t |------------|----------------------------| | **Name:** | NewCredentials | | **Value:** | [Int32][] with value `9` | -| **Notes:** | Represents a clone of the user's current logon. For local operations, it uses the same local identity. For network operations, it uses the identity of the credentials supplied. This should be used when authenticating against a remote database as a Windows User. Allows the caller to clone its current logon token and specify new credentials for outbound connections. The new logon session has the same local identity but uses different credentials for other network connections. This logon type should be used when authenticating against a remote database. | +| **Notes:** | Represents a clone of the user's current logon. For local operations, it uses the same local identity. For network operations, it uses the identity of the credentials supplied. This should be used when authenticating against a remote database as a Windows User. If connecting to a local database as a Windows user, [Network][] should be used. | ## Remarks @@ -121,6 +121,7 @@ The following table shows some of the ways that a `LogonType` can be converted t ### Known Limitations - When [LogonType][] is set to `LogonType.NewCredentials` and trying to connect to a localhost database, it will not recognise the UserCredentials. To fix this use `LogonType.Network` as the [LogonType][]. +- When [LogonType][] is set to `LogonType.Network` and trying to connect to a remote database, it will not recognise the UserCredentials. To fix this use `LogonType.NewCredentials` as the [LogonType][]. ## See Also From 2acf7f03ed8e13ac8e4031283af2ea94c4c19a7f Mon Sep 17 00:00:00 2001 From: cortex-jk Date: Tue, 25 Jun 2024 10:48:38 +0100 Subject: [PATCH 4/7] Added blogs.oracle.com to the IgnoreURLs --- .htmltest.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/.htmltest.yml b/.htmltest.yml index d3ddadf6e..301b5ca83 100644 --- a/.htmltest.yml +++ b/.htmltest.yml @@ -22,6 +22,7 @@ IgnoreURLs: - "http://www.mimekit.net/docs/.*" - "https://nssm.cc/" - "https://code.visualstudio.com/" +- "https://blogs.oracle.com/.*" IgnoreDirs: - "docs/?.*/_print/" - "docs/?.*/_shared/" From 7c3e27f3e3ada1aa0ab2ed340234ee4a144d7d16 Mon Sep 17 00:00:00 2001 From: cortex-jk Date: Tue, 25 Jun 2024 17:20:51 +0100 Subject: [PATCH 5/7] Updated the execute data command block. --- .../execute-data-command-block-1.md | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/content/en/docs/2024.3/Reference/Blocks/data/execute-data-command/execute-data-command-block-1.md b/content/en/docs/2024.3/Reference/Blocks/data/execute-data-command/execute-data-command-block-1.md index 4e11298f0..1d22fcfca 100644 --- a/content/en/docs/2024.3/Reference/Blocks/data/execute-data-command/execute-data-command-block-1.md +++ b/content/en/docs/2024.3/Reference/Blocks/data/execute-data-command/execute-data-command-block-1.md @@ -700,9 +700,13 @@ If it is desirable to have any issues reported as messages when trying to debug ### RunAs -If no credentials are provided in the [ConnectionDetails][], then the [RunAsProperty][] can be used to authenticate with. Some [ConnectionDetails][], do require the connection string to contain `Trusted_Connection=True;` or `userid=;` to make use of the [UserCredentials][]. +RunAs can be used to connect to a database as a Windows user, rather than a SQL user. -If you are using [UserCredentials][] to authenticate in the [RunAsProperty][], then it should be noted that the [LogonType][] is used to identify the method of impersonation. The default is `LogonType.Network`, which should be used for accessing a local database, however if you are trying to access a remote database, then `LogonType.NewCredentials` would be the correct [LogonType][] to use. +To connect as a Windows user: +- An appropriate connection string (e.g. [Oracle][], [SQL Server][]) must be specified in the [Connection Details][Connection Details Property]. +- [UserCredentials][] for the Windows user must be specified in the [Run As property][RunAsProperty]. + +If connecting to a local database, the [UserCredentials][] must specify the [LogonType][] to be `LogonType.Network`; if connecting to a remote database, the [LogonType][] must be `LogonType.NewCredentials`. ### Known Limitations @@ -789,8 +793,8 @@ When using a [Parameterised Command][Parameterised Commands] to execute a stored [Variables]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Variables.MainDoc" >}} [Object Casting]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Objects.ObjectCasting.MainDoc" >}} [UserCredentials]: {{< url path="Cortex.Reference.DataTypes.Credentials.UserCredentials.MainDoc" >}} -[RunAsProperty]: {{< url path="Cortex.Reference.DataTypes.Credentials.UserCredentials.LogonType" >}} -[LogonType]: {{< url path="Cortex.Reference.DataTypes.Credentials.LogonType.MainDoc" >}} +[LogonType]: {{< url path="Cortex.Reference.DataTypes.Credentials.UserCredentials.LogonType" >}} +[RunAsProperty]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.CommonProperties.RunAsProperty" >}} [Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} From c649dcdb889e713461f1b249973b5d1dac48a2ff Mon Sep 17 00:00:00 2001 From: cortex-jk Date: Wed, 26 Jun 2024 09:04:08 +0100 Subject: [PATCH 6/7] Added URLs for connection strings in execute data command block --- .../data/execute-data-command/execute-data-command-block-1.md | 4 +++- data/urls.toml | 1 + 2 files changed, 4 insertions(+), 1 deletion(-) diff --git a/content/en/docs/2024.3/Reference/Blocks/data/execute-data-command/execute-data-command-block-1.md b/content/en/docs/2024.3/Reference/Blocks/data/execute-data-command/execute-data-command-block-1.md index 1d22fcfca..38ac8d33f 100644 --- a/content/en/docs/2024.3/Reference/Blocks/data/execute-data-command/execute-data-command-block-1.md +++ b/content/en/docs/2024.3/Reference/Blocks/data/execute-data-command/execute-data-command-block-1.md @@ -703,7 +703,7 @@ If it is desirable to have any issues reported as messages when trying to debug RunAs can be used to connect to a database as a Windows user, rather than a SQL user. To connect as a Windows user: -- An appropriate connection string (e.g. [Oracle][], [SQL Server][]) must be specified in the [Connection Details][Connection Details Property]. +- An appropriate connection string (e.g. [Oracle][OracleConnectionStringIntegratedSecurity], [SQL Server][SqlConnectionStringTrustedConnection]) must be specified in the [Connection Details][Connection Details Property]. - [UserCredentials][] for the Windows user must be specified in the [Run As property][RunAsProperty]. If connecting to a local database, the [UserCredentials][] must specify the [LogonType][] to be `LogonType.Network`; if connecting to a remote database, the [LogonType][] must be `LogonType.NewCredentials`. @@ -800,3 +800,5 @@ When using a [Parameterised Command][Parameterised Commands] to execute a stored [OracleBlockStatement]: {{< url path="Oracle.PL-SQL.BlockStatement" >}} [SQL Injection]: {{< url path="W3.SqlInjection" >}} +[SqlConnectionStringTrustedConnection]: {{< url path="ConnectionStrings.SqlConnectionTrustedConnection" >}} +[OracleConnectionStringIntegratedSecurity]: {{< url path="ConnectionStrings.OracleConnectionIntegratedSecurity" >}} diff --git a/data/urls.toml b/data/urls.toml index 493db32f0..4e4108392 100644 --- a/data/urls.toml +++ b/data/urls.toml @@ -2211,6 +2211,7 @@ [ConnectionStrings] MainDoc = "https://www.connectionstrings.com/" SqlConnection = "https://www.connectionstrings.com/sqlconnection/" + SqlConnectionTrustedConnection = "https://www.connectionstrings.com/microsoft-data-sqlclient/trusted-connection/" OracleConnection = "https://www.connectionstrings.com/oracle-data-provider-for-net-odp-net/" OracleConnectionIntegratedSecurity = "https://www.connectionstrings.com/oracle-data-provider-for-net-odp-net/using-integrated-security/" [ElasticSearch] From 07f06615d51aadb52d9ecd0747457b263ac5038d Mon Sep 17 00:00:00 2001 From: cortex-jk Date: Wed, 26 Jun 2024 10:19:11 +0100 Subject: [PATCH 7/7] Updated LogonType link --- .../fundamentals/blocks/block-properties/common-properties.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/content/en/docs/2024.3/Reference/Concepts/fundamentals/blocks/block-properties/common-properties.md b/content/en/docs/2024.3/Reference/Concepts/fundamentals/blocks/block-properties/common-properties.md index 38bfeb64f..b045abbe8 100644 --- a/content/en/docs/2024.3/Reference/Concepts/fundamentals/blocks/block-properties/common-properties.md +++ b/content/en/docs/2024.3/Reference/Concepts/fundamentals/blocks/block-properties/common-properties.md @@ -55,7 +55,7 @@ Once the [block][] has finished executing, the next block to execute will run as The default value of `null` also results in the [block][] executing as the user the [Execution Service][] is running as. -If [UserCredentials][] has an invalid domain, username, password or [LogonType][], a [RunAsException][] will be thrown when the [block][] is executed. +If [UserCredentials][] has an invalid domain, username, password or [LogonType][UserCredentialsLogonType], a [RunAsException][] will be thrown when the [block][] is executed. If [UserCredentials][] has a `null` username or password, a [PropertyNullException][] will be thrown when the [block][] is executed. @@ -141,6 +141,8 @@ None [TimePeriod]: {{< url path="Cortex.Reference.DataTypes.DateAndTime.TimePeriod.MainDoc" >}} [UserCredentials]: {{< url path="Cortex.Reference.DataTypes.Credentials.UserCredentials.MainDoc" >}} +[UserCredentialsLogonType]: {{< url path="Cortex.Reference.DataTypes.Credentials.UserCredentials.LogonType" >}} + [BlockTimeoutException]: {{< url path="Cortex.Reference.Exceptions.Flows.Blocks.BlockTimeoutException.MainDoc" >}} [InvalidBlockTimeoutException]: {{< url path="Cortex.Reference.Exceptions.Flows.Blocks.InvalidBlockTimeoutException.MainDoc" >}}