User Guide

Using wattson is made as easy as possible. In case you are lost wattson provides a lot of information with its 'help' command, just call wattson --help.

$ wattson --help
usage: wattson [<flags>] <command> [<args> ...]

The WaTTS client.



Please store your issuer id (up to version 1 the issuer url) in the 'WATTSON_ISSUER' environment variable:

  export WATTSON_ISSUER=<the issuer id>

The url of WaTTS can be stored in the environment variable 'WATTSON_URL':

  export WATTSON_URL=<url of watts>

It is possible to either pass the access token directly to wattson or use oidc-agent to retrieve access tokens. To use oidc-agent the environment variable
'OIDC_SOCK' needs to point to the socket of the agent and 'WATTSON_AGENT_ACCOUNT' needs to contain the oidc-agent account name to use, the account needs to be
loaded, else it will fail:

  export OIDC_SOCK=<path to the oidc-agent socket> (usually this is already exported)
  export WATTSON_AGENT_ACCOUNT=<account of oidc-agent to use>


If you want to pass the access token directly please use the WATTSON_TOKEN variable:

  export WATTSON_TOKEN=<access token>


Flags:
      --help       Show context-sensitive help (also try --help-long and --help-man).
      --version    Show application version.
  -u, --url=URL    the base url of watts' rest interface
  -p, --protver=2  protocol version to use (can be 0, 1 or 2)
  -j, --json       enable json output
      --debug      enable debug output

Commands:
  help [<command>...]
    Show help.

  info
    get the information about watts, e.g. its version

  lsprov
    list all OpenID Connect provider

  lsserv
    list all service

  lscred
    list all credentials

  request <serviceId> [<parameter>]
    request a credential for a service

  revoke <credId>
    revoke a credential

If you have questions or found a bug please always include the version on your description:

Client setup

The client is configured by environment variables:

  • WATTSON_URL: the base url of the Token Translation service, e.g. https://tts-dev.data.kit.edu

  • WATTSON_ISSUER: the issuer id of the OpenId Connect provider in use (see lsprov). For protocol version 1 this is the issuer url.

  • WATTSON_TOKEN: the access token received from the OpenId Connect provider, e.g. using the web interface of WaTTS

  • OIDC_SOCK: pointing to the path of the unix socket of the oidc-agent

  • WATTSON_AGENT_ACCOUNT: the account used with the oidc-agent, this account must be loaded.

All commands need at least the WATTSON_URL to be set:

change the url to fit your needs, alternativly the --url flag can be used.

Issuer and Token are set the same way, commands that need those to be set are marked with AUTH: Either:

or, if using the oidc-agent, important, not setting the 'WATTSON_TOKEN':

If 'WATTSON_TOKEN' is set it overrides the oidc-agent settings.

Flags

Flags can be used with any command and change the behaviour of the client:

  • --json encode the received information using json

  • --protver=X set the protocol version to X, supported are 0, 1 and 2 (default: 2)

    • 0 is used for WATTS up to version 0.4.x

    • 1 is used for WATTS 1.0.x to get the same results as with 0.4.x

    • 2 is the newest api version for WATTS 1.0.x

  • --debug enabled debug output

  • --url set the base url of the TTS, usually done by setting the environment variable WATTSON_URL

Commands

Each Description will include a sample call and its output.

Get Information about the Token Translation Service (info)

The WATTS is running version 1.0.0 and we are not in an active session, this is always the case when using the REST interface.

List all OpenId Provider (lsprov)

The lsprov command lists all the OpenId Providers a WATTS instance supports. The call needs no additional parameter:

In the example above, the WATTS will be asked to list all the OpenId Connect Providers it supports. For this example, the WATTS supports four OpenId Connect providers. Each line contains multiple information:

  • the id of the provider e.g. 'iam'

  • the status, in this example 'ready'

  • a descriptive name, e.g. 'INDIGO Datacloud Identity and Access Management (IAM)'

  • the issuer url of the provider, here 'https://iam-test.indigo-datacloud.eu/'

List all service for a user (lsserv) AUTH

The lsserv command lists all the services the WATTS supports for the authorized user.

The result is a list of the services for which the user might be allowed to request credentials. Each block represents one service. Listing:

  • The Id, e.g. x509

  • The status and authorization status, e.g. enabled/authorized

  • Flags/Icons

    • AT!: this service receives your access-token, only use it if you really trust/need it

  • A description of the service

  • The number of credentials requested and the max. allowed, e.g. 0/3

  • The parameter sets, these are used for advanced requests, desribed later

    • Only if the "Empty Parameter Set (allows basic request)" is present a basic request is possible

To request a credential, one needs the id, in the first square brackets and one parameter set, which can be empty.

Listing all credentials (lscred) AUTH

The lscred command lists all currently requested credentials.

The output is one line per credential.

  • the id is the internal identifier of the credential within TTS.

  • the id of the service it has been requested for.

  • the creation time

  • at which interface the credential was created, it is either the Web App or the REST interface

Requesting a credential (request) AUTH

Basic Request (without parameter sets)

A basic request is possible if the service has the 'Empty Parameter Set (allows basic request)' in the listing (see lsserv). The only parameter a basic request needs is the id of the service to request the credential for:

The output (shortened) contains the credential Id and a list of credential entries, each representing a part of the credential. An entry consists of:

  • a name

  • its type

  • and the value

So each entry is of the following format: [ <name> (<type>) ] => <value>

Advanced requests

Advanced request only have one additional parameter, the parameter object. The parameter object is a string containing a json encoded object.

The parameter object MUST contain all mandatory fields of one parameter set. As an example take thes parameter sets from this service:

It contains two sets, one empty set and one non empty set. The advanced request is only needed for non empty sets. Each non-emtpy set contains of a list of parameter with the following information:

  • Mandatory or not

  • Parameter name

  • Parameter key

  • Parameter description

    The parameter object MUST contain at least every mandatory parameter of a chosen set. The parameter object is then created using the 'parameter key' as key and the wanted value as value.

    For example:

    the request in total would be:

    (note the single quotes and double quotes, using them as above makes your life easier)

Revoking a credential (revoke) AUTH

Revoking is very similar to requesting, yet instead of providing the service for which to request a credential, the credential id is provided.

Checking the list of credentials using the lscred command shows that only one credential is left, yet not the one just requested:

Plugin Developer self signed certificate support

WARNING Never do this with operational systems! If wattson does complain that the certificate of the server can not be verified this has two possible reasons:

  • The server is misconfigured: contact the administrator

  • There is a man in the middle attack

The verification of certificates can be disabled with the following line:

PreviousIntroductionNextDeployment And Administration Guide

Last updated