Identity Management: Set up TeamForge OAuth 2.0 Authorization Framework

TeamForge OAuth nomenclature

It is assumed that you are familiar with the OAuth and OpenID Connect frameworks, terms and concepts. Here's a few links and references for further reading.

Term	Description
OAUTH	The OAuth 2.0 Authorization Framework RFC 6749
OIDC	OpenID Connect Core 1.0
BEARER TOKEN	The OAuth 2.0 Authorization Framework: Bearer Token Usaage RFC 6750
SAMLBEARER	SAML 2.0 Bearer Assertion Profiles for OAuth 2.0
JWE	JSON Web Encryption (JWE)
JWS	JSON Web Signature (JWS)
JWT	JSON Web Token (JWT)
JWA	JSON Web Algorithms (JWA)
JWK	JSON Web Key (JWK)

TeamForge OAuth overview

In the traditional client-server authentication model, client applications must have access to the Resource Owner's credentials in orderto request and access protected resources on the Resource Server. Sharing Resource Owner's credentials such as usernames and passwords to third party applications poses several problems, security being one of the major ones.

Frameworks such as the OAuth 2.0 and OpedID Connect help in mitigating such security risks and hence TeamForge's authentication model has been completely rebuilt on top of OpenID Connect and OAuth 2.0 Authorization frameworks.

TeamForge OAuth roles

TeamForge OAuth authorization process involves interaction between four entities (roles) such as the user, IdP, SP and client application. The following table lists the roles that an entity can assume in the TeamForge OAuth setup.

Entity/Role	OAuth Term	OIDC Term	SAML Term	Description
User	Resource Owner	End User	User	Human or machine that intends to access a resource of an SP.
Service Provider (SP)	Resource Server	Relying Party	Service Provider, Relying Party	Entity that demands authentication to grant access to some resource. The SP trusts the IdP to perform the authentication on its behalf.
Client	Client	-	Browser	Application interacting with SP and IdP on the User's behalf.
Identity Provider (IdP)	Authorization Server	Provider	Identity Provider, Asserting Party	Entity that proves identity and authenticates an user.

OAuth 2.0 protocol flow

The following illustration shows the OAuth 2.0 protocol flow.

(A) The client application requests authorization from the Resource Owner.
(B) The Resource Owner responds to the client with a credential called 'Authorization Grant'.
(C) The client then redeems the 'Authorization Grant' with the Authorization Server for a valid 'Access Token' (D).
(D) The client then reaches out to the Resource Server with the Access Token and gains access to the protected resource.

For more information about the OAuth 2.0 protocol flow, see OAuth 2.0 Protocol Flow.

It's recommended that you read The OAuth 2.0 Authorization Framework RFC 6749 and get familiar with OAth Roles, Protocol Flow, Access Tokens, Grant Types, Client Types and so on before you proceed.

TeamForge can act both as an IdP and Service Provider and at times as a client too. The TeamForge Web Application is one of the system defined clients that use TeamForge IdP's OAuth services. For more information about the system defined clients, see System defined clients.

TeamForge API authentication and access tokens

Both TeamForge REST and SOAP APIs use OAuth 2.0 access tokens for authentication. Clients can obtain access tokens fromthe token endpoint which is located at /oauth/auth/token.

Access Tokens

The tokens used by the TeamForge API are Bearer Tokens as specified in RFC 6750. This means that it is possible and allowed to share tokens among multiple clients or to have clients pass tokens to intermediate services, which then delegate tokens to TeamForge. TeamForge tokens use a standardized format, JSON Web Token (JWT). However, clients should consider access tokens to be opaque in order to guarantee compatibility with future TeamForge versions. It is the client's responsibility to protect the access token against theft. This means that access tokens should only be transmitted over SSL-secured connections and should not be persisted.

TeamForge OAuth scopes

Scopes can be used to restrict which services a token can be used for. Limiting the number of scopes decreases the potential damage that could occur in case an access token is stolen, so it is advisable to restrict the number of scopes to a minimum.

TeamForge currently supports the following list of scopes.

Scope	Description
urn:ctf:services:ctf	CollabNet TeamForge application services. Use this scope to call the TeamForge REST API.
urn:ctf:services:svn	Subversion services. Use this to call the Subversion REST API.
urn:ctf:services:gerrit	Git/Gerrit services. Use this to call the Git REST API.
urn:ctf:services:soap60	SOAP60 services. Use this needed to call the TeamForge SOAP API or the EventQ Reporting API.

Client ID and Client Secret

In order to use TeamForge's OAuth services, a client application must be registered with TeamForge. Upon registration, the client gets its client credentials: Client ID and Client Secret. For more information about how to get the Client ID and Client Secret, see Add clients.

Client ID	The Client ID is a unique identifier used by TeamForge to identify the client application and is used in building the Authorization URLs.
Client Secret	The Client Secret is a unique identifier used to authenticate the client application's identity.

TeamForge OAuth grant types

When a client requests access token from an Authorization Server, it uses the Authorization Grant, which is a credential that represents the Resource Owner's authorization to access protected resources. Of the four standard grant types defined in the The OAuth 2.0 Authorization Framework RFC 6749, TeamForge supports the following three grant types:

Authorization Code grant type (authorization_code)
Resource Owner Password Credentials Grant Type (password)
Client Credentials grant type (client_credentials)

In addition, TeamForge supports the following custom grant type:

Anonymous grant type (urn:ctf:grant_type:anonymous) (rn:ctf:grant_type:anonymous)

TeamForge system defined grant types

TeamForge also supports the following system defined grant types. However, these grant types are used by TeamForge's system defined clients to obtain access tokens and are therefore not supposed to be used for other custom clients.

JSession (urn:ctf:grant_type:jsession)
SCM Admin (urn:ctf:grant_type:scmrequestkey:scmadmin)
SCM Viewer (urn:ctf:grant_type:scmrequestkey:scmviewer)
Token (urn:ctf:grant_type:token)

Authorization Code grant type (authorization_code)

The Authorization Code grant type can be used if the client intends to use TeamForge as its IdP. This grant type, if used by clients, provides an access token for a valid authorization code. This is a redirection based grant type and hence you must add one or more Redirect URIs while adding clients that use this grant type.

Note: Include a comma separated list of Redirect URIs in case you want to set up multiple URIs.

How to get an authorization code?

Clients (Relying Party) must request the authorization code from the TeamForge IdP URL (/oauth/oidc/authorize) with the following parameters:

scope = open_id (mandatory for OIDC clients) 
response_type = code (mandatory for OIDC clients) 
client_id = <Client ID generated while registering the client with TeamForge>
redirect_uri = <URL encoded Redirect URI>

After successful authorization, TeamForge IdP provides the authorization code to the redirect URI configured while adding the client. Here's a sample OIDC response after a successful authorization:

https://<your_redirect_uri>?code=<authorization_code>

Up on getting the authorization code, the client can redeem it with the Authorization Server to obtain an access token.

The following illustration shows the authorization code flow.

Usage example to obtain an access token

# Base URL of TeamForge site. 
site_url="https://teamforge.example.com"  

# Requested scope (all) 
scope="urn:ctf:services:ctf urn:ctf:services:svn urn:ctf:services:gerrit urn:ctf:services:soap60"  

# Client's authorization code 
code=<your authorization code> 
  
curl -d "grant_type=authorization_code&client_id=<your Client ID>&client_secret=<your Client Secret>
&scope=$scope&code=$code" $site_url/oauth/auth/token

A successful response will return the HTTP 200 status code and the response body will contain something like this:

{ 
  "access_token" : "eyJraWQiOiIxIiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJhZG1pbiIsImF1ZCI..." , 
  "token_type" : "Bearer" 
}

In compliance with the Bearer Tokens specification (RFC 6750), TeamForge expects access tokens to be passed in the Authorization header:

GET /resource HTTP/1.1             
Host: teamforge.example.com             
Authorization: Bearer SAksa921hjsi...

The only exception to this is the SOAP API which expects the token to be passed as part of the SOAP request payload in accordance with the API documentaton.

For more information, see Authorization Code grant type (authorization_code).

Resource Owner Password Credentials Grant Type (password)

Clients can use the Resource Owner Password Credentials grant type to get an access token for a given username and password.

Usage example to obtain an access token

# Base URL of TeamForge site.
site_url="https://teamforge.example.com"  

# TeamForge authentication credentials. 
username="foo" 
password="bar"  

# Requested scope (all)
scope="urn:ctf:services:ctf urn:ctf:services:svn urn:ctf:services:gerrit urn:ctf:services:soap60"  

curl -d "grant_type=password&client_id=<your Client ID>&scope=$scope&username=$username&password=$password"
$site_url/oauth/auth/token

You can see this from this example that it is sending an HTTP POST request to the /outh/auth/token endpoint, and the content of the request body contains the following data:

grant_type=password: Indicates you are providing username and password.
client_id=<your Client ID>: Client ID generated while adding the client.
scope= ...: Space-separated list of requested scopes.
username=value&password=value: The valid TeamForge user credentials.

For more information, see Resource Owner Password Credentials Grant Type (password).

Client Credentials grant type (client_credentials)

Clients can use the Client Credentials grant type to get an access token for a given Client ID and Client Secret. Use this grant type only for trusted and confidential clients.

Important: Clients that use the Client Credentials grant type must be assigned with a valid TeamForge license in order for the clients to be able to access TeamForge resources as OAuth clients.

Usage example to obtain an access token

# Base URL of TeamForge site. 
site_url="https://teamforge.example.com"  

# Requested scope (all) 
scope="urn:ctf:services:ctf urn:ctf:services:svn urn:ctf:services:gerrit urn:ctf:services:soap60"  

curl -d "grant_type=client_credentials&client_id=<your Client ID>&client_secret=<your Client Secret>
&scope=$scope" $site_url/oauth/auth/token

For more information, see Client Credentials grant type (client_credentials).

Anonymous grant type (urn:ctf:grant_type:anonymous)

Use this grant type for clients that need to access TeamForge's public resources.

Usage example to obtain an access token

# Base URL of TeamForge site. 
site_url="https://teamforge.example.com"  

# Requested scope (all) 
scope="urn:ctf:services:ctf urn:ctf:services:svn urn:ctf:services:gerrit urn:ctf:services:soap60"  

curl -d "grant_type=urn:ctf:grant_type:anonymous&client_id=<your Client ID>&client_secret=<your Client Secret>
&scope=$scope" $site_url/oauth/auth/token

Unsupported grant types

The following grant types are not supported by TeamForge.

refresh_token
urn:ietf:params:oauth-grant-tupe:saml2-bearer

Federated Identity Management

Federated Identity Management refers to the process of storing user credentials with an IdP (such as TeamForge, SAML and so on) and having the Service Provider (SP) rely on the IdP to validate user credentials when he/she tries to access its resources.

TeamForge supports federated identity. By default, federated login is disable in TeamForge. Site Administrators must enable federated login and select an IdP.

Log on to TeamForge as a Site Administrator.
Select My Workspace > Admin.
Select My Page > Identity.
Select the Federation tab.
Select the Use Federated Login check box and select an IdP from the drop-down list.
Click Save.

Logging into TeamForge in a Federated Login Setup

Once enabled, TeamForge Web Application, by virtue of being a system defined client application (see System defined clients), follows the OAuth authorization/authentication process to access TeamForge services on behalf of the Resource Owner (user).

Click Login.

You are redirected to an authorization page.
Type the user name and password and click Log In.
You, as a Resource Owner, are then prompted to either allow or deny the client application (TeamForge Web Application) to access the resources on the Resource Server (TeamForge Application Server).
Click Allow or Deny to allow or deny access respectively.

System defined clients

TeamForge OAuth consists of the following system defined clients:

TeamForge Web Application Client (ctfweb)
CodeBrowser Client (codebrowser)
SOAP60 Client (soap60-client0
SCM Client (scm-client)
API Client (api-client)
App Client (app-client)

These clients have been pre-defined as illustrated in the following table.

System Defined Client	Grant Type	Services	Token Life Time (in seconds)
ctfweb	authoriztion_code urn:ctf:grant_type:jsession	soap60,ctf,gerrit,svn	3600
codebrowser	urn:ctf:grant_type:anonymous	soap60	3600
soap60-client	password urn:ctf:grant_type:anonymous	soap60	3600
scm-client	urn:ctf:grant_type:scmrequestkey:scmviewer urn:ctf:grant_type:scmrequestkey:scmadmin	soap60,ctf	3600
api-client	paswword	soap60,ctf,gerrit,svn	3600
app-client	urn:ctf:grant_type:token	soap60,ctf,gerrit,svn	3600

You cannot edit these system defined clients. The following error message shows up if you try to edit these clients.

Error editing oauth client: System defined clients are not allowed to be modified.

Add clients

In order to use TeamForge's OAuth services, a client application must be registered with TeamForge. Upon registration, the client gets its client credentials: Client ID and Client Secret.

Client ID	The Client ID is a unique identifier used by TeamForge to identify the client application and is used in building the Authorization URLs.
Client Secret	The Client Secret is a unique identifier used to authenticate the client application's identity.

To add a TeamForge OAuth client:

Log on to TeamForge as a Site Administrator.
Select Admin from the My Workspace menu.
Select Identity from the Projects menu.
Click Add Client from the OAuth tab.
The Add Client dialog box appears.
Enter client information.
The following parameters are required to register a client application with TeamForge:
- Client Application Name: Type a name for your client.
- Redirect URIs: Include a comma separated list of Redirect URIs in case you want to set up multiple URIs. Redirect URIs are required only for clients that use the Authorization Code grant type.
- Grant Type: Select the client's grant type.
- Services (scopes): Select one or more TeamForge OAuth scopes.
- Token Life Time (in seconds): Type the duration (in seconds) for which the token is valid.
- License Types: Select a TeamForge license for the client. This is required only for clients that use the Client Credentials grant type.
Click Save. Once the client is added successfully, a message containing the client's credentials is shown.

Warning: Once the client is added successfully, the Client ID and Client Secret are generated and shown in the message. You must copy and keep your Client Secret safe before closing the message as you cannot fetch your client secret later from anywhere else.