Versions Compared

Old Version 5

changes.mady.by.user Kristina B.

Saved on

compared with

New Version Current

changes.mady.by.user Jonė Š.

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

id1206891765

...

id1206891786

...

id1206891764

On this page

...

Table of Contents

...

id1206891775

Authentication server implements the OpenID Connect standard with several customizations. To access the OpenID Connect configuration, go to https://<auth_server_host>:<port>/authentication/.well-known/openid-configuration.

 

The Authentication server must be configured to accept new client applications by changing these parameters in authserver.properties file:

  1. Add URL of the client app to the whitelist, separate URLs with comma: authentication.redirect.uri.whitelist. This can be either full URL where users should be redirected back from the Authentication server, or just the beginning of it. Authorization endpoint will not accept redirect uri parameters that cannot be found in the whitelist.
  2. Add new client IDs, separated with comma: authentication.client.ids. You might need to uncomment this line first. Authorization endpoint will not accept client_id parameter that cannot be found in this list.

There are a few deviations from standard OpenID Connect specification:

  • When invoking token endpoint, HTTP header X-Auth-Secret with secret must be passed with value from authserver.properties, parameter authentication.client.secret.
  • ID tokens have expiration time (configuration property authentication.token.expirity), they must be refreshed through the token endpoint by passing refresh tokens.

To call TWC REST API with generated authentication token, the token should be send in the header of the request:

                Authorization: Token <received_id_token>

Authentication with user interaction

The basic Authorization flow should be as follows:

1. Redirect the user to the AuthServer with HTTP GET parameters:

    scope=openid

    redirect_uri=<your_app_url>

    client_id=<your_client_id>

    response_type=code

2. After user signs in, receive HTTP GET request with code parameter.

3. Send HTTP POST request to the token endpoint of the Authentication server with HTTP header X-Auth-Secret and parameters:

    scope=openid

    redirect_uri=<your_app_url>

    client_id=<your_client_id>

    grant_type=code

The code means <code_received_after_user_signs_in>

4. Receive back the JSON response with ID Token that can be used to authorize with TWC and refresh token that later should be used to refresh ID Token.

5. Refresh the ID Token by sending HTTP POST request to the token endpoint of the AuthServer with HTTP header X-Auth-Secret and parameters:

    scope=openid

    redirect_uri=<your_app_url>

    client_id=<your_client_id>

    grant_type=refresh_token   

    refresh_token=<refresh_token_value>

Authentication without user interaction

To get a token without user interaction, i.e. use some predefined username and password and make only server-server calls, system needs to send HTTP POST request to the token endpoint of the Authentication server with HTTP headers X-Auth-Secret and parameters:

  • Headers:

X-Auth-Secret: <secret from authentication.client.secret >

Authorization: Basic xxxxxxxxx, where xxxxxx is base64 encoded username:password

  • Query parameters:

grant_type=client_credentials

client_id=<your_client_id>


Teamwork Cloud REST API has an endpoint, which implements token-based authentication described in the Token-based authentication page.

Setting up token-based authentication

To set up Teamwork Cloud and Authentication server for token-based authentication using REST API endpoint

  1. Set up Authentication server to work with your SAML/SSO, if needed.
  2. Open <install_root>/AuthServer/config/authserver.properties

  3. Find key authentication.client.ids and add ,twc-rest-api at the end of the value. Save and close the file.

    Note

    The comma before twc-rest-api is a separator.


  4. Open <install_root>/TeamworkCloud/configuration/application.conf.
  5. Find the esi.auth block and set the server value to your authentication server IP. Save and close the file.
  6. Restart the Authentication server and Teamwork Cloud server.

Using token-based authentication

To use token-based authentication

  1. Open REST API at the following URL:https://<ip>:8111/osmc/authen/login on a browser.
  2. You should be redirected to the Authentication server login page.
  3. Enter your credentials. The browser shows you a token, usually starting with eyJ….

    Image Added

  4. Copy the token and use it to log on to REST API.

    Note

    The token is used in an Authorization header with the Token Type.


For example (using a token with cURL):

Code Block
languagetext
curl -v -k -H "Authorization: Token
eyJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJBZG1pbmlzdHJhdG9yIiwiYXVkIjoidHdjLXJlc3QtYXBp
IiwiaXNzIjoiaHR0cHM6XC9cLzEyNy4wLjAuMTo4NTU1XC9hdXRoZW50aWNhdGlvbiIsImV4cCI6M
TYwNjI5OTc3NywiaWF0IjoxNjA2Mjk4ODc3fQ.bA-
S5hHeSlV8AFoQVzzfIseC3qlmqQoBQREiapHN6I5CcvwetKdSVztWKkssSGjm31Y1zqoULio7_1Ma
mtGBbbzvA1WWQYFRiYk0D612yNDv4uNHBbNLNEv61TYNLwdPwPh0atVRehkh-
LSgjipXTvXj4mZViE0NHKIG9U7htA9Zzvxvck2JDXe_eU2-
4TCNm8II89ROaEb1tZ5nD84ieRbzJWqrcVTdqU2YfbIUeew5Nir8obkLYgixBXFKWsTHi3jNuoBx3
KcAIyZqL6cjtsCER4wbk4PEEDC57UVsOcsXWr6yvXIoVdJMOiDHo_fJMkgOjDqSyIL-2B21O-Y-GA"
https://127.0.0.1:8111/osmc/login

The result is as follows:

Code Block
languagetext
> GET /osmc/login HTTP/1.1
> Host: 127.0.0.1:8111
> User-Agent: curl/7.55.1
> Accept: */*
> Authorization: Token
eyJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJBZG1pbmlzdHJhdG9yIiwiYXVkIjoidHdjLXJlc3QtYXBp
IiwiaXNzIjoiaHR0cHM6XC9cLzEyNy4wLjAuMTo4NTU1XC9hdXRoZW50aWNhdGlvbiIsImV4cCI6M
TYwNjI5OTc3NywiaWF0IjoxNjA2Mjk4ODc3fQ.bA-
S5hHeSlV8AFoQVzzfIseC3qlmqQoBQREiapHN6I5CcvwetKdSVztWKkssSGjm31Y1zqoULio7_1Ma
mtGBbbzvA1WWQYFRiYk0D612yNDv4uNHBbNLNEv61TYNLwdPwPh0atVRehkh-
LSgjipXTvXj4mZViE0NHKIG9U7htA9Zzvxvck2JDXe_eU2-
4TCNm8II89ROaEb1tZ5nD84ieRbzJWqrcVTdqU2YfbIUeew5Nir8obkLYgixBXFKWsTHi3jNuoBx3
KcAIyZqL6cjtsCER4wbk4PEEDC57UVsOcsXWr6yvXIoVdJMOiDHo_fJMkgOjDqSyIL-2B21O-Y-GA
>
< HTTP/1.1 204 No Content
< Content-Length: 0
< Content-Type: application/octet-stream
< Date: Wed, 25 Nov 2020 10:08:44 GMT
< Accept-Ranges: bytes
< Server: Restlet-Framework/2.2.3
< Vary: Accept-Charset, Accept-Encoding, Accept-Language, Accept
< Set-Cookie: twc-rest-current-user=Administrator; Path=/osmc; Expires=Wed, 25 Nov 2020 10:23:44 GMT
< Set-Cookie: twc-rest-session-id=f40ef933-5461-4058-a1e7-9b8d4021aa8a; Path=/osmc; Expires=Wed, 25 Nov 2020 10:23:44 GMT
<
* Connection #0 to host 127.0.0.1 left intact


Limitations

This REST API endpoint only displays the ID token. Usually, ID token is not very long-living. You can configure the ID token expiration in authserver.properties file (using property authentication.token.expirity).

Usually the ID token needs to be refreshed as described in the page Token-based authentication. However, this REST API does not display a refresh token, which is needed to refresh the ID token.

As a workaround, long-living ID tokens can be generated by adding ,twc-rest-api to the authserver.properties file property authentication.client.unlimited. In such case, ID token expiration will be calculated using property authentication.unlimited.token.expirity.

Note

Use this feature with caution and make sure that such long-living ID token is adequately protected

...

.