On this page

Other web applications can integrate with Authentication server through OpenID Connect (further referred to as OIDC) protocol to authenticate users and access Teamwork Cloud REST API on behalf of these users.

Authentication server behaves as the OIDC Identity Provider. Web applications that need to access Teamwork Cloud REST API on behalf of an authenticated user should implement OIDC Service Provider functionality according to OIDC protocol specification.

OpenID Connect integration

See OpenID Connect specification for more details.

Authentication server provides a JSON with all endpoints required for the integration. This JSON can be retrieved using https://<server_host>:8443/authentication/.well-known/oidc-configuration endpoint. This JSON also returns supported response types and grant types.

Example JSON:

{
  "response_types_supported": [
    "code token",
    "code id_token",
    "code",
    "id_token",
    "id_token token",
    "code id_token token"
  ],
  "device_authorization_endpoint": "https://localhost:8443/authentication/api/oidc/device_code",
  "jwks_uri": "https://localhost:8443/authentication/jwks.json",
  "grant_types_supported": [
    "urn:ietf:params:oauth:grant-type:device_code",
    "refresh_token",
    "password",
    "authorization_code"
  ],
  "subject_types_supported": [
    "public"
  ],
  "id_token_signing_alg_values_supported": [
    "RS256"
  ],
  "registration_endpoint": "https://localhost:8443/authentication/api/oidc/register",
  "token_endpoint_auth_methods_supported": [
    "client_secret_basic"
  ],
  "scopes_supported": [
    "openid"
  ],
  "issuer": "https://localhost:8443/authentication",
  "authorization_endpoint": "https://localhost:8443/authentication/oidc/authorize",
  "token_endpoint": "https://localhost:8443/authentication/api/oidc/token"
}

Authentication server supports the following authorization flows:

Authorization code flow
Implicit flow
Hybrid flow
Device code flow (extension, see Device Code Flow - Authorization for more information)

OIDC client registration

To register OIDC clients:

1. Use the web UI: go to the Settings app of Web Application Platform and search for OpenID Connect tab in the OAuth clients section.
2. Use registration_endpoint API: (see the example JSON).
  Example client registration request when using API:

POST https://localhost:8443/authentication/api/oidc/register

BODY:

{

           client_name: “Client name”,

           redirect_uris: [“redirect uri”] // comma separated URIs

}

Limitations of the client registration endpoint:

You cannot provide supported grant types or response types – default options are set.
Authentication server generates the client secret automatically.

However, you can update all of these attributes any time in the OAuth clients section of the Settings app (i.e. using the web UI).

Teamwork Cloud REST API access

After the OIDC client gets ID token after user authentication, it can call Teamwork Cloud REST API endpoints by providing the following header:

Authorization: Token <ID token>