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

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

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

Exemplos

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

setToken

Define um token a ser verificado.

Sintaxe

setToken( < cToken > )

Parâmetros

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

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

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

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

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

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

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

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

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

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

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

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

Exemplos

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

setPrivKey

Configura chave privada para assinatura de Token.

Sintaxe

setPrivKey( < cPubKey > )

Parâmetros

Exemplos

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

setSecretKey

Configura uma senha para assinatura de Token.

Sintaxe

setSecretKey( < cSecretKey > )

Parâmetros

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

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

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

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

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

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

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

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

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.