Skip to content

Latest commit

 

History

History
121 lines (92 loc) · 7.72 KB

enable-authentication.md

File metadata and controls

121 lines (92 loc) · 7.72 KB
Raw

Azure Active Directory Authentication

This How-to-guide shows you how to configure the authentication settings for the FHIR converter service through Azure. This is needed to ensure restricted access to your FHIR converter APIs, allowing only tokens issued from within your tenant to be able to interact with the APIs.

To complete this configuration, you will:

  1. Create a resource application in Azure AD: This resource application will be a representation of the FHIR converter service that can be used to authenticate and obtain tokens. In order for an application to interact with Azure AD, it needs to be registered.
  2. Provide app registration details to your FHIR converter web service: Once the resource application is registered, you will set the authentication configuration of your FHIR converter web service. This ensures that any client that is able to authenticate with the above resource application will be able to access your FHIR converter APIs.
  3. Create a service client application in Azure AD: Client application registrations are Azure AD representations of applications that can be used to authenticate and obtain tokens. A service client is intended to be used by an application to obtain an access token without interactive authentication of a user. It will have certain application permissions and use an application secret (password) when obtaining access tokens.
  4. Retrieve Access Token via Insomnia or Azure CLI: With your service client application enabled, you can obtain an access token to authenticate your application.

Prerequisites

  1. This tutorial requires an Azure AD tenant. If you have not created a tenant, see Create a new tenant in Azure Active Directory.

Authentication Settings Overview

The configurable authentication settings are :

{
  "ConvertService" : {
    "Security": {
      "Enabled":  true,
      "Authentication": {
        "Audience": "",
        "Authority": ""
      }
    }
  }
}
Element Description
Enabled Whether or not the service has any security enabled.
Authentication:Audience Identifies the recipient that the token is intended for.
Authentication:Authority The issuer of the jwt token.

Authentication with Azure AD

Create a Resource Application in Azure AD for your FHIR converter service

  1. Sign into the Azure Portal.
  2. Select Azure Active Directory > App Registrations > New registration:
    1. Enter a Name for your app registration.
    2. To restrict access to APIs to only your tenant, select Accounts in this organizational directory only (tenant name only - Single tenant).
    3. Select Register.
  3. Select Expose an API.
    1. Application ID URI - Add. You can specify a URI or use the generated App ID URI. Select Save.
    2. Select Add a Scope:
      1. In Scope name, enter user_impersonation.
      2. In the text boxes, add an admin consent display name and admin consent description you want users to see on the consent page. For example, access my app.

Set the Authentication configuration of your FHIR converter service

  1. If you have deployed the FHIR converter service to Azure, provide the configuration:

    • If you are using the deployment options to deploy your service, use the following parameters:

      (TODO add instructions for options)

    • Alternatively, you can directly provide the configuration via environment variables in your Azure Container App running the FHIR converter service by editing the container:

      1. ConvertService__Security__Enabled - True
      2. ConvertService__Security__Authentication__Audiences__0 - the Application ID URI created above.
      3. ConvertService__Security__Authentication__Authority - the tenant your application exists in, for example: https://login.microsoftonline.com/<tenant-name>.onmicrosoft.com or https://login.microsoftonline.com/<tenant-id>.

      Refer Configure environment variables for more information.

      convertsecurityconfigaca

Create a Service Client Application

  1. Select Azure Active Directory > App Registrations > New registration:
    1. Enter a Name for your service client. You can provide a URI but it typically will not be used.
    2. Select Register.
  2. Copy the Application (client) ID and the Directory (tenant) ID for later.
  3. Select API Permissions to provide your service client permission to your resource application:
    1. Select Add a permission.
    2. Under My APIs, select the resource application you created above for your FHIR converter service.
    3. Under Select Permissions, select the application roles from the ones that you defined on the resource application.
    4. Select Add permissions.
  4. Select Certificates & secrets to generate a secret for obtaining tokens:
    1. Select New client secret.
    2. Provide a Description and duration of the secret. Select Add.
    3. Copy the secret once it has been created. It will only be displayed once in the portal.

Get Access Token

Using Azure CLI

  1. First, update the application you create above to have access to the Azure CLI:
    1. Select Expose an API > Add a Client Application.
    2. For Client ID, provide the client ID of Azure CLI: 04b07795-8ddb-461a-bbee-02f9e1bf7b46. Note this is available at the Azure CLI Github Repository.
    3. Select your Application ID URI under Authorized Scopes.
    4. Select Add Application.
  2. Install Azure CLI.
  3. Login to Azure: az account
  4. Request access token using the Application ID URI set above: az account get-access-token --resource=<APP-ID-URI>

Using Insomnia

  1. Install Insomnia.
  2. Create a new Post Request or use the OAuth 2 option in the Auth tab for the API request you wish to authenticate with and provide the access token for, with the following form-data:
    1. URL: <Authority>/<tenant-ID>/oauth2/token where Authority is the tenant your application exists in, configured above, and Tenant ID is from your Azure App Registration.
      1. If using Azure Active Directory V2 then instead use URL: <Authority>/<tenant-ID>/oauth2/v2.0/token.
    2. client_id: the Client ID for your Service Client.
    3. grant_type: "client_credentials"
    4. client_secret: the Client secret for your Service Client.
    5. resource: the Application ID URI for your Resource Application.
      1. If using Azure Active Directory V2 then instead of setting resource, set scope: <Application ID URI>/.default where Application ID URI is for your Resource Application.
  3. Select Send (or Fetch Tokens in case you are using the Auth tab in the API request) to retrieve the access token.

Summary

In this How-to Guide, you learned how to configure the authentication settings for the FHIR converter service using AAD as the identity provider.

To get started with your FHIR converter service, refer to the following documents: