Providing DotAlign Cloud API access to services and background processes

If you choose to make it available, your DotAlign Cloud API can be accessed by other internal and external applications to enable scenarios like data extraction into a CRM system, or for building custom interactive end user applications. For this to happen in a secure fashion, the DotAlign Cloud API has to be “exposed” and an admin of your Azure tenant has to grant explicit consent.

Typically, in this scenario, the API is accessed by a service or a background process, without the context of a specific user. This is usually called the client credentials flow in OAUTH terminology, and must only be used by confidential clients, as it requires the holding of secrets.

The DotAlign Cloud API offers two scopes for API access, that is to say it offers two level of access:

• DotAlignCloud.Read.All - This scope has wide access to all data across all teams in your DotAlign Cloud deployment
• DotAlignCloud.Read.Limited - This scope has access to very restricted information, for example, first and last names, email address and a relationship score for each person

The following configuration steps can be used to set up app registrations inside of Microsoft Azure to enable your inhouse or 3rd party apps to be able to access your DotAlign dataset, with you choosing the appropriate scope.

Steps

1. Locate DotAlign Cloud’s app registration

Find the DotAlign Cloud app registration by going to Portal > Azure Active Directory > App registrations > All Applications, and searching for it. The name of the registration is in the form dotalign-SOME_UNIQUE_ID, for example dotalign-ysjaskhsdgsk.

2. Expose the API

In the DotAlign Cloud API's app registration, you need to expose the API for other clients to be able to consume. Because of a limitation in the Azure portal, you must do this directly by modifying the manifest file of the app registration.

In the image below, the text inside the red rectangle was added to create a scope/permission that can be exposed out of this app registration.

The text is below for your convenience. Please change the GUID and paste it into your app registration's manifest. Also set the value to be the scope you want to expose. To be clear, at this point you're just exposing the possibility of an external party being able to connect to the API, and not actually providing that access.

"appRoles": [
    {
        "allowedMemberTypes": [
            "Application"
        ],
        "description": "Read access to the full DotAlign Cloud dataset from all teams",
        "displayName": "DotAlign Cloud all teams data reader",
        "id": "GENERATE_A_NEW_GUID",
        "isEnabled": true,
        "lang": null,
        "origin": "Application",
        "value": "DotAlignCloud.Read.All"
    }
]

If you would like to expose both scopes, you need multiple entries, like so:

"appRoles": [
    {
        "allowedMemberTypes": [
            "Application"
        ],
        "description": "Read access to the full DotAlign Cloud dataset from all teams",
        "displayName": "DotAlign Cloud all teams full data reader",
        "id": "GENERATE_A_NEW_GUID",
        "isEnabled": true,
        "lang": null,
        "origin": "Application",
        "value": "DotAlignCloud.Read.All"
    },
    {
        "allowedMemberTypes": [
            "Application"
        ],
        "description": "Read access to a very limited set of DotAlign Cloud data from all teams",
        "displayName": "DotAlign Cloud all teams limited data reader",
        "id": "GENERATE_A_NEW_GUID",
        "isEnabled": true,
        "lang": null,
        "origin": "Application",
        "value": "DotAlignCloud.Read.Limited"
    }
]

Client apps can now request to consume the API but will only be able to do so if they can prove their identity (using an AppId/AppSecret or a certificate), and a tenant administrator gives them consent.

3. Add a new app registration for the service/background process

There needs to be an app registration for the client app. A developer who would like to access the DotAlign Cloud API would have to create an app registration or request a tenant admin to do so.

You need to provide a name to the app registration and choose the kinds of account you want to allow using this app registration. Unless you have some specific scenario in mind, you would choose the first option which limits the app registration to your organization.

4. Grant permissions to the new app registration

The permissions to access the DotAlign Cloud API can be added to this registration. This can be done inside the "API Permissions" section, by clicking on “Add a permission”.

Search for the DotAlign Cloud app registration under the APIs my organization uses tab.

Choose Application permissions and then check the appropriate scope. Only one scope should be chosen because of the way client credentials flow works (the client gets access to all scopes).

5. Create a client secret

Now that the app registration and permissions are in place, a client secret needs to be created so that a service can use the client id/client secret to gain access using the "client credentials" flow.

6. Grant admin consent

The last step in the process is for a tenant administrator to grant consent for the use of this app registration to be able to access the DotAlign Cloud API. This can be done by clicking on API Permissions and then the "Grant admin consent to DotAlign, Inc." button.

Now the various properties of the app registration can be shared with developers to enable them to write applications that access the DotAlign Cloud API.

Related links

1. Microsoft Graph API, an overview

​https://docs.microsoft.com/en-us/graph/overview​

1. Microsoft Graph access on behalf of a user

​https://developer.microsoft.com/en-us/graph/docs/concepts/auth_v2_service​

1. Azure AD authentication scenarios

​https://docs.microsoft.com/en-us/azure/active-directory/develop/authentication-scenarios​

1. Microsoft Graph API permissions

​https://docs.microsoft.com/en-us/graph/permissions-reference