Configure Azure Active Directory¶

Colectica Portal can use Azure Active Directory for authentication. Follow these instructions to enable Azure Active Directory support.

Register a Colectica RepositoryPortal in Azure AD¶

Navigate to the App registrations page under the Azure Active Directory overview.
Select New registration.
When the Register an application page appears:
- In the Name section, enter a meaningful application name that will be displayed to users of the app, for example ColecticaRepository. If you have multiple Colectica Repositories, use different names when registering each one.
- Leave Supported account types on the default setting of Accounts in this organizational directory only.
- For Redirect URL, select web. Enter your repository URI plus signin-oidc, such as https://colectica.your.org/signin-oidc.
Select Register to create the application.
On the app Overview page, find the ColecticaRepository Application (client) ID value and the ColecticaRepository Directory (tenant) ID and record them for later. You’ll need it for configuring the Portal.
Select Authentication section, and:
1. For Front-channel logout URL, Enter your repository URI plus signout-oidc, such as https://colectica.your.org/signout-oidc.
2. For Implicit grant and hybrid flows, check the boxes for both Access tokens and ID tokens.
3. Click Save
Select the Manifest section, and:
1. find the accessTokenAcceptedVersion property and change the value to 2
2. Click Save
Select the Token Configuration section, and:
1. Click Add optional claim
2. Select Token Type of ID
  - Select email, family_name, and given_name
  - Check the box to allow OpenID Connect scopes
  - Click Add
3. Again, Click Add optional claim
4. Select Token Type of Access
  - Select email, family_name, and given_name
  - Check the box to allow OpenID Connect scopes
  - Click Add
Select the Certificates & secrets section, and:
1. Click New client secret
2. Enter ColecticaRepositorySecret as the Description
3. Set Expires to Never
4. Copy and record the Value to use later.
Select the Expose an API section, and:
1. Select Add a scope
2. accept the proposed Application ID URI (api://{clientId}) by selecting Save and Continue, and record it for later.
3. Enter the following parameters
  - for Scope name: ColecticaRepositoryApi
  - Keep Admins and users for Who can consent
  - in Admin consent display name: Access Colectica as a user
  - in Admin consent description: Access Colectica as a user
  - in User consent display name: Access Colectica as a user
  - in User consent description: Access Colectica as a user
  - Keep State as Enabled
  - Select Add scope

Register a client for Colectica Desktop applications¶

Navigate to the App registrations page under the Azure Active Directory overview.
Select New registration.
When the Register an application page appears, enter your application’s registration information:
1. In the Name section, enter a meaningful application name that will be displayed to users of the app, for example ColecticaDesktopClient.
2. Leave Supported account types on the default setting of Accounts in this organizational directory only.
3. In Redirect URI, select Public client/native.
Next to the Redirect URIs label, click Add a Redirect URI
1. Click Add a Platform
2. Select Mobile and desktop applications
3. Place a check mark next to all proposed redirect URIs
4. Click Configure
Select the API permissions section
1. Click the Add a permission button and then,
2. Ensure that the My APIs tab is selected
3. In the list of APIs, select the API ColecticaRepository.
4. In the Delegated permissions section, ensure that the permissions, ColecticaRepositoryApi, are checked. Use the search box if necessary.
5. Select the Add permissions button
On the app Overview page, find the ColecticaDesktopClient Application (client) ID and record it for later. You’ll need it for configuring the Portal.

Configure Colectica Portal¶

Colectica Portal uses OpenID Connect for authentication to Azure Active Directory. The inclusion of the email claim is required in the OIDC profile to enable account creation. Follow these instructions to enable OpenID Connect support.

In PortalDir\appsettings.json, find the OpenIDConnect section.

"OpenIDConnect":
{
   "Enabled": "false",
   "Authority": "",
   "ClientId": "",
   "ClientSecret": "",
   "Audience": "",
   "NameClaimType": "",
   "GetClaimsFromUserInfoEndpoint": "true"
}

Set the Enabled property to true.
Find the Directory (tenant) ID from the Azure AD’s app registration for ColecticaRepository to use in the next step
Set the Authority property to the URL for the Azure AD server to https://login.microsoftonline.com/{tenant ID}/v2.0/, replacing the /{tenant ID}/ with your ColecticaRepository Directory (tenant) ID. It should look similar to https://login.microsoftonline.com/00000000-0000-0000-0000-000000000000/v2.0/.
Set the ClientId for the ColecticaRepository Application (client) ID app registration.
Set the ClientSecret to the ColecticaRepositorySecret from the repository app registration.
Set the GetClaimsFromUserInfoEndpoint to “true”.
To manage which OIDC users and groups map to the different Colectica roles, see Configure Active Directory.

Configure Colectica Desktop applications¶

Before synchronizing with a remote repository, the repository must be configured in Colectica Desktop tools.

From the File menu, choose Repositories.
Click the Add button.
Select Transport of REST
Set the Hostname to the Repository (Portal) hostname.
Select Authentication AzureActiveDirectory.
Set the Client Id to the ColecticaDesktopClient Application (client) ID client app registration.
Set the Tenant Id to the ColecticaRepository Directory (tenant) ID repository app registration.
Set the Scope to the Application ID URI (api://{clientId}) from the Expose an API in the the ColecticaRepository repository app registration.
Close the File menu. Your repository configuration will automatically be saved.

Register a client for Colectica SDK applications¶

If you are using the Colectica SDK to create programs that connect to the Colectica Repository using Azure AD client secrets or certificates, you will need to register a client app for a confidential client. Before connecting to a remote repository, the client app must be configured in the Azure AD portal.

Ensure that App registrations is set to Yes by an Administrator.
Navigate to the App registrations page under the Azure Active Directory overview.
Select New registration.
When the Register an application page appears, enter your application’s registration information:
1. In the Name section, enter a meaningful application name that will be displayed to users of the app, for example ColecticaSDKClient.
2. Leave Supported account types on the default setting of Accounts in this organizational directory only.
3. In Redirect URI, select Public client/native.
Select the API permissions section
1. Click the Add a permission button and then,
2. Ensure that the My APIs tab is selected
3. In the list of APIs, select the API ColecticaRepository.
4. In the Delegated permissions section, ensure that the permissions, ColecticaRepositoryApi, are checked. Use the search box if necessary.
5. Select the Add permissions button
On the app Overview page, find the ColecticaSDKClient Application (client) ID and record it for later. You’ll need it for configuring the your SDK code.
In your SDK code, configure the RepositoryConnectionInfo for your Azure client. TransportMethod should be set to REST, AuthenticationMethod should be set to AzureActiveDirectory, AzureAuthenticationMode should be set to ClientSecret or ClientCertificate. Either ClientSecret or ClientCertificateThumbprint should be set based on your choice of secret or certificate. If using a client certificate, it should be in the user’s certificate store.
Azure AD requires a special scope to be specified for client apps. The Scope should be set to api://{RepositoryApplicationID}/.default. The RepositoryApplicationID is the ClientId for the ColecticaRepository Application (client) ID app registration.
After the first call to the Colectica REST API, a user will be created on the Repository with the ClientId as a name. A Colectica admin can then give the application ColecticaUser or ColecticaAdministrator roles via the admin area.

var connection = new RepositoryConnectionInfo();
connection.AuthenticationMethod = RepositoryAuthenticationMethod.AzureActiveDirectory;
connection.TransportMethod = RepositoryTransportMethod.REST;
connection.Url = "https://colectica.example.org/";

// The Scope, TenantId, and ClientId from Azure AD, similar to below
connection.Scope = "api://11195939-E6B9-4307-941B-BFC38EDF1280/.default";
connection.TenantId = "222EE97F-F557-4D13-9EA6-200EE21B2242";
connection.ClientId = "333B5A39-413A-4785-8546-256E62110D7E";

connection.AzureAuthenticationMode = AzureAuthenticationMode.ClientSecret;
connection.ClientSecret = "secretrandompasswordfromAzureAD";

//connection.AzureAuthenticationMode = AzureAuthenticationMode.ClientCertificate;
//connection.ClientCertificateThumbprint = "abc1238cd8b4c0fc6096f3deae2e7e73112a4";

var client = new RestRepositoryClient(connection);
var info = client.GetRepositoryInfo();

Use Azure AD App Roles¶

Colectica Repository allows configuring Azure App Roles for managing Colectica Roles.

To create an app role by using the Azure portal’s user interface:

Navigate to the App registration page for the Repository under the Azure Active Directory overview.
Select App roles, and then select Create app role.

In the Create app role pane, create the following app roles.

Display name	Allowed member types	Value	Description
Colectica Guest	Both	ColecticaGuest	Colectica Read Only operations
Colectica User	Both	ColecticaUser	Colectica Read and Write operations
Colectica Administrator	Both	ColecticaAdministrator	Colectica Read, Write, and Admin operations

Select Apply to save your changes.
In the Enterprise applications editor for Repository, you can assign roles under Manage, select Users and groups.
Optionally, set the SynchronizeExternalRoles feature to true in the Repository’s appsettings.json to solely rely on the App roles configured in Azure AD.