edocstore-azure-installation-guide.md

eDocStore installation guide (Microsoft Azure)

This installation guide contains step by step instructions of how to:

• deploy eDocStore on Microsoft Azure;
• configure deployed eDocStore applications.

Deployment

This section describes step by step instructions of how to deploy eDocStore from Azure Marketplace.

The default eDocStore Azure resource deployment creates Azure resources which do not start to consume Azure credits right after deployment. By default the only non-free resource is CosmosDB, which consumes Azure credits only once it has created and existing collection.

To deploy eDocStore Azure resources:

1. Find the eDocStore in the Marketplace and click on Create.
2. In the Basic step

• choose the Subscription where to deploy the eDocStore resources,
• create a new or use an existing but empty Resource group,
• choose resource group Location,

then click on OK.

3. In the succeeding step

• choose the Pricing Tier for the eDocStore binding App service hosting, by default hosting plan is shared among all API service applications (bindings);
• choose the eDocStore API service applications (bindings) to be deployed, each binding (protocol) has it's own Azure App service instance,

then click on OK.

4. In the Summary step review your settings, then click on OK.
5. In the Buy step review and agree to the Microsoft's terms of use and on Create to initialize eDocStore Azure resource creation. The creation takes 5-10 minutes.

Inital configuration

After a successful deployment eDocStore applications comes with initial security configuration which prohibits unauthorized access to eDocStore applications. To be able to use eDocStore applications after a deployment either security configuration is completed (recommended) or security is disabled.

This section contains step by step instructions of how to configure security for each of eDocStore applications (Administrative Panel, SOAP API service, REST API service):

• setup Azure AD authentications to eDocStore Administrative Panel application;
• setup Azure AD authentications and authorization to Web service and Browser binding services;
• setup Azure AD authentications and authorization to Web service and Browser binding client side applications (contains code samples).

Administrative Panel

This section describes step by step instructions of how to setup eDocStore Administrative Panel Azure Active Directory authentication security in the Azure Portal.

1. In the Azure Portal Azure Active Directory tenant where eDocStore has been deployed in the App Service pane select Administrative Panel app (by default name starts with ‘edocstoremngr..’) click on Authentication / Authorization
   

1.1. verify that ‘App Service Authentication’ is ‘On’;

1.2. verify that ‘Action to take when request is not authenticated’ is ‘Log in with Azure Active Directory’;

1.3. as Authentication Provider choose Azure Active Directory and in the succeeding page select Express, then choose Create New AD Application and click on OK. Then click on Save and wait till Azure AD application is being created.

2. By default all users in specific Azure AD tenant will be able to access the Administrative Panel (after step #3 will be completed). To restrict access to the specific users of Azure AD tenant (recommended) continue with this step; otherwise proceed to the last step (#3).
   In the Azure Active Directory pane click on Enterprise Applications and select Administrative Panel Azure AD App (which was created in the step #1).

   In the succeeding page

   2.1. click on Properties and set ‘User assignment required’ to ‘Yes’ and click on Save. Now only the allowed Azure AD tenant users will be able to access the Administrative Panel;

   2.2. to allow a specific user access to the Administrative Panel click on Users and groups and choose Add user. In the succeeding page select user which you want to be able to access the Administrative Panel and click on Assign.

3. To complete security configuration and allow access to the Administrative Panel to any user (or only allowed users in case if step #2 was completed) in the Azure Active Directory pane click on App Registrations and in the succeeding page select Administrative Panel Azure AD App (which was created in the step #1).
   In the succeeding page click on Settings, then in the succeeding page click on Required Permissions and in the succeeding page click on Grant permissions to allow sign in with Azure AD user credentials.

Web service and Browser bindings

This section contains step by step instructions of how to setup eDocStore Web service and Browser binding service Azure Active Directory authentication and CMIS object Access Control List (ACL) authorization security in the Azure Portal. These instructions applies to both available service bindings and created Azure AD artifacts can be shared among them concurrently.

1. In the Azure Active Directory pane click on App Registrations and choose New application registration.

   1.1. Provide an application name, for example 'edocstore-services', select the ‘Web app / API’ as the Application Type, provide any value in Sign-on URL as it won’t be used in this scenario and click on Create.

   1.2. In the succeeding page click on Manifest and set ACL roles which should be available for granting to Azure AD users from Azure Portal. By convention all eDocStore CMIS objects (except repositories – which can be accessed by any user which can access service) have Access Control Entry for ‘Administrator’ (case-sensitive) role with ‘cmis:all’ permission. Therefore it is required to set ‘Administrator’ role in Azure AD manifest appRole collection to be able to access the root folder of the repository:

   

   AppRoles sample value:

   "appRoles": [
   {
       "allowedMemberTypes": [
         "User"
       ],
       "displayName": "Administrator",
       "id": "6f2a2c46-58ed-4e49-97e8-ba30a6d81d8b",
       "isEnabled": true,
       "description": "global administrator",
       "value": "Administrator"
   },
   ..
   {
       // another role
   }]
   

   You will be able to update the appRole collection as needed, but to start to successfully use eDocStore binding services it is highly recommended to add this ‘Administrator’ role.

   NB! users with ‘Administrator’ role will be able to do anything in any CMIS repository with any CMIS object; this role and it’s permission can not be removed from the CMIS object ACL, therefore this role should be given to as few users as possible. It is highly recommended to create local administrator roles for each CMIS repository individually.

2. In the App Service pane select eDocStore REST/SOAP API service App Service and click on Application settings 2.1. Set ida:IsEnabled property value to ‘true’ (default)
   2.2. Set ida:Tenant property value to Azure AD tenant name, which can be found in Azure Active Directory pane -> Overview page.
   2.3. Set ida:Audience property value to App Id URI of the 'edocstore-services' application (which was created in step #1). App Id URI can be found in Azure Active Directory pane -> App registrations page -> 'edocstore-services' application -> Settings page -> Properties page -> App ID URI.
   2.4. Click on Save.

3. By default all users in specific Azure AD tenant will be able to access the eDocStore binding services (even if they won’t have assigned any roles they will be able to retrieve repository information via GetRepositories, GetRepositoryInfo services). If you want to restrict access to the specific users of Azure AD tenant (recommended) continue with this step; otherwise proceed to the succeeding step.
   In the Azure Active Directory pane click on Enterprise Applications and select 'edocstore-services' application service principal. In the succeeding page
   3.1. Click on Properties and set ‘User assignment required’ to ‘Yes’, then Click on Save.
   Now only the allowed Azure AD tenant users will be able to access the services (including GetRepositories, GetRepositoryInfo services).

   3.2. To allow a user access to the 'edocstore-services’ application click on Users and groups and choose Add user. In the succeeding page select users which should be able to access the services and click on Assign.
   

4. To assign roles to specific users in the Azure Active Directory pane click on Enterprise Applications and select 'edocstore-services' application (which was created in step #1) service principal (i.e. Enterprise Application). In the succeeding page click on Users and groups and choose Add user. In the succeeding page a select user or multiple users to assign specific single role (it is possible to assign multiple roles to the specific user, but for each role assignment the specific user need to be added repeatedly), then select the role and click on Assign.
   
   NB! To be able to Add role, it must be added to the Application Manifest which was described in step #1.2.

Web service and Browser binding clients

This section contains step by step instructions of how to setup eDocStore Web service and Browser binding service client Azure Active Directory authentication and CMIS object Access Control List (ACL) authorization security in the Azure Portal. These instructions applies to both available service bindings and created Azure AD artifacts can be shared among them concurrently.

1. In the Azure Active Directory pane, click on App registrations and choose New application registration.

1.1. Enter a friendly name for the application, for example 'edocStore-client-TEST’ and select 'Native' as the Application Type.

1.2. For the Redirect URI, enter https://<your_tenant_name>/edocStore-client-TEST, replacing <your_tenant_name> with the name of your Azure AD tenant.

1.3. Click on Create to create the application.

2. In the succeeding page, find the Application ID value and copy it somewhere. It will be needed to acquire token from Azure AD.
   

3. Configure Permissions for your application. In the Settings menu, choose the 'Required permissions' section and then, click on Add, then select an API.

In the succeeding page type eDocStore service binding Azure AD application name (e.g. ‘edocstore-services') in the textbox.

Then, click on Select Permissions and select 'Access ... ' (selected Azure Azure AD application name) .

Then, click on Done.

Web service binding client

This section contains code sample of a request to the eDocStore Web Server binding (SOAP) service. The aim of the request in this sample is to retrieve the root folder object for the REP:100001 repository. To successfully execute this request an authorized user should have assigned a role in Azure AD ‘edocstore-services' service principal which have permission to read properties in root folder’s Access Control List (ACL), e.g 'Administrator' role.

NuGet packages:

Microsoft.IdentityModel.Clients.ActiveDirectory v3.19.8

Sample code:

class Program {
	static void Main(string[] args) {            
		ServicePointManager.SecurityProtocol = SecurityProtocolType.Tls12;
		ServiceReference1.ObjectServiceClient client = null;
		try {
			client = new ServiceReference1.ObjectServiceClient();

			// Attach bearer token authorization behavior  
			client.Endpoint.AddAuthorizationEndpointBehavior();

     	    var response = client.getObjectByPathAsync( 
			   repositoryId: "REP:100001",
			   path: "/",
			   includeACL: null,
			   includeAllowableActions: null,
			   includePolicyIds: null,
			   includeRelationships: null,
			   filter: null,
			   renditionFilter: null,
			   extension: null).Result;
				
			client.Close();
		}
		catch (Exception ex) {
			client?.Abort();
		}
	}
}

internal static class AzureAdToken {
	public static string Get() {
		// Azure AD tentant name
		string idaTenant = "contoso.onmicrosoft.com";

		// The base URL of the authorization server 
		// (this is always https://login.microsoftonline.com/{0}).
		string idaAadInstance = "https://login.microsoftonline.com/{0}"; 

		// Azure AD 'edocStore-client-TEST’ ApplicationID
		string idaClientId = "47458125-31f8-489b-9599-245ea26aa065";

		// Azure AD 'edocStore-client-TEST’ Redirect URI
		var idaRedirectUri = new Uri("https://contoso.onmicrosoft.com/edocStore-client-TEST");

		// App Id URI of the 'edocstore-services'
		string idaServiceResourceId = 
			"https://contoso.onmicrosoft.com/ae811c04-48c3-439e-9739-f4224ed43299";

		// The URL of the authorization server
		string idaAuthority = String.Format(CultureInfo.InvariantCulture, idaAadInstance, idaTenant);
		var ctx = new AuthenticationContext(idaAuthority);
		var token = ctx.AcquireTokenAsync(idaServiceResourceId, idaClientId, 
			idaRedirectUri, new PlatformParameters(PromptBehavior.Always)).Result;
			
		return token.AccessToken;
	}
}

internal class AuthorizationHeaderEndpointBehavior : IEndpointBehavior {
	public void ApplyClientBehavior(ServiceEndpoint endpoint, 
		System.ServiceModel.Dispatcher.ClientRuntime clientRuntime) {
		clientRuntime.ClientMessageInspectors.Add(new AuthorizationHeaderMessageInspector(AzureAdToken.Get()));
	}
	public void AddBindingParameters(ServiceEndpoint endpoint, 
		System.ServiceModel.Channels.BindingParameterCollection bindingParameters) {
	}

	public void ApplyDispatchBehavior(ServiceEndpoint endpoint, 
		System.ServiceModel.Dispatcher.EndpointDispatcher endpointDispatcher) {
	}

	public void Validate(ServiceEndpoint endpoint) {
	}
}

internal static class EndpointExtension {
	public static void AddAuthorizationEndpointBehavior(this ServiceEndpoint endpoint) {
		endpoint.EndpointBehaviors.Add(new AuthorizationHeaderEndpointBehavior());
	}
}

internal class AuthorizationHeaderMessageInspector : IClientMessageInspector {
	private readonly string _token;
	public AuthorizationHeaderMessageInspector(string token) {
		_token = string.Concat("Bearer ", string.IsNullOrEmpty(token)
			? AzureAdToken.Get() 
			: token);
	}

	public object BeforeSendRequest(ref System.ServiceModel.Channels.Message request, 
		System.ServiceModel.IClientChannel channel) {
		HttpRequestMessageProperty httpRequestMessage;
		object httpRequestMessageObject;
		if (request.Properties.TryGetValue(HttpRequestMessageProperty.Name,
			out httpRequestMessageObject)) {
			httpRequestMessage = httpRequestMessageObject as HttpRequestMessageProperty;
			if (string.IsNullOrEmpty(httpRequestMessage.Headers["Authorization"])) {
				httpRequestMessage.Headers["Authorization"] = _token;
			}
		}
		else {
			httpRequestMessage = new HttpRequestMessageProperty();
			httpRequestMessage.Headers.Add("Authorization", _token);
			request.Properties.Add(HttpRequestMessageProperty.Name, httpRequestMessage);
		}

		return null;
	}
	
		public void AfterReceiveReply(ref System.ServiceModel.Channels.Message reply, 
			object correlationState) {
	}
}

Browser binding client

This section contains a code sample of a request to the eDocStore Browser binding (RESTful) service. The aim of the request in this sample is to retrieve the root folder object for the REP:100001 repository. To successfully execute this request an authorized user should have assigned a role in Azure AD ‘edocstore-services' service principal which have permission to read properties in root folder’s Access Control List (ACL), e.g 'Administrator' role.

NuGet packages:

Microsoft.IdentityModel.Clients.ActiveDirectory v3.19.8

Sample code:

private async Task GetRootFolder() {
    // Azure AD tentant name
    string idaTenant = "contoso.onmicrosoft.com";
    
    // The base URL of the authorization server 
	// (this is always https://login.microsoftonline.com/{0}).
    string idaAadInstance = "https://login.microsoftonline.com/{0}";

    // Azure AD 'edocStore-client-TEST’ ApplicationID
    string idaClientId = "47458125-31f8-489b-9599-245ea26aa065";       

    // Azure AD 'edocStore-client-TEST’ Redirect URI
    Uri idaRedirectUri = new Uri("https://contoso.onmicrosoft.com/edocStore-client-TEST");
    
    // App Id URI of the 'edocstore-services'
    string IdaServiceResourceId = 
	"https://contoso.onmicrosoft.com/ae811c04-48c3-439e-9739-f4224ed43299";

    // eDocStore base URL to retrieve ROOT folder of the REP:100001 repository.
    string eDocStoreRootFolderAddress = 
	"https://edocstoreresta936c965dda.azurewebsites.net/cmis/REP:100001/root";

    // The URL of the authorization server
    string IdaAuthority = String.Format(CultureInfo.InvariantCulture, idaAadInstance, idaTenant);

    // Get an access token to call the eDocStore CMIS service.
    var authContext = new AuthenticationContext(IdaAuthority);            
	authContext.TokenCache.Clear();

    AuthenticationResult result = null;
    try {
        result = await authContext.AcquireTokenAsync(IdaServiceResourceId, idaClientId, 
			idaRedirectUri, new PlatformParameters(PromptBehavior.Always));
    }
    catch (AdalException ex) {
        // An unexpected error occurred.
        string message = ex.Message;
        if (ex.InnerException != null) {
            message += 
			"Error Code: " + ex.ErrorCode + "Inner Exception : " + ex.InnerException.Message;
        }

        Console.WriteLine(message);
        return;
    }

    // Once the token has been returned by ADAL, 
	// add it to the http authorization header as a bearer token,
	// before making the call to access the eDocStore service.
    httpClient.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer",
		result.AccessToken);

    HttpResponseMessage response = await httpClient.GetAsync(eDocStoreRootFolderAddress);

    if (response.IsSuccessStatusCode) {
        Console.WriteLine("An error occurred : " + response.ReasonPhrase);
    }
 
    string s = await response.Content.ReadAsStringAsync();
    Console.WriteLine("Response : " + s);
}

See also

• Architecture overview
• eDocStore overview
• Samples
• User guide