Classe tJWT

JSON Web Token (JWT) é um padrão aberto (RFC 7519) que define uma maneira compacta e independente de transmitir com segurança informações entre Cliente e Servidor como um objeto JSON. O token JWT é assinado digitalmente utilizando algoritmos de criptografia que podem ser verificados, bem como as informações contídas dentro dele. A grande vantagem de seu uso é que possibilita realizar comunicação segura de objetos JSON mesmo utilizando conexões inseguras como HTTP, é simples, leve e eficiente. Para maiores informações, recomenda-se a leitura da RFC: https://tools.ietf.org/html/rfc7519

Hierarquia

tJWT
- tJWT

Observações

Exemplos

User Function testjwt()
  Local pubKey := PUBKEY()
  Local privKey := PRIVKEY()
  Local token:= ""
  // Cria um novo token
  token:= u_newtoken(pubKey,privKey)
  
  Sleep(5000)

  // Verifica Token
  u_vertoken(token,pubKey,privKey)

Return


// Criação e assinatura de token
User Function newtoken(pubKey,privKey)
  Local genToken := ""
  Local oTokenJWT := Nil
  Local claims := Nil
  Local aAudience := Nil
  
  // Instancia da classe
  oTokenJWT:=tJWT():New()
  
  // Configuração Token a ser criado e assinado.
  /// Definição das chaves publicas e privadas
  oTokenJWT:setPubKey(pubKey)
  oTokenJWT:setPrivKey(privKey)
  // issuer
  oTokenJWT:setIssuer("auth0")
  // types
  oTokenJWT:setType("JWS")

  // Audience pode setar uma string ou array de strings. Caso seja definido um array diferente, apenas os elementos
  //do tipo caracter serao adicionados.
  aAudience := {1,"Ronaldo","Carlos"}
  oTokenJWT:setAudience(aAudience)

  // Set audience pode ser definido de dois modos e um anula o outro.
  oTokenJWT:setAudience("Teste")

  // Define um conjunto de claims
  claims := JsonObject():new()
  claims['idade'] := 10
  claims['root'] := .T.
  claims['flag'] := 10.55555
  claims['nome'] := "Cristiano Ronaldo"
  claims['dir'] := { "home", "user", 10, 15.5, .T. }

  // Add Public Claim
  oTokenJWT:setPayloadClaim(claims)

  // tempo de expiração em segundos
  oTokenJWT:setExpiresAt(1000000)

  // criação do token com algoritimo rs256
  genToken := oTokenJWT:createToken("rs256")

  if (Len(genToken) == 0)
    conout("Erro na geração de token. Error: "+ oTokenJWT:getLastError())
  end if
  conout("Token gerado: " + genToken)

  FreeObj(oTokenJWT)
  FreeObj(claims)
Return genToken

// Verificação de token
User Function vertoken(token,pubKey,privKey)
  Local oTokenJWT := Nil
  Local ret := .F.

  // Instancia da classe
  oTokenJWT:=tJWT():New()

  /// Definição das chaves publicas e privadas
  oTokenJWT:setPubKey(pubKey)
  oTokenJWT:setPrivKey(privKey)

  // Seta o token gerado
  oTokenJWT:setToken(token)

  if(oTokenJWT:hasIssuer())
    conout("Issuer FOUND on claims.")
  else
    conout("Issuer NOT FOUND on claims.")
  endif

  if(oTokenJWT:hasPayloadClaim("root"))
    conout("ROOT FOUND on claims.")
  else
    conout("ROOT NOT FOUND on claims.")
  endif

  if(oTokenJWT:hasPayloadClaim("dir"))
    conout("DIR FOUND on claims.")
  else
    conout("DIR NOT FOUND on claims.")
  endif

  claims := JsonObject():new()
  claims['dir'] := { "home", "user", 10, 15.5, .T. }
  oTokenJWT:withClaim(claims)

  // Verifica
  ret:= oTokenJWT:verifyToken("rs256")
 
  if(!ret)
    Conout("Token invalido! Error: " + oTokenJWT:getLastError())
  else
   Conout("Token Valido!")
  End If

  FreeObj(oTokenJWT)
Return

Abrangência

17.3.0.19

Construtores

New

Cria um objeto tJWT para configuração, criação, assinatura e manipulação de Tokens.

Sintaxe

tJWT():New()

Retorno

Nome	Tipo	Descrição
oObj	object	Nova instância da classe tJWT

Exemplos

    Local oTokenJWT:= tJWT():New()

Métodos

A classe expõe os seguintes métodos:

createToken

Cria e assina um token no formato JWT.

Sintaxe

createToken( < cAlgo > )

Parâmetros

Nome	Tipo	Descrição	Obrigatório	Referência
cAlgo	character	Indica qual o algoritmo que deverá ser utilizado para assinatura do token.	X

Exemplos

    Local genToken := oTokenJWT:createToken("RS256")

verifyToken

Verifica um determinado token com relação a assinatura, prazo de validade, JOSE Header e demais claims contidas nele.

Sintaxe

verifyToken( < cAlgo > )

Parâmetros

Nome	Tipo	Descrição	Obrigatório	Referência
cAlgo	character	Indica qual o algoritmo que deverá ser utilizado para assinatura do token.	X

Exemplos

    Local ret:= oTokenJWT:verifyToken("RS256")

setToken

Define um token a ser verificado.

Sintaxe

setToken( < cToken > )

Parâmetros

Nome	Tipo	Descrição	Obrigatório	Referência
cToken	character	Indica o token a ser definido para verificação.	X

Exemplos

    oTokenJWT:setToken("eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXUyJ9.eyJhdWQiOiJUZXN0ZSIsImRpciI6WyJob21lIiwidXNlciIsMTAsMTUuNSx0cnVlXSwiZXhwIjoxNTgwNzEzNzY3LCJmbGFnIjoxMC41NTU1NSwiaWF0IjoxNTc5NzEzNzY3LCJpZGFkZSI6MTAsImlzcyI6ImF1dGgwIiwibm9tZSI6IlBhdWxvIFRvdm8iLCJyb290Ijp0cnVlfQ.Yv1FxzdmEGs8quRhn5kuLvS6e2MLMoLg24HP0SqAHWrdIHFoUlf8ulSGnA9QayJidJuprxkZa2JyAztAPr5f2kFFXojoXEbyIv85pXZp3swt7omS0JD92V9cDkGyROfRdn4V6BkzvV3sL2d2hdiBrl-CrOo0HTDAD4exlgB7tXprd-LGZwkq_OSJ2QjoeNvuyHXwSwpVJzz1ZINkb82jkpUvOjXkGW8JqDsBPgMKX_0a5K2cUBlq0m9dKDyyRAMP54JZDttL1aO894l_S200grNB1LGnTpoa6KZEk4W8yxH7cnQVd_8OpRHo_0hJ52o0t62QMOQDeZVsltxs9gfANA")

getLastError

Obtem o registro de erro da última operação executada sem sucesso.

Sintaxe

getLastError()

Exemplos

    conout("Erro na geração de token. Error: "+ oTokenJWT:getLastError())

setAlgorithm

Define o parâmetro "alg" do Header de um token JWT. Este parâmetro define o algoritmo que será usado na assinatura do Token. Normalmente não é preciso definir essa informação pois será preenchida automaticamente na assinatura do token. Os seguintes algoritmos são suportados: HS256, RS256, RS512, PS256, PS384, PS512 e ES256.

Sintaxe

setAlgorithm( < cAlg > )

Parâmetros

Nome	Tipo	Descrição	Obrigatório	Referência
cAlg	character	Indica o algoritmo que será usado na assinatura do Token.	X

Exemplos

    oTokenJWT:setAlgorithm("HS256")

setType

Define o parâmetro (também conhecido por claim) "typ" (Type) do Header de um token JWT. Este parâmetro define o tipo de token JWT. De acordo com a RFC, os tipos conhecidos são: JSON Web Signature (JWS) e JSON Web Encryption (JWE).

Sintaxe

setType( < cType > )

Parâmetros

Nome	Tipo	Descrição	Obrigatório	Referência
cType	character	Indica o tipo de token.	X

Exemplos

    oTokenJWT:setType("JWS")

setContentType

Define o parâmetro (também conhecido por claim) "cty" (Content Type) do Header de um token JWT. Este parâmetro define o tipo de conteúdo de um token JWT. De acordo com a RFC, os tipos conhecidos são: JSON Web Signature (JWS) e JSON Web Encryption (JWE).

Sintaxe

setContentType( < cContentType > )

Parâmetros

Nome	Tipo	Descrição	Obrigatório	Referência
cContentType	character	Indica o tipo de token.	X

Exemplos

    oTokenJWT:setContentType("JWS")

setKeyId

Define o parâmetro (também conhecido por claim) "kid" (Key ID) do Header de um token JWT. Estê parâmetro consiste em uma chave de identificação "string-based" que pode ser utilizada para validação do toke. Esta claim está disponível na especificação JWS e seu uso é opcional.

Sintaxe

setKeyId( < cKeyId > )

Parâmetros

Nome	Tipo	Descrição	Obrigatório	Referência
cKeyId	character	Indica o ID da chave.	X

Exemplos

    oTokenJWT:setKeyId("78b4cf23656dc395364f1b6c02907691f2cdffe1")

setIssuer

Define a claim reservada "iss" (Issuer) do Payload de um token JWT. Consiste na definição da entidade emissora do token. O uso dessa claim é opcional mas recomendado.

Sintaxe

setIssuer( < cIssuer > )

Parâmetros

Nome	Tipo	Descrição	Obrigatório	Referência
cIssuer	character	Indica o emissor do token.	X

Exemplos

    oTokenJWT:setIssuer("http://myapi.com")

setSubject

Define a claim reservada "sub" (Subject) do Payload de um token JWT. Consiste na definição do identificador que representa o assunto do token JWT. O uso dessa claim é opcional.

Sintaxe

setSubject( < cSubject > )

Parâmetros

Nome	Tipo	Descrição	Obrigatório	Referência
cSubject	character	Indica subject do token.	X

Exemplos

    oTokenJWT:setSubject("1234567890")

setAudience

Define a claim reservada "aud" (Audience) do Payload de um token JWT. De acordo com a RFC, identifica os destinatários que o JWT é destinado.

Sintaxe

setAudience( < aAud > )

Parâmetros

Nome	Tipo	Descrição	Obrigatório	Referência
aAud	variant	Indica uma lista de nomes (Array) ou apenas um nome (String). No caso da lista, tipos diferentes de string serão ignorados.	X

Exemplos

    Local aAudience := {"Paulo","Ronaldo","Carlos"}
    oTokenJWT:setAudience(aAudience)

setExpiresAt

Define a claim reservada "exp" (Expiration Time) do Payload de um token JWT. Define o tempo de expiração em segundos.

Sintaxe

setExpiresAt( < nSec > )

Parâmetros

Nome	Tipo	Descrição	Obrigatório	Referência
nSec	numeric	Indica o tempo de expiração em segundos.	X

Exemplos

  // Tempo de expiração configurado para 24horas. ( 24x60x60 )
  oTokenJWT:setExpiresAt(86400)

setNotBefore

Define a claim reservada "nfb" (Not Before) do Payload de um token JWT. Define o tempo antes do qual o JWT não deve ser aceito para processamento.

Sintaxe

setNotBefore( < nSec > )

Parâmetros

Nome	Tipo	Descrição	Obrigatório	Referência
nSec	numeric	Indica o tempo em segundos.	X

Exemplos

  // Configurado para 1horas. ( 1x60x60 )
  oTokenJWT:setNotBefore(3600)

setIssuedAt

Define a claim reservada "iat" (Issue At) do Payload de um token JWT. Define a data e hora em que o toke JWT foi gerado no formato de timestamp em segundos. Por default, no momento de geração do token, internamente este valor é definido automaticamente.

Sintaxe

setIssuedAt( < nSec > )

Parâmetros

Nome	Tipo	Descrição	Obrigatório	Referência
nSec	numeric	Indica o data e hora no formato de um timestamp.	X

Exemplos

  Local cData, cHora, nSecs
  Local oTokenJWT := Nil

  oTokenJWT:=tJWT():New()

  cData := "2020/02/13"
  cHora := "20:10:35"
  nSecs:= oTokenJWT:encodeTime(cData, cHora)
  oTokenJWT:setIssuedAt(nSecs)

setId

Define a claim reservada "jti" (JWT ID) do Payload de um token JWT. Define um identificador único para um token JWT.

Sintaxe

setId( < cID > )

Parâmetros

Nome	Tipo	Descrição	Obrigatório	Referência
cID	character	Indica ID para o token JWT.	X

Exemplos

  oTokenJWT:setId("1580137200")

setPayloadClaim

Define uma ou mais claims publicas ou privadas no Payload de um token JWT.

Sintaxe

setPayloadClaim()

Exemplos

  claims := JsonObject():new()
  claims['idade'] := 10
  claims['root'] := .T.
  claims['flag'] := 10.55555
  claims['nome'] := "Paulo"
  claims['dir'] := { "home", "user", 10, 15.5, .T. }

  // Add Public Claim
  oTokenJWT:setPayloadClaim(claims)

setHeaderClaim

Define uma ou mais claims no Header de um token JWT.

Sintaxe

setHeaderClaim()

Exemplos

  claims := JsonObject():new()
  claims['idade'] := 10
  claims['root'] := .T.
  claims['flag'] := 10.55555
  claims['nome'] := "Paulo"
  claims['dir'] := { "home", "user", 10, 15.5, .T. }

  // Add Header Claim
  oTokenJWT:setHeaderClaim(claims)

setPubKey

Configura chave publica para verificar assinatura de Token.

Sintaxe

setPubKey( < cPubKey > )

Parâmetros

Nome	Tipo	Descrição	Obrigatório	Referência
cPubKey	character	Chave publica .	X

Exemplos

  Local pubKey := PUBKEY()
  oTokenJWT:setPubKey(pubKey)

setPrivKey

Configura chave privada para assinatura de Token.

Sintaxe

setPrivKey( < cPubKey > )

Parâmetros

Nome	Tipo	Descrição	Obrigatório	Referência
cPubKey	character	Chave privada.	X

Exemplos

  Local privKey := PRIVKEY()
  oTokenJWT:setPrivKey(privKey)

setSecretKey

Configura uma senha para assinatura de Token.

Sintaxe

setSecretKey( < cSecretKey > )

Parâmetros

Nome	Tipo	Descrição	Obrigatório	Referência
cSecretKey	character	Senha para assinatura de token.	X

Exemplos

  oTokenJWT:setSecretKey("secret")

hasIssuer

Verifica se o issuer ("iss") está presente no Token.

Sintaxe

hasIssuer()

Exemplos

  Local ret:= .F.
  ret:= oTokenJWT:hasIssuer()

hasSubject

Verifica se o Subject ("sub") está presente no Token.

Sintaxe

hasSubject()

Exemplos

  Local ret:= .F.
  ret:= oTokenJWT:hasSubject()

hasAudience

Verifica se a Claim "aud" (Audience) está presente no Token.

Sintaxe

hasAudience()

Exemplos

  Local ret:= .F.
  ret:= oTokenJWT:hasAudience()

hasExpiresAt

Verifica se a Claim "exp" (Expiration Time) está presente no Token.

Sintaxe

hasExpiresAt()

Exemplos

  Local ret:= .F.
  ret:= oTokenJWT:hasExpiresAt()

hasNotBefore

Verifica se a Claim "nfb" (Not Before) está presente no Token.

Sintaxe

hasNotBefore()

Exemplos

  Local ret:= .F.
  ret:= oTokenJWT:hasNotBefore()

hasIssuedAt

Verifica se a Claim "iat" (Issued At) está presente no Token.

Sintaxe

hasIssuedAt()

Exemplos

  Local ret:= .F.
  ret:= oTokenJWT:hasIssuedAt()

hasId

Verifica se a Claim "jti" (JWT ID) está presente no Token.

Sintaxe

hasId()

Exemplos

  Local ret:= .F.
  ret:= oTokenJWT:hasID()

hasAlgorithm

Verifica se o parâmetro de Header "alg" (Algortihm) está presente no Token.

Sintaxe

hasAlgorithm()

Exemplos

  Local ret:= .F.
  ret:= oTokenJWT:hasAlgorithm()

hasType

Verifica se o parâmetro de Header "typ" (Type) está presente no Token.

Sintaxe

hasType()

Exemplos

  Local ret:= .F.
  ret:= oTokenJWT:hasType()

hasContentType

Verifica se o parâmetro de Header "cty" (Content Type) está presente no Token.

Sintaxe

hasContentType()

Exemplos

  Local ret:= .F.
  ret:= oTokenJWT:hasContentType()

hasKeyId

Verifica se o parâmetro de Header "kid" (Key ID) está presente no Token.

Sintaxe

hasKeyId()

Exemplos

  Local ret:= .F.
  ret:= oTokenJWT:hasKeyId()

hasPayloadClaim

Verifica se uma determinada Claim do Payload está presente no Token.

Sintaxe

hasPayloadClaim( < cClaim > )

Parâmetros

Nome	Tipo	Descrição	Obrigatório	Referência
cClaim	character	Indica a claim a ser verificada.	X

Exemplos

  Local ret:= .F.
  ret:= oTokenJWT:hasPayloadClaim("nome")

hasHeaderClaim

Verifica se um determinado Parâmetro do Header está presente no Token.

Sintaxe

hasHeaderClaim( < cParam > )

Parâmetros

Nome	Tipo	Descrição	Obrigatório	Referência
cParam	character	Indica o parâmetro a ser verificado.	X

Exemplos

  Local ret:= .F.
  ret:= oTokenJWT:hasHeaderClaim("testeid")

withIssuer

Define um issuer que será checado durante a verificação do token JWT.

Sintaxe

withIssuer( < cIssuer > )

Parâmetros

Nome	Tipo	Descrição	Obrigatório	Referência
cIssuer	character	Indica o Issuer a ser checado.	X

Exemplos

  Local ret:= .F.
  oTokenJWT:withIssuer("Auth0")
  ret:= oTokenJWT:verifyToken("rs256")

withSubject

Define um Subject que será checado durante a verificação do token JWT.

Sintaxe

withSubject( < cSubject > )

Parâmetros

Nome	Tipo	Descrição	Obrigatório	Referência
cSubject	character	Indica o Subject a ser checado.	X

Exemplos

  Local ret:= .F.
  oTokenJWT:withSubject("1234567890")
  ret:= oTokenJWT:verifyToken("rs256")

withAudience

Define uma lista ou apenas uma Audience que será checada durante a validação de um token. Caso seja definida uma lista, somente será valido se todos os elementos estiverem contido no token.

Sintaxe

withAudience( < cAudience > )

Parâmetros

Nome	Tipo	Descrição	Obrigatório	Referência
cAudience	variant	Indica uma lista de Audience (Array) ou apenas um Audience (String). No caso da lista, tipos diferentes de string serão ignorados.	X

Exemplos

  Local ret:= .F.
  oTokenJWT:withAudience("testex")
  ret:= oTokenJWT:verifyToken("RS256")

  aAudience := {"Paulo","Ronaldo","Carlos","Zequinha"}
  oTokenJWT:withAudience(aAudience)
  ret:= oTokenJWT:verifyToken("RS256")

withId

Define um JWT ID (jti) que será checada durante a verificação do token JWT.

Sintaxe

withId( < cID > )

Parâmetros

Nome	Tipo	Descrição	Obrigatório	Referência
cID	character	Indica ID para ser checado	X

Exemplos

  Local ret:= .F.
  oTokenJWT:withId("1580137200")
  ret:= oTokenJWT:verifyToken("rs256")

withClaim

Define um conjunto ou apenas uma claim para ser checada durante a validação de um token.

Sintaxe

withClaim()

Exemplos

  Local ret:= .F.
  claims := JsonObject():new()
  claims['idade'] := 10
  claims['root'] := .T.
  claims['flag'] := 10.66666
  claims['nome'] := "Cristiano Ronaldo"
  claims['dir'] := { "home", "user", 10, 15.5, .T. }
  oTokenJWT:withClaim(claims)
  ret:= oTokenJWT:verifyToken("rs256")

encodeTime

Transforma uma informação de tempo em um valor em segundos considerando o epoch, que é o número de segundos decorridos desde 1º de janeiro de 1970 (meia-noite UTC / GMT). Essa informação de tempo pode ser um conjunto Data e Hora ou apenas um valor em segundos.

Sintaxe

encodeTime( < cData >, [ cHora ] )

Parâmetros

Nome	Tipo	Descrição	Obrigatório	Referência
cData	variant	Pode ser do tipo Caracter indicando a Data que deve estar no formato yyyy/mm/dd, ou uma informação do tipo numérica informando um valor em segundos. Caso o valor seja segundos, não será necessário informar o segundo parâmetro. Ex: 2020/02/25 ou 300 segundos (5 minutos - 5 * 60).	X
cHora	character	Indica a Hora que deve estar no formato hh:mm:ss. O valor default é 00:00:00. Ex: 20:05:45

Exemplos

  Local cData, cHora, timeEncode
  Local oTokenJWT:= Nil

  cData := "2020/02/13"
  cHora := Time()
  conout("Data: " + cData + "Hora: " + cHora)

  timeEncode:= oTokenJWT:encodeTime(cData, cHora)
  // Checagem para verificar se foi transformado com sucesso.
  if(timeEncode == 0)
    Conout("Error: " + oTokenJWT:getLastError())
  end if
  Conout("timeEncode= "+ cValToChar(timeEncode))

decodeTime

Decodifica um valor em segundos para Data e Hora no formato "human-readable" "yyyy/mm/dd hh:mm:ss" ou seja, legível e de facil entendimento. A decodificação leva em consideração o epoch, que é o número de segundos decorridos desde 1º de janeiro de 1970 (meia-noite UTC / GMT). Veja maiores informações sobre epoch em https://www.epochconverter.com.

Sintaxe

decodeTime( < nSec > )

Parâmetros

Nome	Tipo	Descrição	Obrigatório	Referência
nSec	numeric	Indica o valor em segundos	X

Exemplos

  Local nSecs, timeDecode
  Local oTokenJWT:= Nil

  // Instancia da classe
  oTokenJWT:=tJWT():New()

  // "2020/02/13 20:10:35"
  nSecs := 1581635435
  timeDecode := oTokenJWT:decodeTime(nSecs)
  if (Len(timeDecode) == 0)
    Conout("Error: " + oTokenJWT:getLastError())
  end if
  conout("timeDecode= "+timeDecode)

clearWithClaim

Limpa a lista de "WithClaim" utilizadas durante a validação e verificação de conteúdo de um token.

Sintaxe

clearWithClaim()

Exemplos

  claimsCheck := JsonObject():new()
  claimsCheck['idade'] := 10
  claimsCheck['root'] := .T.
  claimsCheck['flag'] := 10.66666
  claimsCheck['nome'] := "Cristiano Ronaldo"
  claimsCheck['dir'] := { "home", "user", 10, 15.5, .F. }  // valor alterado
  oTokenJWT:withClaim(claimsCheck)

  ret:= oTokenJWT:verifyToken("rs256")
  if (!ret)
    Conout("token verification error")
  end if

  // primeiro faço uma limpeza das claims configuradas anteriormente.
  oTokenJWT:clearWithClaim()

  claimsCheck:FromJson("")   // limpa o objeto
  claimsCheck['idade'] := 10
  oTokenJWT:withClaim(claimsCheck)

  ret:= oTokenJWT:verifyToken("rs256")
  if (!ret)
    Conout("token verification error")
  end if

Propriedades

A classe expõe as seguintes propriedades:

token

Armazena o último token criado.

Tipo	Valor Padrão	Somente Leitura
character	""	N

Árvore de páginas

Classe tJWT

Classe tJWT

Hierarquia

Observações

Exemplos

Abrangência

Construtores

New

Sintaxe

Retorno

Exemplos

Métodos

createToken

Sintaxe

Parâmetros

Exemplos

verifyToken

Sintaxe

Parâmetros

Exemplos

setToken

Sintaxe

Parâmetros

Exemplos

getLastError

Sintaxe

Exemplos

setAlgorithm

Sintaxe

Parâmetros

Exemplos

setType

Sintaxe

Parâmetros

Exemplos

setContentType

Sintaxe

Parâmetros

Exemplos

setKeyId

Sintaxe

Parâmetros

Exemplos

setIssuer

Sintaxe

Parâmetros

Exemplos

setSubject

Sintaxe

Parâmetros

Exemplos

setAudience

Sintaxe

Parâmetros

Exemplos

setExpiresAt

Sintaxe

Parâmetros

Exemplos

setNotBefore

Sintaxe

Parâmetros

Exemplos

setIssuedAt

Sintaxe

Parâmetros

Exemplos

setId

Sintaxe

Parâmetros

Exemplos

setPayloadClaim

Sintaxe

Exemplos

setHeaderClaim

Sintaxe

Exemplos

setPubKey

Sintaxe