User Guide

Search…
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.
1
$ wattson --help
2
usage: wattson [<flags>] <command> [<args> ...]
3
​
4
The WaTTS client.
5
​
6
​
7
​
8
Please store your issuer id (up to version 1 the issuer url) in the 'WATTSON_ISSUER' environment variable:
9
​
10
  export WATTSON_ISSUER=<the issuer id>
11
​
12
The url of WaTTS can be stored in the environment variable 'WATTSON_URL':
13
​
14
  export WATTSON_URL=<url of watts>
15
​
16
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
17
'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
18
loaded, else it will fail:
19
​
20
  export OIDC_SOCK=<path to the oidc-agent socket> (usually this is already exported)
21
  export WATTSON_AGENT_ACCOUNT=<account of oidc-agent to use>
22
​
23
​
24
If you want to pass the access token directly please use the WATTSON_TOKEN variable:
25
​
26
  export WATTSON_TOKEN=<access token>
27
​
28
​
29
Flags:
30
      --help       Show context-sensitive help (also try --help-long and --help-man).
31
      --version    Show application version.
32
  -u, --url=URL    the base url of watts' rest interface
33
  -p, --protver=2  protocol version to use (can be 0, 1 or 2)
34
  -j, --json       enable json output
35
      --debug      enable debug output
36
​
37
Commands:
38
  help [<command>...]
39
    Show help.
40
​
41
  info
42
    get the information about watts, e.g. its version
43
​
44
  lsprov
45
    list all OpenID Connect provider
46
​
47
  lsserv
48
    list all service
49
​
50
  lscred
51
    list all credentials
52
​
53
  request <serviceId> [<parameter>]
54
    request a credential for a service
55
​
56
  revoke <credId>
57
    revoke a credential
Copied!
If you have questions or found a bug please always include the version on your description:
1
wattson --version
Copied!
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:
1
export WATTSON_URL=https://tts-dev.data.kit.edu
Copied!
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:
1
export WATTSON_ISSUER=<the issuer id>
2
export WATTSON_TOKEN=<the access token>
Copied!
or, if using the oidc-agent, important, not setting the 'WATTSON_TOKEN':
1
export WATTSON_ISSUER=<the issuer id>
2
export WATTSON_AGENT_ACCOUNT=<the oidc-agent account>
3
export OIDC_SOCK=<the oidc-agent socket>
Copied!
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)
1
$ wattson info
2
connecting to https://tts-dev.data.kit.edu/api/v2/ using protocol version 2
3
retrieving information:
4
WATTS version: 1.0.0
5
  the redirect path is: /oidc
6
this connection is *NOT* logged in
Copied!
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:
1
$ wattson lsprov
2
connecting to https://tts-dev.data.kit.edu/api/v2/ using protocol version 2
3
retrieving provider list:
4
Provider [iam][ready] INDIGO Datacloud Identity and Access Management (IAM) (https://iam-test.indigo-datacloud.eu/)
5
Provider [hbp][ready] Human Brain Project (HBP) (https://services.humanbrainproject.eu/oidc/)
6
Provider [eudat][ready] EUDAT (b2access) (https://b2access.eudat.eu:8443/oauth2)
7
Provider [egi][ready] European Grid Infrastracture (Development) (https://aai-dev.egi.eu/oidc/)
8
Provider [google][ready] Google, the well known search giant (https://accounts.google.com)
Copied!
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.
1
$ wattson lsserv
2
connecting to https://tts-dev.data.kit.edu/api/v2/ using protocol version 2
3
retrieving service list:
4
​
5
Service [x509][enabled/authorized] [ ] A simple, non trusted demo CA
6
 - credenitals: 0/3
7
 - parameter sets:
8
    Empty Parameter Set (allows basic request)
9
​
10
​
11
Service [aarc_ssh][enabled/NOT AUTHORIZED] [ ] Ssh Key Deployment on multiple VMs
12
   Your authorisation is insufficient for this service. This may be due to missing group membership or due to a too low Level of Assurance (LoA) (Yes, we already support that kind of stuff ;D)
13
 - credenitals: 0/1
14
 - parameter sets:
15
    Parameter Set:
16
      MANDATORY Parameter 'public key' [pub_key]: the public key to upload to the service (textarea)
17
​
18
    Empty Parameter Set (allows basic request)
19
​
20
​
21
Service [indigo_ssh][enabled/authorized] [ ] Example Ssh Key Deployment
22
 - credenitals: 0/1
23
 - parameter sets:
24
    Parameter Set:
25
      MANDATORY Parameter 'public key' [pub_key]: the public key to upload to the service (textarea)
26
​
27
    Empty Parameter Set (allows basic request)
28
​
29
​
30
Service [HBP_S3][enabled/NOT AUTHORIZED] [ AT! ] Self Service for your HBP-S3 storage keys
31
   The S3 key creation is only active when you are a member of the HBP group 'hbp-kit-cloud'
32
 - credenitals: 0/1
33
 - parameter sets:
34
    Empty Parameter Set (allows basic request)
35
​
36
​
37
Service [info][enabled/authorized] [ ] Simple Info Service
38
 - credenitals: 0/1
39
 - parameter sets:
40
    Empty Parameter Set (allows basic request)
Copied!
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.
1
$ wattson lscred
2
connecting to https://tts-dev.data.kit.edu/api/v2/ using protocol version 2
3
retrieving credential list:
4
​
5
Credential [9dfa0900-930b-462c-8144-da9dd1aa37d2]: for service with id [info] created Wed, 21 Dec 2016 10:48:51 GMT at 'Web App'
Copied!
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:
1
$ wattson request x509
2
connecting to https://tts-dev.data.kit.edu/api/v2/ using protocol version 2
3
requesting credential for service [x509]:
4
Credential [29e28d92-a13f-4f3a-b23b-54c921a4cd82]:
5
[ Certificate (textfile)] => Certificate:
6
    Data:
7
        Version: 3 (0x2)
8
        Serial Number: 11 (0xb)
9
    Signature Algorithm: sha1WithRSAEncryption
10
        Issuer: C=EU, O=INDIGO, OU=TTS, CN=TTS-CA
11
        Validity
12
            Not Before: Dec 21 10:54:18 2016 GMT
13
            Not After : Jan  1 10:54:18 2017 GMT
14
        Subject: C=EU, O=INDIGO, OU=TTS, [email protected]
15
        Subject Public Key Info:
16
            Public Key Algorithm: rsaEncryption
17
                Public-Key: (1024 bit)
18
                Modulus:
19
                    c8:96:6d:23:2a:10:bd:de:25
20
                Exponent: 65537 (0x10001)
21
        X509v3 extensions:
22
            X509v3 Subject Key Identifier:
23
                C2:DD:2F:99:80:7A:6C:54:66:EF:89:DE:02:0A:3A:14:AB:81:66:7B
24
            X509v3 Authority Key Identifier:
25
                keyid:E3:64:2D:4D:2B:8A:81:4E:58:0A:71:FE:D7:62:9D:A7:3F:69:C5:5E
26
​
27
            X509v3 Basic Constraints:
28
                CA:FALSE
29
            X509v3 Key Usage:
30
                Digital Signature, Key Encipherment
31
            X509v3 Subject Alternative Name:
32
                URI:https://accounts.google.com/109538112780676045413
33
    Signature Algorithm: sha1WithRSAEncryption
34
         ac:fd:04:36:81:4f:d8:99:8c:42:ee:92:23:0c:a5:1b:a0:6b:
35
         aa:48:00:a8
36
-----BEGIN CERTIFICATE-----
37
MIIDITCCAgmgAwIBAgIBCzANBgkqhkiG9w0BAQUFADA9MQswCQYDVQQGEwJFVTEP
38
KROGLtV7daqUGLf8p+BPmnipmUPiuzszzNhIcBfTsN24qkgAqA==
39
-----END CERTIFICATE-----
40
​
41
[ Private Key (textfile)] => -----BEGIN ENCRYPTED PRIVATE KEY-----
42
MIICxjBABgkqhkiG9w0BBQ0wMzAbBgkqhkiG9w0BBQwwDgQIxFS4nQh/WxQCAggA
43
sRc6PzBg3g1S0yNedNEQsOUU3krgJchRKmhSvLMeVRlTZSk/xuvb+mTr
44
-----END ENCRYPTED PRIVATE KEY-----
45
​
46
[ Passphrase (for Private Key) (text)] => 1234
47
[ CA Certificate (textfile)] => -----BEGIN CERTIFICATE-----
48
MIIDRTCCAi2gAwIBAgIBADANBgkqhkiG9w0BAQsFADA9MQswCQYDVQQGEwJFVTEP
49
9D9hyq7aDBPvLiVQ/DcgQ1c+Nf1G12HZpg==
50
-----END CERTIFICATE-----
Copied!
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:
1
Service [indigo_ssh][enabled/authorized] Example Ssh Key Deployment
2
 - credenitals: 0/1
3
 - parameter sets:
4
    Parameter Set:
5
      MANDATORY Parameter 'public key' [pub_key]: the public key to upload to the service (textarea)
6
​
7
    Empty Parameter Set (allows basic request)`
Copied!
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:
1
{ "pub_key":"ssh-rsa AAAAAAAAAABBBBBBBBBBBBBBBCCCCCCCCCCCCCCCCCCC [email protected]"}
Copied!
the request in total would be:
1
wattson request indigo_ssh '{ "pub_key":"ssh-rsa AAAAAAAAAABBBBBBBBBBBBBBBCCCCCCCCCCCCCCCCCCC [email protected]"}'
Copied!
(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.
1
$ wattson revoke 29e28d92-a13f-4f3a-b23b-54c921a4cd82
2
revoking credential [29e28d92-a13f-4f3a-b23b-54c921a4cd82]:
3
credential sucessfully revoked
Copied!
Checking the list of credentials using the lscred command shows that only one credential is left, yet not the one just requested:
1
$ wattson lscred
2
connecting to https://tts-dev.data.kit.edu/api/v2/ using protocol version 2
3
retrieving credential list:
4
​
5
Credential [9dfa0900-930b-462c-8144-da9dd1aa37d2]: for service with id [info] created Wed, 21 Dec 2016 10:48:51 GMT at 'Web App'
Copied!
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:
1
export WATTSON_INSECURE=true
Copied!
Introduction
Deployment And Administration Guide
Last modified 3yr ago
Copy link
Contents
Client setup
Flags
Commands
Get Information about the Token Translation Service (info)
List all OpenId Provider (lsprov)
List all service for a user (lsserv) AUTH
Listing all credentials (lscred) AUTH
Requesting a credential (request) AUTH
Revoking a credential (revoke) AUTH
Plugin Developer self signed certificate support