Super-ExMerge On-line Documentation

⌘K
  2. Home
  4. Docs
  6. Super-ExMerge On-line Doc...
  8. PowerShell Cmdlet Referen...
  10. New-FormattedCredential

New-FormattedCredential

Use this cmdlet to create a new FormattedCredential object that specifies credential details in a secure way from text.

New-FormattedCredential

  • -Username
  • [-Password]
  • [-EncryptType]
  • [-ReturnFormattedString]

New-FormattedCredential

  • -UserName
  • -SecurePassword
  • [-EncryptType]
  • [-ReturnFormattedString]

New-FormattedCredential

  • -UserName
  • -PromptForPassword
  • [-EncryptType]
  • [-ReturnFormattedString]

New-FormattedCredential

  • -Credential
  • [-EncryptType]
  • [-ReturnFormattedString]

New-FormattedCredential

  • -FormattedString

    Description

    Jump To:

    The New-FormattedCredential cmdlet creates a formatted credential object which provides a mechanism to create secure credentials for use by Priasoft solutions.
    A formatted credential is a text string that includes both the user identity as well as the password and can take one of several formats:
    Review the examples below for use of these formats.

    Clear Text:
    This format is the simplest format and is the user identity followed by the password. When using this format, the clear text password will be encrypted using the HostKey. The FormattedCredential object will not allow for the storage of a clear-text password.
    Example: user@source.com:Password

    Encoded Password:
    This format obscures the password as a Base64 encoded string. Although the password is not in clear text, the password value is also not protected. Any script or code that can decode Base64 can retrieve the password.
    Example: user@source.com:B64=UGFzc3dvcmQ=

    HostKey Encrypted:
    This format encrypts the password using a unique key that is specific to the host upon which the encrypted password is generated. As such, this format can only be used on the host that generated the encrypted password.
    Example: user@source.com:HostKey#FL5qdn9HcKPVVxPqxlHN0Q==

    Pre-shared Key Encrypted:
    This format encrypts the password using a custom encryption key and allows for the encrypted password to be used on another host, provided that the same encryption key is used. In order to use this format, a Pre-shared Key must be set on the host prior to use. Use the Set-PreSharedKey cmdlet to set the key for the current host.
    Example: user@source.com:PSK#/LWNB20yPJY2vgpxNF1FUw==

    Cached Credential:
    This format will cause Super-ExMerge to pull the credential from the Priasoft cached credential manager.
    Example: Cached:MyCredential
    Example: Cached:user@source.com

    Examples

    Jump To:
    Example 1
      New-FormattedCredential -UserName user@source.com -Password 'MyP@ssw0rd!'

    This example creates a formatted credential with a clear text password.
    When the -EncryptType parameter is not provided, the HostKey encryption type is used by default.
    The formatted credential string would be similar to the following for this example:
    user@source.com:HostKey#uHjNyVvqkpq+T1pnoN3uQQ==

    Example 2
      New-FormattedCredential -UserName user@source.com -PromptForPassword -EncryptType Base64Encoded
EnterPassword:> ***********

    This example will create a formatted credential by prompting for the password (using character masking) and will encode the password as a Base64 encoded value.
    The formatted credential string would be as follows for this example:
    user@source.com:B64=TXlQQGFzc3cwcmQh

    Example 3
      $myPass = ConvertTo-SecureString -Force -AsPlainText -String MyP@ssw0rd!
New-FormattedCredential -Username user@source.com -SecurePassword $myPass -EncryptType HostKey

    This example will create a formatted credential using a SecureString password as input and then encrypting it using the HostKey of the local host. The password can only be decrypted and used on the same host from which the encrypted password was created.
    The formatted credential string would be similar to the following for this example:
    user@source.com:HostKey#uHjNyVvqkpq+T1pnoN3uQQ==

    Example 4
      $creds = Get-Credential
New-FormattedCredential -Credential $creds -EncryptType PreSharedKey

    This example will create a formatted credential that uses a PSCredential object to collect the username and password on input, and then is encrypted using a Pre-shared Key that is stored on the local host. The password can only be decrypted and used on another host that has the same pre-shared key. Use the Set-PresharedKey cmdlet to establish a pre-shared key on a host.
    If this cmdlet is used on a host that does not have a pre-shared key established, or the key does not match the one used to encrypt the password, an error will occur and no object is returned.
    The formatted credential string would be similar to the following for this example:
    user@source.com:PSK#26jK7Ml/MyMOnJbLwcxCEQ==

    Example 5
      
$sourceCred = New-FormattedCredential -UserName SourceMapi
$targetCred = New-FormattedCredential -UserName TargetMapi

    This example will attempt to create two formatted credentials by searching the Priasoft credential cache for a SourceMapi and a TargetMapi credential. If more than one SourceMapi or TargetMapi credential exists in the cache, an error occurs stating that the search result was ambiguous. If no credential is found, an error occurs stating that no credential was found.

    The SourceMapi and TargetMapi accounts normally exists as a result of using Priasoft Setup Wizard tools that are part of the Priasoft Migration Suite for Exchange. The SourceMapi and TargetMapi accounts are highly secured accounts for use in on-premises environments.

    The formatted credential strings for these two results will look like the following (provided that the credentials were found in the cache):
    CachedUser:SourceMapi
    CachedUser:TargetMapi

    Example 6
      New-FormattedCredential -username user@source.com

    This example will create a new formatted credential by searching the Priasoft credential cache for a username that matches the value provided. If no cached credential is found, an error occurs stating that no credential could be found. If more than one credential is found with the same username, an error occurs stating that the username is ambiguous.

    An example of the formatted credential string for this example will be as follows:
    CachedUser:user@source.com

    Example 7
      New-FormattedCredential -username server01.domain.com

    This example will create a new formatted credential by searching the Priasoft credential cache for a server name that matches the value provided. If no cached credential is found, an error occurs stating that no credential could be found. If more than one credential is found with the same server name, an error occurs stating that the username is ambiguous.
    An example of the formatted credential string for this example will be as follows:
    CachedUser:server01.domain.com


    Parameters

    Jump To:

    -UserName

    The UserName parameter specifies the user identity of the formatted credential.

    If this parameter is used alone, a search for the value is made against the Priasoft credential cache.

    The UserName parameter can be of any format of an user identity: ‘DOMAIN\username‘ and ‘user@domain.com‘ are two common examples. Note that Office365 only accepts UPN style identities.

    Required:
    Yes
    Type:
    String
    Aliases:
    None
    Position:
    0
    Default Value:
    None

    -Password

    The Password parameter sets the password of the formatted credential. The password parameter should be passed in as plain text. The -EncryptType parameter determines how the password value is treated upon return.

    Required:
    No
    Type:
    String
    Aliases:
    None
    Position:
    1
    Default Value:
    None

    -SecurePassword

    The SecurePassword parameter specifies the password of the formatted credential using a SecureString object to securely hold the password.

    Required:
    Yes
    Type:
    SecureString
    Aliases:
    None
    Position:
    1
    Default Value:
    None

    -PromptForPassword

    The PromptForPassword will prompt for the password using character masking so as to obscure the password being typed.
    NOTE: This parameter can only be used in an interactive session and from applications that host a PowerShell User Interface. If $host.UI is $null, this parameter will throw an error.

    Required:
    Yes
    Type:
    SwitchParameter
    Aliases:
    None
    Position:
    1
    Default Value:
    False

    -Credential

    The Credential parameter accepts a PSCredential object that is used to create a FormattedCredential. The Username and Password values of the PSCredential object are used to create the FormattedCredential.

    NOTE: This parameter can only be used in an interactive session and from applications that host a PowerShell User Interface. If $host.UI is $null, this parameter will throw an error.
    NOTE: With PowerShell v4.0 and later, passing an uninitialized variable to this parameter will cause a credential prompt to appear. This can shortcut scripting since a separate line for Get-Credential is not needed. Example:
    New-FormattedCredential -Credential $newVariable
    In contrast to:
    $cred = Get-Credential
    New-FormattedCredential -Credential $cred

    Required:
    Yes
    Type:
    PSCredential
    Aliases:
    None
    Position:
    0
    Default Value:
    None

    -FormattedString

    The FormattedString parameter specifies a pre-made formatted credential string, which if parsed without errors, will return a new FormattedCredential object.
    This can be an easy way to validate that a FormattedCredential string is valid.

    Required:
    Yes
    Type:
    String
    Aliases:
    None
    Position:
    0
    Default Value:
    None

    -EncryptType

    The EncryptType parameter determines how the Password of the FormattedCredential is encrypted, if at all.
    If this parameter is not used, the value will default to: HostKey.
    EncryptType supports the following values:
    None: No encrypt is made. The password is shown in clear text in the resulting FormattedString value of the FormattedCredential.
    Base64Encoded: The password is encoded as a Base64 string. No encryption of the password is made, only an obfuscation by the encoding.
    HostKey: The password is encrypted using the Rijndael provider and using a host-specific key. Password encrypted this way can only be decrypted on the same host on which it was generated.
    PreSharedKey: The password is encrypted using the Rijndael provider and using a user-provided key. The PreSharedKey can be set using the Set-PresharedKey cmdlet, and must be set before using this encryption type.
    PriasoftCachedCreds: The password is extracted from the Priasoft Cached Credentials from a matching username value that is compared against the Username, Server, and CredentialName properties of each cached credential.

    Required:
    No
    Type:
    FormattedEncryptionTypes (Enum)
    Aliases:
    None
    Position:
    2
    Default Value:
    HostKey

    -ReturnFormattedString

    The ReturnFormattedString switch parameter determines whether a string value or a FormattedCredential object is place on the pipeline.

    Required:
    No
    Type:
    SwitchParameter
    Aliases:
    None
    Position:
    Not a positioned parameter. Use by name only.
    Default Value:
    False

    Output

    Jump To:

    This cmdlet will place either a String value or a FormattedCredential object on the pipeline.

    How can we help?