OAuth2 and OpenIDConnect
Attention
This module is part of Tuleap Enterprise. It might not be available on your installation of Tuleap.
Tuleap oauth2_server plugin provides both OAuth2 and OpenIDConnect servers. This plugin allows for other websites to interconnect with Tuleap easily. Users can grant authorizations to external websites or applications to let them access Tuleap resources (through the REST API) or sign in with a Tuleap account.
It is a recommended and secure way to let other applications interact with Tuleap’s REST API with Access Tokens. Applications can also authenticate users with their Tuleap account by leveraging OpenIDConnect, providing Single sign-on capabilities.
Setup
The plugin tuleap-plugin-oauth2-server must be installed and enabled on your
Tuleap instance, see Plugins installation to learn how to do that.
Definitions
Throughout this document, the terms “End-User”, “Client Application” and “Provider” will be used. Here is what they mean:
“Project Administrator”: a Tuleap user. They belong to their Project’s “Project Administrators” user group.
“End-User”: a Tuleap user. They are NOT Project Administrator. In OAuth2 terminology this corresponds to a “resource owner”.
“Client Application”: a software application that is able to request authorization from End-Users to access your Tuleap instance on their behalf through OAuth2 and OpenIDConnect. In OAuth2 terminology this corresponds to a “client”. In OpenIDConnect terminology this is a “Relying Party”.
Client registration
In order to use OAuth2 and OpenIDConnect, the Project Administrator must manually register ([1]) the Client Application in a project.
In Project Administration, click on the “OAuth2 Apps” tab.
When you click on “Add an App”, a modal opens. You may choose the application’s name (text). The “Redirect endpoint” (URL) is required. If the Client Application supports Proof Key for Code Exchange, you should check the “Force usage of PKCE to authenticate” checkbox.
When the Project Administrator creates an OAuth2 App, they must choose a name for it. The name will be shown to End-Users when the Client Application asks their authorization. The redirect endpoint is specific to the application and should be found in its documentation. It is where Tuleap will redirect End-Users after they give (or do not give) authorization to the Client Application.
Tuleap will show the Client Secret only once after creating the application.
Attention
Tuleap will show only once a feedback with the Client Secret the Client Application will need to use OAuth2. Save it somewhere safe. It is used by Tuleap to authenticate the application and is like a password.
Provider registration
Next, register Tuleap as an OAuth2 server or OpenIDConnect provider in the Client Application. You will need to provide:
The Client ID. It starts by
tlp-client-id-.The Client Secret that appeared only once at Client registration. It starts by
tlp-oauth2-c1-.The Authorization endpoint:
https://<your-tuleap-domain>/oauth2/authorize. It is where the Client Application will redirect End-Users to ask Tuleap for authorization.The Token endpoint:
https://<your-tuleap-domain>/oauth2/token. It is where the Client Application will request its OAuth2 Access token to be able to access the Tuleap REST API.The User Information endpoint:
https://<your-tuleap-domain>/oauth2/userinfo. It is where the Client Application will request information about End-Users that have authorized it, for example their user ID or user name.
Granting authorization
Once the Client Application is registered in your project and Tuleap is registered on the Client Application, the Client Application can ask End-Users to grant it authorization to access Tuleap.
The process starts in the Client Application, which will redirect End-Users to Tuleap’s Authorization endpoint page:
Tuleap will ask End-Users to authorize whatever permissions are requested by the Client Application.
When End-Users click on “Authorize”, they will be redirected back to the Client Application. It will now have an Access Token that it can use to access Tuleap’s REST API on the End-Users’ behalf, with their permissions.
Revoking authorization
After having authorized a client application, End-Users can revoke it whenever they want. Access your user preferences:
Click on the “Cog” icon on the right-hand side of your name and profile picture to access your user preferences.
Then, go to the “OAuth2 Apps” tab in user preferences.
Go to the “OAuth2 Apps” tab in your user preferences. All authorized OAuth2 Client applications will be listed with the permissions (Scopes) you have granted them.
When you click on “Revoke authorization”, the application will no longer have access to Tuleap’s REST API. If you use the application again, it will request your authorization once more.
Discovery endpoint
Tuleap implements the OpenIDConnect Discovery endpoint.
The endpoint can be found at:
https://<your-tuleap-domain>/.well-known/openid-configuration
It responds with a JSON object detailing the location of the various endpoints and supported parameters for OAuth2 and OpenIDConnect. You can find there the list of supported OAuth2 scopes that can be requested by a Client application.
Client Application development
If you wish to develop your own Client Application compatible with Tuleap, please refer to RFC6749, RFC7636 and OpenIDConnect Core. Those documents contain all the details needed to implement an OpenIDConnect compatible Application Client.
Please note that only the OAuth2 Authorization Code Grant is supported by Tuleap. The OAuth2 Implicit Grant is not supported.
JSON Web Key Set (JWKS) endpoint
Tuleap signs its OpenIDConnect ID Tokens. To verify this
signature, your client application will need to access the JSON Web Key Set
endpoint to retrieve the signing keys. It can be found at
https://<your-tuleap-domain>/oauth2/jwks.
The signing key is regularly rotated so we advise against storing it in your application.
Token Revocation endpoint
Tuleap implements the OAuth2 Token revocation endpoint
It can be found at https://<your-tuleap-domain>/oauth2/token/revoke
Client Applications that suspect their OAuth2 Refresh Token or OAuth2 Access Token has been compromised can use this endpoint to revoke it and ensure it can no longer be used. To use that endpoint, the Client Application must authenticate itself with its Client ID and Client secret. Please consult RFC7009 for implementation details.
Integrations that leverage OpenID Connect
Resources
Footnotes