jwtPS

1.1.3

jwtPS.dll-Help.xml

<?xml version="1.0" encoding="utf-8"?>
<helpItems schema="maml" xmlns="http://msh">
  <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp">
    <command:details>
      <command:name>ConvertFrom-Jwt</command:name>
      <command:verb>ConvertFrom</command:verb>
      <command:noun>Jwt</command:noun>
      <maml:description>
        <maml:para>This function accepts a string in the format of a Json Web Token (JWT) and returns a hashtable with of the header and claimset converted from Base 64.</maml:para>
      </maml:description>
    </command:details>
    <maml:description>
      <maml:para>The string must be a valid JWT. The function will split the string into the three parts of a JWT and convert the first two parts back into the human-readable format. The header and the claimset will be returned as a hashtable.</maml:para>
    </maml:description>
    <command:syntax>
      <command:syntaxItem>
        <maml:name>ConvertFrom-Jwt</maml:name>
        <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByValue)" position="named" aliases="none">
          <maml:name>Jwt</maml:name>
          <maml:description>
            <maml:para>Expects string in valid JWT format.</maml:para>
          </maml:description>
          <command:parameterValue required="true" variableLength="false">String</command:parameterValue>
          <dev:type>
            <maml:name>String</maml:name>
            <maml:uri />
          </dev:type>
          <dev:defaultValue>None</dev:defaultValue>
        </command:parameter>
      </command:syntaxItem>
    </command:syntax>
    <command:parameters>
      <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByValue)" position="named" aliases="none">
        <maml:name>Jwt</maml:name>
        <maml:description>
          <maml:para>Expects string in valid JWT format.</maml:para>
        </maml:description>
        <command:parameterValue required="true" variableLength="false">String</command:parameterValue>
        <dev:type>
          <maml:name>String</maml:name>
          <maml:uri />
        </dev:type>
        <dev:defaultValue>None</dev:defaultValue>
      </command:parameter>
    </command:parameters>
    <command:inputTypes>
      <command:inputType>
        <dev:type>
          <maml:name>None</maml:name>
        </dev:type>
        <maml:description>
          <maml:para></maml:para>
        </maml:description>
      </command:inputType>
    </command:inputTypes>
    <command:returnValues>
      <command:returnValue>
        <dev:type>
          <maml:name>System.Object</maml:name>
        </dev:type>
        <maml:description>
          <maml:para></maml:para>
        </maml:description>
      </command:returnValue>
    </command:returnValues>
    <maml:alertSet>
      <maml:alert>
        <maml:para></maml:para>
      </maml:alert>
    </maml:alertSet>
    <command:examples>
      <command:example>
        <maml:title>-------------------------- Example 1 --------------------------</maml:title>
        <dev:code>PS C:\&gt; ConvertFrom-Jwt -Jwt "eyJ0eXAi[...]I1NiJ9.eyJpYXQiOjEyMzQ1Njc[...]IsImV4cCI6OTg3NjU0MzIxfQ.K741[...]Yf2aE68CHY"</dev:code>
        <dev:remarks>
          <maml:para></maml:para>
        </dev:remarks>
      </command:example>
    </command:examples>
    <command:relatedLinks />
  </command:command>
  <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp">
    <command:details>
      <command:name>New-Jwt</command:name>
      <command:verb>New</command:verb>
      <command:noun>Jwt</command:noun>
      <maml:description>
        <maml:para>The function creates a Json Web Token (JWT).</maml:para>
      </maml:description>
    </command:details>
    <maml:description>
      <maml:para>Three parts are required to create a JWT: the algorithm which decides how the body of the JWT will be encrypted, the claimset which carries the message, and the secret (Password for HMAC encryption or private key for RSA, ECDsa or Pss).</maml:para>
    </maml:description>
    <command:syntax>
      <command:syntaxItem>
        <maml:name>New-Jwt</maml:name>
        <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="named" aliases="none">
          <maml:name>Algorithm</maml:name>
          <maml:description>
            <maml:para>Set the encryption algorithm.</maml:para>
          </maml:description>
          <command:parameterValue required="true" variableLength="false">cryptographyType</command:parameterValue>
          <dev:type>
            <maml:name>cryptographyType</maml:name>
            <maml:uri />
          </dev:type>
          <dev:defaultValue>None</dev:defaultValue>
        </command:parameter>
        <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="named" aliases="none">
          <maml:name>Payload</maml:name>
          <maml:description>
            <maml:para>Provide the claimset.</maml:para>
          </maml:description>
          <command:parameterValue required="true" variableLength="false">Hashtable</command:parameterValue>
          <dev:type>
            <maml:name>Hashtable</maml:name>
            <maml:uri />
          </dev:type>
          <dev:defaultValue>None</dev:defaultValue>
        </command:parameter>
        <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="named" aliases="none">
          <maml:name>Secret</maml:name>
          <maml:description>
            <maml:para>The secret is a password for HMAC encryption and a private key for RSA, ECDsa or Pss algorithms.</maml:para>
          </maml:description>
          <command:parameterValue required="true" variableLength="false">String</command:parameterValue>
          <dev:type>
            <maml:name>String</maml:name>
            <maml:uri />
          </dev:type>
          <dev:defaultValue>None</dev:defaultValue>
        </command:parameter>
        <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="named" aliases="none">
          <maml:name>Header</maml:name>
          <maml:description>
            <maml:para>Here you can provide a hashtable with additional parameters for the JWT header.</maml:para>
          </maml:description>
          <command:parameterValue required="true" variableLength="false">Hashtable</command:parameterValue>
          <dev:type>
            <maml:name>Hashtable</maml:name>
            <maml:uri />
          </dev:type>
          <dev:defaultValue>None</dev:defaultValue>
        </command:parameter>
      </command:syntaxItem>
      <command:syntaxItem>
        <maml:name>New-Jwt</maml:name>
        <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="named" aliases="none">
          <maml:name>Algorithm</maml:name>
          <maml:description>
            <maml:para>Set the encryption algorithm.</maml:para>
          </maml:description>
          <command:parameterValue required="true" variableLength="false">cryptographyType</command:parameterValue>
          <dev:type>
            <maml:name>cryptographyType</maml:name>
            <maml:uri />
          </dev:type>
          <dev:defaultValue>None</dev:defaultValue>
        </command:parameter>
        <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="named" aliases="none">
          <maml:name>Payload</maml:name>
          <maml:description>
            <maml:para>Provide the claimset.</maml:para>
          </maml:description>
          <command:parameterValue required="true" variableLength="false">Hashtable</command:parameterValue>
          <dev:type>
            <maml:name>Hashtable</maml:name>
            <maml:uri />
          </dev:type>
          <dev:defaultValue>None</dev:defaultValue>
        </command:parameter>
        <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="named" aliases="none">
          <maml:name>FilePath</maml:name>
          <maml:description>
            <maml:para>Provide the path to the key.</maml:para>
          </maml:description>
          <command:parameterValue required="true" variableLength="false">FileInfo</command:parameterValue>
          <dev:type>
            <maml:name>FileInfo</maml:name>
            <maml:uri />
          </dev:type>
          <dev:defaultValue>None</dev:defaultValue>
        </command:parameter>
        <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="named" aliases="none">
          <maml:name>Header</maml:name>
          <maml:description>
            <maml:para>Here you can provide a hashtable with additional parameters for the JWT header.</maml:para>
          </maml:description>
          <command:parameterValue required="true" variableLength="false">Hashtable</command:parameterValue>
          <dev:type>
            <maml:name>Hashtable</maml:name>
            <maml:uri />
          </dev:type>
          <dev:defaultValue>None</dev:defaultValue>
        </command:parameter>
      </command:syntaxItem>
    </command:syntax>
    <command:parameters>
      <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="named" aliases="none">
        <maml:name>Algorithm</maml:name>
        <maml:description>
          <maml:para>Set the encryption algorithm.</maml:para>
        </maml:description>
        <command:parameterValue required="true" variableLength="false">cryptographyType</command:parameterValue>
        <dev:type>
          <maml:name>cryptographyType</maml:name>
          <maml:uri />
        </dev:type>
        <dev:defaultValue>None</dev:defaultValue>
      </command:parameter>
      <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="named" aliases="none">
        <maml:name>Payload</maml:name>
        <maml:description>
          <maml:para>Provide the claimset.</maml:para>
        </maml:description>
        <command:parameterValue required="true" variableLength="false">Hashtable</command:parameterValue>
        <dev:type>
          <maml:name>Hashtable</maml:name>
          <maml:uri />
        </dev:type>
        <dev:defaultValue>None</dev:defaultValue>
      </command:parameter>
      <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="named" aliases="none">
        <maml:name>Secret</maml:name>
        <maml:description>
          <maml:para>The secret is a password for HMAC encryption and a private key for RSA, ECDsa or Pss algorithms.</maml:para>
        </maml:description>
        <command:parameterValue required="true" variableLength="false">String</command:parameterValue>
        <dev:type>
          <maml:name>String</maml:name>
          <maml:uri />
        </dev:type>
        <dev:defaultValue>None</dev:defaultValue>
      </command:parameter>
      <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="named" aliases="none">
        <maml:name>FilePath</maml:name>
        <maml:description>
          <maml:para>Provide the path to the key.</maml:para>
        </maml:description>
        <command:parameterValue required="true" variableLength="false">FileInfo</command:parameterValue>
        <dev:type>
          <maml:name>FileInfo</maml:name>
          <maml:uri />
        </dev:type>
        <dev:defaultValue>None</dev:defaultValue>
      </command:parameter>
      <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="named" aliases="none">
        <maml:name>Header</maml:name>
        <maml:description>
          <maml:para>Here you can provide a hashtable with additional parameters for the JWT header.</maml:para>
        </maml:description>
        <command:parameterValue required="true" variableLength="false">Hashtable</command:parameterValue>
        <dev:type>
          <maml:name>Hashtable</maml:name>
          <maml:uri />
        </dev:type>
        <dev:defaultValue>None</dev:defaultValue>
      </command:parameter>
    </command:parameters>
    <command:inputTypes>
      <command:inputType>
        <dev:type>
          <maml:name>None</maml:name>
        </dev:type>
        <maml:description>
          <maml:para></maml:para>
        </maml:description>
      </command:inputType>
    </command:inputTypes>
    <command:returnValues>
      <command:returnValue>
        <dev:type>
          <maml:name>System.String</maml:name>
        </dev:type>
        <maml:description>
          <maml:para></maml:para>
        </maml:description>
      </command:returnValue>
    </command:returnValues>
    <maml:alertSet>
      <maml:alert>
        <maml:para></maml:para>
      </maml:alert>
    </maml:alertSet>
    <command:examples>
      <command:example>
        <maml:title>-------------------------- Example 1 --------------------------</maml:title>
        <dev:code>PS C:\&gt; $algorithm = [jwtTypes+algorithm]::HMAC
PS C:\&gt; $encryption = [jwtTypes+encryption]::SHA256
PS C:\&gt; $cryptoType = [jwtTypes+cryptographyType]::new($algorithm, $encryption)
PS C:\&gt; New-Jwt -Payload @{'iat'=123456789} -Algorithm $cryptoType -Secret P@ssw0rd</dev:code>
        <dev:remarks>
          <maml:para>This function returns a JWT with HMAC encryption.</maml:para>
        </dev:remarks>
      </command:example>
      <command:example>
        <maml:title>-------------------------- Example 2 --------------------------</maml:title>
        <dev:code>PS C:\&gt; $algorithm = [jwtTypes+algorithm]::RSA
PS C:\&gt; $encryption = [jwtTypes+encryption]::SHA384
PS C:\&gt; $cryptoType = [jwtTypes+cryptographyType]::new($algorithm, $encryption)
PS C:\&gt; $customJwtHeader = @{"enc" = "A128CBC-HS256"}
PS C:\&gt; New-Jwt -Payload @{'iat'=123456789} -Algorithm $cryptoType -FilePath Path\To\File.pem -Header $customJwtHeader</dev:code>
        <dev:remarks>
          <maml:para>This function returns a JWT with RSA encryption and SHA386 and a custom header.</maml:para>
        </dev:remarks>
      </command:example>
      <command:example>
        <maml:title>-------------------------- Example 3 --------------------------</maml:title>
        <dev:code>PS C:\&gt; $algorithm = [jwtTypes+algorithm]::ECDsa
PS C:\&gt; $encryption = [jwtTypes+encryption]::SHA512
PS C:\&gt; $cryptoType = [jwtTypes+cryptographyType]::new($algorithm, $encryption)
PS C:\&gt; New-Jwt -Payload @{'iat'=123456789} -Algorithm $cryptoType -FilePath Path\To\File.pem</dev:code>
        <dev:remarks>
          <maml:para>This function returns a JWT with ECDsa encryption and SHA512.</maml:para>
        </dev:remarks>
      </command:example>
    </command:examples>
    <command:relatedLinks />
  </command:command>
</helpItems>