Credentials: Managing credentials for OAuth 2.0 or OpenID Connect (Connect 2024)
The Connect server has a so-called Secure Store, i.e. an area in the database that is used for the encrypted storage of credentials. Authorization when using OAuth 2.0 or OpenID Connect is performed using tokens that are stored in the secure store. In addition, this scenario usually requires (long-lived) tokens for renewing the (short-lived) access token as well as connection information for the renewal process, which is also stored in the Secure Store. Future versions of the Connect Server will support the optional offloading of certificates and passwords to the Secure Store.
The administration of the access data stored in the Secure Store is carried out via the page Connection Designer → Credentials. Here, new credentials can be entered (or obtained from an external service), edited and deleted. Each entry in the Secure Store has a unique name that identifies the entry. An entry can contain one or more of the following record types:
Connection information
Access token
Refresh token
Password (currently not used)
Certificate (currently not used)
To obtain credentials for an OAuth 2.0 or OIDC authorization provider, a record of the type "Connection information" must be created, first. This information can then be used to obtain an access token from the authorization provider and, in most cases, also a refresh token for renewing the access token.
Obtaining credentials for OAuth 2.0 or OpenID Connect
To obtain credentials from an OAuth 2.0 or OpenID Connect provider, you first need to maintain the appropriate connection information. To do so, navigate to the page Connection Designer → Credentials and click on the "Add credentials" button. In the window that now appears, assign a unique name to the corresponding record in the Secure Store and click on “OK”.
Now the editor for a new Secure Store record is displayed. To obtain credentials for OAuth 2.0 / OIDC, select the record type "OAuth / OpenID Connect" in the Type field. Now select the provider from which you want to obtain credentials in the Authorization Provider field.
To authenticate the application against the authorization provider, the Client ID and Client Secret fields need to be filled with the data assigned by the authorization provider. The procedure for obtaining this data varies from provider to provider. Some examples can be found at the end of this article. If the authorization provider supports multiple authorization flows, the flow to be used must be selected in the Authorization Flow field. Then, in the Scopes field, select all the scopes that are needed in your scenario. Note here that for some authorization providers, the exact set of scopes that was specified when the application was registered must be selected here. Finally, the Redirect URI is required, i.e. the URI to which the authorization provider forwards the browser after the provider-specific authorization. This URI must use the HTTPS protocol and be reachable from the current client. For many authorization providers, this URI also needs to be specified when registering the application, and both URIs must match.
After maintaining this data, click the "Save" button to save the connection information and follow the instructions in the "Renewing credentials for OAuth 2.0 or OpenID Connect" section to request the required access tokens.
Renewing credentials for OAuth 2.0 or OpenID Connect
To obtain new credentials from an OAuth 2.0 or OpenID Connect provider, navigate to the page Connection Designer → Credentials and click the “Edit” button next to the desired connection information. This will display the page for editing the connection information. Here you can make adjustments if necessary.
Now click on the "Save" button. A window appears asking whether new access tokens should be requested.
Click the "Yes" button to start the access token request. This opens a new browser window for authentication. The content of this window is generated by the authorization provider. Follow the instructions in this window until it closes by itself or until you are prompted to close the window. If you have already authenticated, the window may immediately close by itself.
Using the credentials for OAuth 2.0 or OpenID Connect for authorization
For authorization using OAuth 2.0 or OIDC, the Http.Client.Handlers.HttpOAuthHandler class must be included as a client handler in the corresponding HTTP client. The constructor of this class has only one parameter named "secureStoreItemName". This must be set to the name of the secure store record, which contains the corresponding connection information and access tokens. It is recommended to retrieve this name from the connection information configuration. The following example shows a typical definition for an HTTP client with authorization via OAuth 2.0 or OpenID Connect:
Technical requirements for using OAuth 2.0 or OpenID Connect
When using OAuth 2.0, the server must be able to reach the corresponding OAuth endpoints via HTTPS. Please note that some OAuth providers require an HTTPS connection for the backchannel and often only accept certificates issued by an official certificate authority. The service provider's OAuth endpoints should be directly accessible to the Connect Server (without a separate proxy server). The use of a standard proxy defined at operating system level should also work, but has not been explicitly tested.
The current implementation of OAuth supports the following authorization flows: Assertion, Authorization Code, Authorization Code with PKCE and Client Credentials. The flows Implicit and Resource Owner Password, which are considered insecure, are not currently supported. The Device Code and Hybrid authorization flows are also not supported.
If the authorization provider supports OpenID Connect (OIDC), the configuration can be determined using OIDC Discovery (if supported by the provider). In addition, the OAuth functionalities that form the basis for OIDC are supported in this case.
Registering Connect as an OAuth 2.0 client application
Before the Connect Server can request authorization from an OAuth 2.0 provider, it must be registered there as a client application. Since the URI of the Connect Server installation varies for on-premise installations, no general registration can be made by the software manufacturer.
Azure DevOps
The registration of the app can be done via the URI https://app.vsaex.visualstudio.com/app/register The base URI of the Connect Server installation must use the HTTPS protocol. The base URI of the Connect Server installation must use the HTTPS protocol. Enter the Connect Server base URI into the field Application Website, and the Connect Server base URI supplemented by the path /authorization/oauth into the field Authorization Callback URL. Then mark the required scopes. These cannot only be adjusted later. If you need adjustment, you need to delete the app registration and create a new one. Also note that when creating an access token, you need to specify exactly the same set of scopes as used during the app registration. Requesting an access token for part of these scopes is not supported.
After registering the client application, Client ID as well as Client Secret are displayed in the fields App ID and Client Secret (not App Secret!). These values are required for configuring the connection. Subsequent changes to the settings or deletion of the app can be done via the URI https://app.vsaex.visualstudio.com/me take place.
If REST APIs return an error, such as “TF400813: The user "<GUID>" is not authorized to access this resource” verify that Third-party application access via OAuth is allowed in the organizational settings at https://dev.azure.com/{your-org-name}/_settings/organizationPolicy.
Azure Active Directory
The registration of an app can be done in the Azure Portal under Azure Active Directory → App Registrations (https://portal.azure.com/#view/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/~/RegisteredApps). The base URI of the Connect Server installation must use the HTTPS protocol. In the Redirection URI (Optional) section, select type “Web“ and enter the Connect Server base URI with the path /authorization/oauth added. Then click “Register”.
The client ID of the newly registered application can now be found in the "Application ID (Client)" field. To generate the client secret, click on "Add a certificate or secret". On the page that now appears, click the "New secret client key" button in the "Secret client keys" area. Now enter a name (e.g. "Connect Server") and select the validity period of the key. Then click on "Add" to generate the key. Now the new client key is displayed in the table column “Value”. Click the button to the right of this value to copy it to the clipboard. Note that the key can only be displayed/copied at this location immediately after generation. If the client key is required at a later time, a new key must be generated in each case. The client key must be used as the client secret in the Connect Server.
Note that a client ID for Azure Active Directory is valid for a maximum of two years. At latest then, a new Client ID must be generated. This limit cannot be changed.
Github
The registration of an app is done via the URI https://github.com/settings/developers. Select the “OAuth Apps” section and click the “New OAuth App” button.
On the following page, enter the information about your Connect Server installation, and then click the “Register application” button:
On the next page, the Client ID of the newly registered app is displayed.
Now click on "Generate a new client secret" to generate a client secret. You will now be asked to confirm your identity again (e.g. by entering a password) and then the newly generated client secret will be displayed:
Copy the Client Secret immediately using the appropriate button, as it cannot be displayed later.
The registration of an app is done via the Developer Console using the URI https://console.cloud.google.com/projectcreate.
Assign a project name here and then click on "Create".
Now navigate of the screen to APIs & Services → Enable APIs & services using the menu on the left side of the page. A list of the Google services currently available for your app is now displayed. Additional Google services can be added and thus made available via the "Library" menu item. Now select the "Credentials" menu item and then click the "Create credentials" button at the top of the screen. A drop-down menu appears:
Select the "OAuth client ID" option here. The following page appears:
Select the type "Web Application" and assign a name to your application. Then click on "Add URI" in the "Authorized Redirect URIs" area and enter the redirect URI of your Connect Server installation. Then click on "Create". A window appears with the Client ID and Client Secret of your application.
Copy this information because you will not be able to access it later.
Google only provides a refresh token with the first authentication request. Therefore, before refreshing the access token, it is important to visit the page https://myaccount.google.com/u/0/permissions and remove the existing access permissions. As a result, the next authentication request redisplays the UI for confirming access and then generates a new refresh token.