Skip to content

Latest commit

 

History

History
188 lines (141 loc) · 10.1 KB

WebApiSetup.md

File metadata and controls

188 lines (141 loc) · 10.1 KB
Raw

WebAPI Setup

WebAPI is used by GMM UI and other GMM Durable Functions to get information about the groups that are managed by GMM as well as their respective job definition.

Create the WebAPI application and populate prereqs keyvault

The following PowerShell script will create a new application, <solutionAbbreviation>-webapi-<environmentAbbreviation> and will also save these settings in the prereqs keyvault:

  • webApiClientId
  • webApiTenantId
  • webApiClientSecret
  • webApiCertificateName

Note that this script will create an new application and authentication will be done using a client id and client secret pair. If you prefer to use a certificate you need to provide the name of your certificate which must be present on your prereqs keyvault.

From your PowerShell 7.x command prompt navigate to the Service\GroupMembershipManagement\Hosts\WebApi\Scripts\ folder of your Public repo and run these commands:

1.    . ./Set-WebApiAzureADApplication.ps1
2.    Set-WebApiAzureADApplication	-SubscriptionName "<subscription-name>" `
                                    -SolutionAbbreviation "<solution-abbreviation>" `
                                    -EnvironmentAbbreviation "<environment-abbreviation>" `
                                    -TenantId "<tenant-id>" `
                                    -Clean $false `
                                    -Verbose

Follow the instructions on the screen.

Note: TenantId - This is the tenant where your GMM resources are located, i.e. keyvaults, storage account. DevTenantId - If the application is going to be installed in a different tenant, set that tenant id here. This is an optional parameter, if not provided TenantId value is used by default.

Roles as policy to gate functionality

In order to control access to the WebAPI, several roles are created when the WebAPI application is created by the script above.

The roles are:

  • Job Creator

    • Users with this role can view and have access to Membership Management page.
    • They can view onboarded destinations for groups they own.
    • They can submit onboarding requests for groups they own.

  • Job Tenant Reader

    • Users with this role can read or view all destinations in the tenant, whether they own the destinations being synced or not.

  • Job Tenant Writer

    • Users with this role can update all destinations in the tenant, whether they own the destinations being synced or not.
    • They can submit onboarding requests for groups, whether they own them or not.

  • Submission Reviewer

    • View Submission Requests for all groups​.
    • Approve/decline Submission requests​.
    • View user information from custom source.
    • Note: for Submission Reviewers to be able to see all pending requests, they need to also have the Job Tenant Reader role

  • Hyperlink Administrator

    • Users with this role can add, update, and remove custom urls from the Admin Settings page.

  • Custom Membership Provider Administrator

    • Users with this role can add, update, and remove custom field names from the Admin Settings page.

Add a role to a group

Login and follow these steps in the tenant that was set in "AppTenantId" to run the Set-WebApiAzureADApplication.ps1 script in the previous step.

  1. From the Azure Portal locate and open "Microsoft Entra ID"
  2. On the left menu select "Enterprise Applications"
  3. Search for the webapi application, the name follows this convention <solutionAbbreviation>-webapi-<environmentAbbreviation> i.e. gmm-webapi-int. You might need to change the "Application Type" filter to "All Applications".
  4. Click on the name of your application.
  5. On the left menu select "Users and groups".
  6. Click on "Add user/group"
  7. Under "Users and groups", click on "None selected" and search for the group created in the previous step and select it.
  8. Under "Select a role" click on "None selected", from the roles list select the appropriate role for this group (or individual user).
  9. Click "Assign"

Note: Individual users can be added and granted the proper permission, if you decide not to use a group.

Add trusted client applications

The WebpAPI will be called by the GMM UI. In order to allow it to call the WebAPI, it needs to be added as trusted client application.

Create UI application by following UI\Documentation\UISetup.md.

  1. From the Azure Portal locate and open "Microsoft Entra ID"
  2. On the left menu select "App Registrations"
  3. Search for the webapi application, the name follows this convention <solutionAbbreviation>-webapi-<environmentAbbreviation> i.e. gmm-webapi-int.
  4. Click on the name of your application.
  5. On the left menu select "Expose an API".
  6. Click on "Add a client application"
  7. Provide the Application/Client ID of your GMM UI application, the name follows this convention <solutionAbbreviation>-ui-<environmentAbbreviation> i.e. gmm-ui-int. Make sure to select the Authorized scope.
  8. Click "Add application"

Add the WebAPI application to the GMM UI as API Permission

  1. From the Azure Portal locate and open "Microsoft Entra ID"
  2. On the left menu select "App Registrations"
  3. Search for the ui application, the name follows this convention <solutionAbbreviation>-ui-<environmentAbbreviation> i.e. gmm-ui-int.
  4. Click on the name of your application.
  5. On the left menu select "API Permissions".
  6. Click on "Add a permission"
  7. Click on "APIs my organization uses" and type the WebAPI Application ID
  8. Select the WebAPI application and click on "Delegated permissions"
  9. Check "user_impersonation" on and click "Add permissions"
  10. Click "Grant admin consent for "

The following steps need to be completed after a successful deployment

Grant Permissions

This step needs to be completed after all the resources have been deployed to your Azure tenant.

See Post-Deployment tasks

Running the script mentioned in the Post-Deployment tasks section will grant the WebAPI system identity access to the resources it needs.

To properly setup the WebAPI you will need to configure the parameters in the WebApi/Infrastructure/compute/parameters for your environment. If you have a custom domain, follow the instructions here. If not, skip on to the instructions here.

Grant access to the SQL Server Database

WebAPI will access the database using its system identity to authenticate with the database to prevent the use of credentials.

Once the WebAPI is deployed (<SolutionAbbreviation>-compute-<EnvironmentAbbreviation>-webapi)and has been created we need to grant it access to the SQL Server DB.

Server name follows this naming convention <SolutionAbbreviation>-data-<EnvironmentAbbreviation> and <SolutionAbbreviation>-data-<EnvironmentAbbreviation>-r for the replica server. Database name follows this naming convention <SolutionAbbreviation>-data-<EnvironmentAbbreviation> and <SolutionAbbreviation>-data-<EnvironmentAbbreviation>-r for the replica database.

  1. Connect to your SQL Server Database using Sql Server Management Studio (SSMS) or Azure Data Studio.
  • Server name : <server-name>.database.windows.net
  • User name: Use your Azure account.
  • Authentication: Microsoft Entra ID - Universal with MFA
  • Database name: <database-name>
  1. Run these SQL command
  • This script needs to run only once per database.
  • Make sure you are connected to right database. Sometimes SSMS will default to the master database.
IF NOT EXISTS (SELECT * FROM sys.database_principals WHERE name = N'<SolutionAbbreviation>-compute-<EnvironmentAbbreviation>-webapi')
BEGIN
 CREATE USER [<SolutionAbbreviation>-compute-<EnvironmentAbbreviation>-webapi] FROM EXTERNAL PROVIDER;
 ALTER ROLE db_datareader ADD MEMBER [<SolutionAbbreviation>-compute-<EnvironmentAbbreviation>-webapi];
 ALTER ROLE db_datawriter ADD MEMBER [<SolutionAbbreviation>-compute-<EnvironmentAbbreviation>-webapi];
 ALTER ROLE db_ddladmin ADD MEMBER [<SolutionAbbreviation>-compute-<EnvironmentAbbreviation>-webapi];
END

Verify it ran successufully by running:

SELECT * FROM sys.database_principals WHERE name = N'<SolutionAbbreviation>-compute-<EnvironmentAbbreviation>-webapi'

You should see one record for your webapi app. Repeat the steps for both databases.

Setting up a custom domain

If you have a custom domain ('contoso.com', for example) and want to use it, you will need to upgrade your App Service Plan. You can set the API custom domain in the apiHostname parameter as api.contoso.com. This way, your parameter file will look like this

    {
        "$schema": "https://schema.management.azure.com/schemas/2015-01-01/deploymentParameters.json#",
        "contentVersion": "1.0.0.0",
        "parameters": {
            "apiHostname": {
                "value": "api.contoso.com"
            }
        }
    }

Then, once the deployment finishes, follow these steps:

  1. Go to your App Service resource and select Custom domains.
  2. There, click on + Add custom domain and enter your custom domain details. You can choose to include your own TLS/SSL certificate, or use an App Service Managed Certificate.
  3. Once you have completed and validated the custom domain. Click Add.

Finally, you will need to update your App registration to include this custom domain. To do so, make sure you:

  1. Login and follow these steps in the tenant where the application was created.
  2. From the Azure Portal locate and open "Microsoft Entra ID"
  3. On the left menu, select "App registrations"
  4. Search for the webapi application, the name follows this convention <solutionAbbreviation>-webapi-<environmentAbbreviation> i.e. gmm-webapi-int.
  5. Click on the name of your application.
  6. On the left menu, select "Expose an API"
  7. In the Application ID URI, set your custom domain here. i.e. api://api.contoso.com.

Using the default domain

If you do not wish to set up a custom domain, you can leverage the one included in the F1 service plan, remove the apiHostname parameter file to use the default <solutionAbbreviation>-compute-<solutionAbbreviation>-webapi.azurewebsites.net