# TokenInfo

Since version 3.0.4 we have the TokenInfo object in the xssec library.
This is a wrapper around all the information the token contains.

## Security Note

Do not simply rely on the information within the token!
The webapplication normally receives the token with the HTTP Request from "outside" the application.
So there is a deep parameter validation needed! 

*Also if the token is signed, it may also contain dangerous information.*

### How to get the TokenInfo object
There are several ways to get the TokenInfo.
If an error occurs NO security context is created. But the [TokenInfo](TokenInfo.md) object is available, so you can do some logging.

#### If you create the SecurityContext on your own
```js
xssec.createSecurityContext(access_token, config, function(error, securityContext, tokenInfo) {
    if (error) {
        console.log('tokenInfo is also available if you have an error', tokenInfo.getPayload())
        return;
    }
    console.log('Security Context created successfully', tokenInfo.getPayload());
    console.log('You can also retrieve it from the SecurityContext', securityContext.getTokenInfo());
});
```

#### If you use the passport library. 
The ``tokenInfo`` object is attached to the ``request`` object in the JWTStrategy middleware. ([more here](../README.md#api-description))
Only if the middleware could not find a bearer token in the HTTP header, there is no ``tokenInfo`` object created.

The documentation for a default error handler in express you find [here](https://expressjs.com/en/guide/error-handling.html)

```js
passport.use(new JWTStrategy(config));

app.use(passport.initialize());

//don't forget to set failWithError to true.
//Otherwise the errorHandler will not be called
app.use(passport.authenticate('JWT', { session: false, failWithError: true })); 

// simple express Error Handler
app.use(function(err, req, res, next) {
  //be aware that the error handler is not only for the passport errors!
  var tokenInfo = req.tokenInfo;
  if(tokenInfo) {
    //err is exception thrown but not the error of the tokenValidation
    //to get the errorObject from xsuaa
    var xserror = tokenInfo.getErrorObject()  
    
    //to the logging
    console.error(xserr, tokenInfo.getPayload());
  }
  
  res.status(err.status);
  res.send(err.message);
});
```

## API Description

### TokenInfo(encoded_token)

Code says more than words :-)

```js
var tokenInfo = new TokenInfo(encodedTokenAsString);

///// Get the Token-information as a whole
var payload = tokenInfo.getPayload(); //Get the token payload
var header = tokenInfo.getHeader();   //Get the token header
var encoded = tokenInfo.getTokenValue(); //returns the encoded token string

var exp = tokenInfo.getExpirationDate(); //returns a Date object or null if not available
var iat = tokenInfo.getIssuedAt(); //returns a Date object or null if not available
var iss = tokenInfo.getIssuer(); //returns a string or null if not available

var is_xsuaa = tokenInfo.isTokenIssuedByXSUAA(); //returns true, if the token is a XSUAA token

///// Error Handling
tokenInfo.isDecoded(); //returns true, if a token could be decoded
tokenInfo.isValid();    //returns true, if no error object is attached

tokenInfo.getErrorObject(); //return the error object if there is one


///// Verification of an encoded token

//you can pass a key Callback to retrieve the key asyncronously
function getKeyCB(header, callback) {
  client.getSigningKey(header.kid, function(err, key) {
    var signingKey = key.publicKey || key.rsaPublicKey;
    callback(null, signingKey);
  });
}

tokenInfo.verify(getKeyCB, function(err, tokenInfo) {
    if(err) {
        console.error(err.errorCode, err.message);
        console.error(err.stack);

        //tokenInfo is also available, if there was a verification error.
        console.log(tokenInfo.getPayload());
    } else {
        //yeah, it was verified
        ...
    }
});

//instead of a callback you can directly give the verification key to the function
tokenInfo.verify("123456", function(err, tokenInfo) {
    ...
});

```

### Future Plans
We have plans to provide some more functionality here in the future:

* provide not only verify, but also sign functionality
* easy create tokens for unittesting