Microsoft Entra ID

Previously known as Azure Active Directory

Register Ontopic Suite

1. Navigate to https://entra.microsoft.com (opens new window), choose Entra ID in the left menu, then select App registrations and click New registration.

2. Enter the application name (e.g., "Ontopic Suite"), then click Register.

3. Note down the Application (client) ID and Directory (tenant) ID.

4. Navigate to the Authentication section:

   • Click Add a platform under Platform configurations
   • Select Web
   • Under Redirect URIs, enter "https://{your domain}/oauth2/callback"
   • Click Configure

5. Navigate to the Certificates & secrets section:

   • From the Client secrets tab, click New client secret
   • Enter a description (e.g., "Ontopic Suite") and select an expiration date
   • Click Add
   • Copy the Value of the client secret (it will not be shown again)

6. Navigate to the Token configuration section:

   • Under Optional claims, click Add groups claim
   • Select Security groups and Groups assigned to the application
   • Click Add

7. Navigate to the Expose an API section:

   • Click Add next to Application ID URI
   • Click Save
   • Note the Application ID URI for later use

8. Add API scopes by clicking Add a scope under Scopes defined by this API for each scope in the table below. Enter the Scope name, Admin consent display name, and Admin consent description, then click Add scope:

Scope name	Admin consent display name	Admin consent description
project-description-read	Read project description	Allows the app to read the project description
project-management	Project management	Management of projects including project creation and deletion, managing their settings, data sources and project-level access policies
project-design-read	Read project design	Read access to snapshots and project design artifacts (ontologies, mappings and lenses)
project-design-write	Write project design	Write access to snapshots and project design artifacts
project-sparql-deployment	Deploy project SPARQL endpoints	Deploy and manage SPARQL endpoints in projects
project-sql-deployment	Deploy project SQL endpoints	Deploy and manage SQL endpoints in projects
project-rdf-materialization	Manage RDF materialization	Create and manage RDF materialization jobs in projects
sparql-deployment-list	List SPARQL endpoints	List all the SPARQL endpoints
sql-deployment-list	List SQL endpoints	List all the SQL endpoints
arbitrary-sparql-deployment	Manage arbitrary SPARQL endpoints	Deploy and manage arbitrary SPARQL endpoints (not attached to a project)
arbitrary-sql-deployment	Manage arbitrary SQL endpoints	Deploy and manage arbitrary SQL endpoints (not attached to a project)
sparql-query	Execute SPARQL queries	Execute SPARQL queries
sparql-reformulation	Reformulate SPARQL queries	Reformulate SPARQL queries into SQL queries
sql-reformulation	Reformulate SQL queries	Reformulate semantic SQL queries over VKG into source SQL queries

9. Navigate to the Manifest section:

   • Change requestedAccessTokenVersion from null to 2
   • Click Save

10. Navigate to the API permissions section:

    • Under Configured permissions, click Add a permission
    • Select Microsoft Graph → Application permissions
    • Select Directory.Read.All
    • Click Add permissions
    • Click Grant admin consent for {tenant name} and confirm with Yes

11. Navigate to the App roles section:

    • Click Create app role
    • Enter "ots-project-creator" as Display name
    • Select Both (Users/Groups + Applications) as Allowed member types
    • Enter "ots-project-creator" as Value
    • Enter "Allow to create a project in Ontopic Suite" as Description
    • Click Apply

Assign app roles to users and groups

1. Navigate to https://entra.microsoft.com (opens new window), choose Entra ID in the left menu, then select Enterprise apps and click on the Ontopic Suite application.
2. Choose Users and groups on the left and click on Add user/group
3. Select the user or group
4. Select the app role
5. Click on Assign

Grant another application access to Ontopic Suite

1. Navigate to https://entra.microsoft.com (opens new window), choose Entra ID in the left menu, then select App registrations and click on your application of choice.
2. Move to the API permissions section. Under the Configured permission section, click on Add a permission. Click on the APIs my organization uses tab, and click on the "Ontopic Suite" application. Click on the Delegated permissions tab, and select all the relevant permissions. Then click Add permissions. Last, click on Grant admin consent for {tenant name} and then Yes.

Configure Ontopic Suite

Docker-compose

1. Use or create a registered app from the Azure Active Directory. You will need the Application (client) ID, the Directory (tenant) ID, the client secret, and the Application ID URI of the registered app.

2. Edit the .env file, set:

IDENTITY_SERVICE_PROVIDER_OAUTH2=azure
IDENTITY_SERVICE_AZURE_TENANT_ID=<Directory (tenant) ID>
IDENTITY_SERVICE_AZURE_API_CLIENT_ID=<Application (client) ID>
IDENTITY_SERVICE_SESSION_SCOPE=openid,email,profile,offline_access,<Application ID URI>/project-description-read
IDENTITY_SERVICE_CLIENT_ID=<Application (client) ID>

3. Edit the files default-secrets/identity/client-secret and default-secrets/identity/azure/api-client-secret inserting the client secret.

AWS Marketplace

1. Use or create a registered app from Microsoft Entra ID. You will need the following information from the registered app:

   • Application (client) ID
   • Directory (tenant) ID
   • Client secret
   • Application ID URI

2. Configure Microsoft Entra ID settings using the configuration service running on port 8080:

   • Navigate to the OpenID tab
   • Enter the Application (client) ID for both Client ID and API client ID
   • Enter the client secret for both Client secret and API client secret
   • Enter the Directory (tenant) ID as Tenant ID

3. In the advanced settings, add the Application ID URI to the scope without removing the existing ones.

Note: Changes to the configuration service will restart Ontopic Suite.