Link Search Menu Expand Document
Start for Free

Azure AD with Launchpad

This chapter discusses preparing Azure AD for use with Kubernetes.

Page Contents
  1. Overview
  2. Prerequisites
  3. Setup
    1. Setting up the environment
    2. Registering the Stardog Application
    3. Setting up the application
  4. Permission Scope
    1. Permission Scope Definition
    2. Applying the Permission Scope
  5. Authorized Definition
  6. Groups
    1. Group setup
    2. Group Membership
  7. Getting info required for Stardog Helm Chart

Overview

You can use Azure AD as your identity provider (IdP) when using Stardog Launchpad.

Our goal in this tutorial is to do the following:

  1. Show the commands needed to register Stardog as an application an Azure AD.

  2. Show the commands help to show when automating in a CI/CD pipeline.

This page only covers how to set up Azure AD via the CLI.

Prerequisites

Commands:

Setup

Setting up the environment

Log in to Azure using the instructions found here.

Set the environment variable SUBSCRIPTION to the one you want to work with. You can see available subscriptions with:

az account subscription list

Then you can set it with:

export SUBSCRIPTION=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX

Registering the Stardog Application

You can get your TENANT_ID with the following command:

export AZURE_TENANT_ID=$(az account list | \
jq -r --arg SUBSCRIPTION $SUBSCRIPTION '.[] | select (.id == $SUBSCRIPTION).tenantId)'

This command does the following to set the AZURE_TENANT_ID variable:

  • az account list: Gets a list of all the subscriptions for the logged-in account.
  • jq -r: Processes the output as raw strings. --arg SUBSCRIPTION $SUBSCRIPTION sets a variable inside jq’s environment. '.[] iterates over the entire list of subscriptions returned by az account list.
  • select (...): Uses a filter to extract the tenantId for the subcription whose id matches the id we stored in $SUBSCRIPTION.

Now we’re ready to create the application. For the remainder of this tutorial, we’ll assume the application is called “Stardog Application (dev)”.

export AZURE_STARDOG_APP_ID=$(az ad app create --display-name "Stardog Apps (dev)" --sign-in-audience AzureADMyOrg --web-redirect-uris https://[your company's endpoint]/oauth/azure/redirect --enable-access-token-issuance true --enable-id-token-issuance --query appId --output tsv)

This command does the following to set the AZURE_STARDOG_APP_ID variable:

  • az ad app create: Creates a new application registration in Azure AD.
  • --display-name "Stardog Apps (dev)": This sets the display name, as mentioned above.
  • --sign-in-audience AzureADMyOrg: Specifies the sign-in audience for the application. Intended for users in the same organization as the Azure AD tenant.
  • --web-redirect-uris https://[your company's endpoint]/oauth/azure/redirect: Sets the rediect URI for the application. After a user signs in, Azure AD will redirect them to this URI.
  • --enable-access-token-issuance true: Enables the issuance of access tokens and ID tokens for the application.
  • --query appId: Extracts just the appId value from the full output of the application creation command. The appId is the unique identifier for the application in Azure AD.
  • --output tsv: Specifies the output of the command should be in TSV (Tab-Separated Values) format.

If the application is already registered, you can set AZURE_STARDOG_APP_ID like this:

AZURE_STARDOG_APP_ID=$(az ad app list | jq -r --arg APP_NAME "Stardog Apps (dev)" '.[] | select (.displayName == $APP_NAME).appId')

Setting up the application

Create a service principal for the application like so:

az ad sp create –id $AZURE_STARDOG_APP_ID

Then get the Object ID associated with the application, which will we need to create the scope:

AZURE_STARDOG_OBJECT_ID=$(az ad app show --id $AZURE_STARDOG_APP_ID --query id --output tsv)

Now add the identifierUri:

az rest --method PATCH --uri https://graph.microsoft.com/v1.0/applications/$AZURE_STARDOG_OBJECT_ID  --headers 'Content-Type=application/json' --body "{'identifierUris':[ 'api://$AZURE_STARDOG_APP_ID' ]}"

This command does the following:

  • az rest: Makes a REST API call to Azure services.
  • --method PATCH: Use the PATCH method in the API call. PATCH is used to apply partial modifications to a resource.
  • --uri https://graph.microsoft.com/v1.0/applications/$AZURE_STARDOG_OBJECT_ID: Specifies the URI of the REST API endpoint. It targets the Microsoft Graph API endpoint for modifying an Azure AD application. $AZURE_STARDOG_OBJECT_ID, which we just set, contains the Object ID of the Stardog application.
  • --headers 'Content-Type=application/json': Specifies the Content-Type header as application/json, indicating the request body is in JSON format.
  • --body "{'identifierUris':[ 'api://$AZURE_STARDOG_APP_ID' ]}": This is the request body of the PATCH request. It’s setting identifierUris to include the $AZURE_STARDOG_APP_ID we set earlier.

Permission Scope

Permission Scope Definition

Next we need to prepare a JSON definition file based on the following template:

{ 
	"api": { 
		"oauth2PermissionScopes": [ 
	 
			{
				"adminConsentDescription": "openid",
				"adminConsentDisplayName": "openid",
				"id": "",
				"isEnabled": true,
				"type": "User",
				"userConsentDescription": "openid",
				"userConsentDisplayName": "openid",
				"value": "openid"
			},
			{
				"adminConsentDescription": "Directory.Read.All.",
				"adminConsentDisplayName": "Directory.Read.All",
				"id": "",
				"isEnabled": true,
				"type": "User",
				"userConsentDescription": "Directory.Read.All",
				"userConsentDisplayName": "Directory.Read.All",
				"value": "Directory.Read.All"
			},
			{
				"adminConsentDescription": "profile",
				"adminConsentDisplayName": "profile",
				"id": "",
				"isEnabled": true,
				"type": "User",
				"userConsentDescription": "profile",
				"userConsentDisplayName": "profile",
				"value": "profile"
			},
			{
				"adminConsentDescription": "email",
				"adminConsentDisplayName": "email",
				"id": "",
				"isEnabled": true,
				"type": "User",
				"userConsentDescription": "email",
				"userConsentDisplayName": "email",
				"value": "email"
			}
		]
	}
}

We recommend saving this file as ad_oauth2PermissionScopes.json.

You will need to add values for the following 4 variables:

  • SCOPE_OPEN_ID
  • SCOPE_READ_ALL_ID
  • SCOPE_PROFILE_ID
  • SCOPE_EMAIL_ID

To do this, you can run the uuidgen command 4 times in your shell and copy and paste the values into your definition file.

The above template is Mustache-compatible, so the scope definition process can be easily automated.

Applying the Permission Scope

You can apply your permission scope with:

az rest --method PATCH --uri https://graph.microsoft.com/v1.0/applications/$AZURE_STARDOG_OBJECT_ID --headers 'Content-Type=application/json' --body @/path/to/ad_oauth2PermissionScopes.json

You can check the scope with the following command:

az ad app show --id $AZURE_STARDOG_APP_ID --query api.oauth2PermissionScopes

Authorized Definition

Now we need to add a definition to tell Azure AD the client is authorized. Create a JSON definition file based on the following template:

{ 
	"api": { 
		"preAuthorizedApplications": [
			{
				"appId": "",
				"delegatedPermissionIds": [
					"",
					"",
					"",
					""
				]
			}
		]
	}
}

Replace the variables with the same values used in ad_oauth2PermissionScopes.json. We recommend saving this file as ad_oauth2AuthorizedClient.json.

Then run the following command:

az rest --method PATCH --uri https://graph.microsoft.com/v1.0/applications/$AZURE_STARDOG_OBJECT_ID  --headers 'Content-Type=application/json' --body @/path/to/ad_oauth2AuthorizedClient.json

Groups

Group setup

Now we need to make sure the groups Stardog relies on actually exist. For the purposes of this exercise, we will assume you simply use the defaults, which are:

  • stardog_reader
  • stardog_writer
  • stardog_admin

To check whether they exist, you can run the following command:

az ad group list | jq -r --arg group 'stardog_admin' '.[]| select(.displayName == $group) | .displayName == $group'

(Replace stardog_admin with whichever group you’re testing.)

If this command does not return true, you can create the group with the following command:

az ad group create --display-name stardog_admin --mail-nickname stardog_admin

Group Membership

To get a list of your group members, run:

az ad group member list --group stardog_admin | jq '.[] | .displayName '

To add a member to a group, you need their member ID. You can list your users, find the member to add via their userPrincipleName, and store their ID in a variable called ID:

ID=$(az ad user list | jq -r --arg upn 'person@example.com' '.[] | select(.userPrincipalName == $upn) | .id')

Then add them to the group:

az ad group member add --group stardog_admin --member-id $ID

If you simply want to add yourself, you can use this command to retrieve the current user’s ID:

ID=$(az ad signed-in-user show | jq .id -r)

Getting info required for Stardog Helm Chart

The only thing left is to link Stardog with Azure AD. We will need the following environment variables for our Helm Chart:

  • AZURE_TENANT_ID: Defined above.
  • AZURE_STARDOG_APP_ID: Defined above.
  • AZURE_CLIENT_SECRET: Can be defined as follows:
    AZURE_CLIENT_SECRET=$(az ad app credential reset --id $AZURE_STARDOG_APP_ID --display-name puppy | jq -r '.password')