Skip to main content

Security

QuickStart Module

This quickstart module shows you how to perform authentication and use security tokens

Authentication

In order to use the API in any programming language, you need to be able to generate an ID Token to identify yourself to the services. This token is issued by Microsoft using your Azure Active Directory and is scoped to the OpenDataDSL API:

scope=api://opendatadsl/.default

The method you use to generate the token is determined by how the application or script will be run.

Application TypeGeneration Method
User application, attended loginUser log in via Web Browser
System application, unattended loginUse secret key specific for the application

Unattended Login

For an unattended login, you will need to create an application in Azure AD and generate a secret. The 3 pieces of information required are:

  • You company tenant id - {{tid}}
  • The id of the application in Azure AD - {{aid}}
  • The generated secret - {{sid}}

Getting the necessary id's and secret

The 3 items above can be retrieved/generated in Azure Active Directory as follows:

Tenant ID

Log into Azure Active Directory, with your tenant selected in Overiew, you should see your tenant id on the main page. Click the copy icon next to the Tenant ID and paste it somewhere safe for later as tid.

Azure AD Tenant ID

Client ID

If you haven't created a new App Registration in Azure Active Directory, you will need to do that now in order to get the application id and generate a secret.

Once you have created your App Registration, click on it so that you are in the Overview screen and copy the Application (client) ID and paste it somewhere safe for later as aid.

Secret

To generate a secret, whilst in the App Registration, click on the Certificates and Secrets menu item.

Azure AD Tenant ID

Create a new client secret, then immediately copy the secret and paste it somewhere safe for later as sid.

Example of getting an Access Token

GET /{{tid}}/oauth2/v2.0/token
Host: login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&
client_id={{aid}}&
client_secret={{sid}}&
scope=api://opendatadsl/.default

Using the token

Once you have the token, you need to add it into an Authorization header with the prefix Bearer:

Authorization: Bearer {{token}}

Example request using the token

This example request gets information about the Object service.

GET https://api.opendatadsl.com/api/object
Authorization: Bearer {{token}}

Token expiry

The token has a lifetime of around an hour, which means if you are running an application and making service requests which go beyond the token expiry time, you will need to request a new token.