From e62b606bf299f5d196f99a440d2a063ed29dc035 Mon Sep 17 00:00:00 2001 From: Hayden Roszell Date: Wed, 3 Jul 2024 20:04:06 +0100 Subject: [PATCH] chore(docs): Translate doc structure for compatibility with doctool and upgrade bootstrap workflow --- ...low.yml => keyfactor-release-workflow.yml} | 5 +- README.md | 87 +++++------------ docs/azureapp.md | 52 +++-------- docs/azuresp.md | 52 +++-------- docsource/azureapp.md | 20 +--- docsource/azuresp.md | 17 ---- integration-manifest.json | 93 ++----------------- 7 files changed, 59 insertions(+), 267 deletions(-) rename .github/workflows/{keyfactor-bootstrap-workflow.yml => keyfactor-release-workflow.yml} (78%) diff --git a/.github/workflows/keyfactor-bootstrap-workflow.yml b/.github/workflows/keyfactor-release-workflow.yml similarity index 78% rename from .github/workflows/keyfactor-bootstrap-workflow.yml rename to .github/workflows/keyfactor-release-workflow.yml index 6d8de53..3071ff4 100644 --- a/.github/workflows/keyfactor-bootstrap-workflow.yml +++ b/.github/workflows/keyfactor-release-workflow.yml @@ -1,4 +1,4 @@ -name: Keyfactor Bootstrap Workflow +name: Keyfactor Release Workflow on: workflow_dispatch: @@ -11,9 +11,10 @@ on: jobs: call-starter-workflow: - uses: keyfactor/actions/.github/workflows/starter.yml@v2 + uses: keyfactor/actions/.github/workflows/starter.yml@v3 secrets: token: ${{ secrets.V2BUILDTOKEN}} APPROVE_README_PUSH: ${{ secrets.APPROVE_README_PUSH}} gpg_key: ${{ secrets.KF_GPG_PRIVATE_KEY }} gpg_pass: ${{ secrets.KF_GPG_PASSPHRASE }} + \ No newline at end of file diff --git a/README.md b/README.md index fdb22b2..144a7b6 100644 --- a/README.md +++ b/README.md @@ -1,53 +1,3 @@ - -# Azure App Registration and Enterprise Application Orchestrator - -The Azure App Registration and Enterprise Application Orchestrator extension remotely manages both Azure App Registration/Application certificates and Enterprise Application/Service Principal certificates. - -#### Integration status: Production - Ready for use in production environments. - -## About the Keyfactor Universal Orchestrator Extension - -This repository contains a Universal Orchestrator Extension which is a plugin to the Keyfactor Universal Orchestrator. Within the Keyfactor Platform, Orchestrators are used to manage “certificate stores” — collections of certificates and roots of trust that are found within and used by various applications. - -The Universal Orchestrator is part of the Keyfactor software distribution and is available via the Keyfactor customer portal. For general instructions on installing Extensions, see the “Keyfactor Command Orchestrator Installation and Configuration Guide” section of the Keyfactor documentation. For configuration details of this specific Extension see below in this readme. - -The Universal Orchestrator is the successor to the Windows Orchestrator. This Orchestrator Extension plugin only works with the Universal Orchestrator and does not work with the Windows Orchestrator. - -## Support for Azure App Registration and Enterprise Application Orchestrator - -Azure App Registration and Enterprise Application Orchestrator is supported by Keyfactor for Keyfactor customers. If you have a support issue, please open a support ticket via the Keyfactor Support Portal at https://support.keyfactor.com - -###### To report a problem or suggest a new feature, use the **[Issues](../../issues)** tab. If you want to contribute actual bug fixes or proposed enhancements, use the **[Pull requests](../../pulls)** tab. - ---- - - ---- - - - -## Keyfactor Version Supported - -The minimum version of the Keyfactor Universal Orchestrator Framework needed to run this version of the extension is 10.4 -## Platform Specific Notes - -The Keyfactor Universal Orchestrator may be installed on either Windows or Linux based platforms. The certificate operations supported by a capability may vary based what platform the capability is installed on. The table below indicates what capabilities are supported based on which platform the encompassing Universal Orchestrator is running. -| Operation | Win | Linux | -|-----|-----|------| -|Supports Management Add|✓ |✓ | -|Supports Management Remove|✓ |✓ | -|Supports Create Store| | | -|Supports Discovery|✓ |✓ | -|Supports Reenrollment| | | -|Supports Inventory|✓ |✓ | - - - - - ---- - -

Azure App Registration and Enterprise Application Universal Orchestrator Extension

@@ -86,6 +36,15 @@ The Azure App Registration and Enterprise Application Orchestrator extension rem Certificates used for client authentication by Applications (configured in App Registrations) are represented by the [`AzureApp` store type](docs/azureapp.md), and certificates used for SSO/SAML assertion signing are represented by the [`AzureSP` store type](docs/azuresp.md). Both store types are managed by the same extension. The extension is configured with a single Azure Service Principal that is used to authenticate to the [Microsoft Graph API](https://learn.microsoft.com/en-us/graph/use-the-api). The Azure App Registration and Enterprise Application Orchestrator extension manages certificates for Azure App Registrations (Applications) and Enterprise Applications (Service Principals) differently. +## Compatibility + +This integration is compatible with Keyfactor Universal Orchestrator version 10.4 and later. + +## Support +The Azure App Registration and Enterprise Application Universal Orchestrator extension is supported by Keyfactor for Keyfactor customers. If you have a support issue, please open a support ticket with your Keyfactor representative. If you have a support issue, please open a support ticket via the Keyfactor Support Portal at https://support.keyfactor.com. + +> To report a problem or suggest a new feature, use the **[Issues](../../issues)** tab. If you want to contribute actual bug fixes or proposed enhancements, use the **[Pull requests](../../pulls)** tab. + ## Installation Before installing the Azure App Registration and Enterprise Application Universal Orchestrator extension, it's recommended to install [kfutil](https://github.com/Keyfactor/kfutil). Kfutil is a command-line tool that simplifies the process of creating store types, installing extensions, and instantiating certificate stores in Keyfactor Command. @@ -100,7 +59,7 @@ The Azure App Registration and Enterprise Application Universal Orchestrator ext
Requirements - ### Azure Service Principal (Graph API Authentication) + #### Azure Service Principal (Graph API Authentication) The Azure App Registration and Enterprise Application Orchestrator extension uses an [Azure Service Principal](https://learn.microsoft.com/en-us/entra/identity-platform/app-objects-and-service-principals?tabs=browser) for authentication. Follow [Microsoft's documentation](https://learn.microsoft.com/en-us/entra/identity-platform/howto-create-service-principal-portal) to create a service principal. Currently, Client Secret authentication is supported. The Service Principal must have the following API Permission: - **_Microsoft Graph Application Permissions_**: @@ -110,7 +69,7 @@ The Azure App Registration and Enterprise Application Universal Orchestrator ext Alternatively, the Service Principal can be granted the `Application.ReadWrite.OwnedBy` permission if the Service Principal is only intended to manage its own App Registration/Application. - #### Client Certificate or Client Secret + ##### Client Certificate or Client Secret Beginning in version 3.0.0, the Azure App Registration and Enterprise Application Orchestrator extension supports both [client certificate authentication](https://learn.microsoft.com/en-us/graph/auth-register-app-v2#option-1-add-a-certificate) and [client secret](https://learn.microsoft.com/en-us/graph/auth-register-app-v2#option-2-add-a-client-secret) authentication. @@ -159,9 +118,9 @@ The Azure App Registration and Enterprise Application Universal Orchestrator ext > > You will use `clientcert.[pem|pfx].base64` as the **ClientCertificate** field in the [Certificate Store Configuration](#certificate-store-configuration) section. - ### Azure App Registration (Application) + #### Azure App Registration (Application) - #### Application Certificates + ##### Application Certificates Application certificates are used for client authentication and are typically public key only. No additional configuration in Azure is necessary to manage Application certificates since all App Registrations can contain any number of [Certificates and Secrets](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app#add-credentials). Unless the Discovery job is used, you should collect the Application IDs for each App Registration that contains certificates to be managed. @@ -196,7 +155,10 @@ The Azure App Registration and Enterprise Application Universal Orchestrator ext * **Manually**: Follow the [official Command documentation](https://software.keyfactor.com/Core-OnPrem/Current/Content/InstallingAgents/NetCoreOrchestrator/CustomExtensions.htm?Highlight=extensions) to install the latest [Azure App Registration and Enterprise Application Universal Orchestrator extension](https://github.com/Keyfactor/azure-application-orchestrator/releases/latest). 4. Create new certificate stores in Keyfactor Command for the Sample Universal Orchestrator extension. + * [Azure App Registration (Application)](docs/azureapp.md#certificate-store-configuration) + +
Azure Enterprise Application (Service Principal) @@ -206,7 +168,7 @@ The Azure App Registration and Enterprise Application Universal Orchestrator ext
Requirements - ### Azure Service Principal (Graph API Authentication) + #### Azure Service Principal (Graph API Authentication) The Azure App Registration and Enterprise Application Orchestrator extension uses an [Azure Service Principal](https://learn.microsoft.com/en-us/entra/identity-platform/app-objects-and-service-principals?tabs=browser) for authentication. Follow [Microsoft's documentation](https://learn.microsoft.com/en-us/entra/identity-platform/howto-create-service-principal-portal) to create a service principal. Currently, Client Secret authentication is supported. The Service Principal must have the following API Permission: - **_Microsoft Graph Application Permissions_**: @@ -216,7 +178,7 @@ The Azure App Registration and Enterprise Application Universal Orchestrator ext Alternatively, the Service Principal can be granted the `Application.ReadWrite.OwnedBy` permission if the Service Principal is only intended to manage its own App Registration/Application. - #### Client Certificate or Client Secret + ##### Client Certificate or Client Secret Beginning in version 3.0.0, the Azure App Registration and Enterprise Application Orchestrator extension supports both [client certificate authentication](https://learn.microsoft.com/en-us/graph/auth-register-app-v2#option-1-add-a-certificate) and [client secret](https://learn.microsoft.com/en-us/graph/auth-register-app-v2#option-2-add-a-client-secret) authentication. @@ -265,9 +227,9 @@ The Azure App Registration and Enterprise Application Universal Orchestrator ext > > You will use `clientcert.[pem|pfx].base64` as the **ClientCertificate** field in the [Certificate Store Configuration](#certificate-store-configuration) section. - ### Enterprise Application (Service Principal) + #### Enterprise Application (Service Principal) - #### Service Principal Certificates + ##### Service Principal Certificates Service Principal certificates are typically used for SAML Token signing. Service Principals are created from Enterprise Applications, and will mostly be configured with a variation of Microsoft's [SAML-based single sign-on](https://learn.microsoft.com/en-us/entra/identity/enterprise-apps/add-application-portal) documentation. For more information on the mechanics of the Service Principal certificate management capabilities of this extension, please see the [mechanics](#extension-mechanics) section. @@ -302,7 +264,10 @@ The Azure App Registration and Enterprise Application Universal Orchestrator ext * **Manually**: Follow the [official Command documentation](https://software.keyfactor.com/Core-OnPrem/Current/Content/InstallingAgents/NetCoreOrchestrator/CustomExtensions.htm?Highlight=extensions) to install the latest [Azure App Registration and Enterprise Application Universal Orchestrator extension](https://github.com/Keyfactor/azure-application-orchestrator/releases/latest). 4. Create new certificate stores in Keyfactor Command for the Sample Universal Orchestrator extension. + * [Azure Enterprise Application (Service Principal)](docs/azuresp.md#certificate-store-configuration) + +
@@ -312,8 +277,4 @@ Apache License 2.0, see [LICENSE](LICENSE). ## Related Integrations -See all [Keyfactor Universal Orchestrator extensions](https://github.com/orgs/Keyfactor/repositories?q=orchestrator). - -When creating cert store type manually, that store property names and entry parameter names are case sensitive - - +See all [Keyfactor Universal Orchestrator extensions](https://github.com/orgs/Keyfactor/repositories?q=orchestrator). \ No newline at end of file diff --git a/docs/azureapp.md b/docs/azureapp.md index 9380654..c775b5d 100644 --- a/docs/azureapp.md +++ b/docs/azureapp.md @@ -17,7 +17,7 @@ Azure [App Registration/Application certificates](https://learn.microsoft.com/en ## Requirements -### Azure Service Principal (Graph API Authentication) +#### Azure Service Principal (Graph API Authentication) The Azure App Registration and Enterprise Application Orchestrator extension uses an [Azure Service Principal](https://learn.microsoft.com/en-us/entra/identity-platform/app-objects-and-service-principals?tabs=browser) for authentication. Follow [Microsoft's documentation](https://learn.microsoft.com/en-us/entra/identity-platform/howto-create-service-principal-portal) to create a service principal. Currently, Client Secret authentication is supported. The Service Principal must have the following API Permission: - **_Microsoft Graph Application Permissions_**: @@ -27,7 +27,7 @@ The Azure App Registration and Enterprise Application Orchestrator extension use Alternatively, the Service Principal can be granted the `Application.ReadWrite.OwnedBy` permission if the Service Principal is only intended to manage its own App Registration/Application. -#### Client Certificate or Client Secret +##### Client Certificate or Client Secret Beginning in version 3.0.0, the Azure App Registration and Enterprise Application Orchestrator extension supports both [client certificate authentication](https://learn.microsoft.com/en-us/graph/auth-register-app-v2#option-1-add-a-certificate) and [client secret](https://learn.microsoft.com/en-us/graph/auth-register-app-v2#option-2-add-a-client-secret) authentication. @@ -76,34 +76,14 @@ Beginning in version 3.0.0, the Azure App Registration and Enterprise Applicatio > > You will use `clientcert.[pem|pfx].base64` as the **ClientCertificate** field in the [Certificate Store Configuration](#certificate-store-configuration) section. -### Azure App Registration (Application) +#### Azure App Registration (Application) -#### Application Certificates +##### Application Certificates Application certificates are used for client authentication and are typically public key only. No additional configuration in Azure is necessary to manage Application certificates since all App Registrations can contain any number of [Certificates and Secrets](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app#add-credentials). Unless the Discovery job is used, you should collect the Application IDs for each App Registration that contains certificates to be managed. -## Extension Mechanics - -The Azure App Registration and Enterprise Application Orchestrator extension uses the [Microsoft Dotnet Graph SDK](https://learn.microsoft.com/en-us/graph/sdks/sdks-overview) to interact with the Microsoft Graph API. The extension uses the following Graph API endpoints to manage Application certificates: - -* [Get Application](https://learn.microsoft.com/en-us/graph/api/application-get?view=graph-rest-1.0&tabs=http) - Used to obtain the Object ID of the App Registration, and to download the certificates owned by the App Registration. -* [Update Application](https://learn.microsoft.com/en-us/graph/api/application-update?view=graph-rest-1.0&tabs=http) - Used to modify the App Registration to add or remove certificates. - * Specifically, the extension manipulates the [`keyCredentials` resource](https://learn.microsoft.com/en-us/graph/api/resources/keycredential?view=graph-rest-1.0) of the Application object. - -### Discovery Job - -The Discovery operation discovers all Azure App Registrations that the Service Principal has access to. The discovered App Registrations (specifically, their Application IDs) are reported back to Command and can be easily added as certificate stores from the Locations tab. - -The Discovery operation uses the "Directories to search" field, and accepts input in one of the following formats: -- `*` - If the asterisk symbol `*` is used, the extension will search for all Azure App Registrations that the Service Principal has access to, but only in the tenant that the discovery job was configured for as specified by the "Client Machine" field in the certificate store configuration. -- `,,...` - If a comma-separated list of tenant IDs is used, the extension will search for all Azure App Registrations available in each tenant specified in the list. The tenant IDs should be the GUIDs associated with each tenant, and it's the user's responsibility to ensure that the service principal has access to the specified tenants. - -> The Discovery Job only supports Client Secret authentication. - - - ## Certificate Store Type Configuration The recommended method for creating the `AzureApp` Certificate Store Type is to use [kfutil](https://github.com/Keyfactor/kfutil). After installing, use the following command to create the `` Certificate Store Type: @@ -154,11 +134,6 @@ Custom fields operate at the certificate store level and are used to control how | Name | Display Name | Type | Default Value/Options | Required | Description | | ---- | ------------ | ---- | --------------------- | -------- | ----------- | -| ServerUsername | Server Username | Secret | | | The Application ID of the Service Principal used to authenticate with Microsoft Graph for managing Application/Service Principal certificates. | -| ServerPassword | Server Password | Secret | | | A Client Secret that the extension will use to authenticate with Microsoft Graph for managing Application/Service Principal certificates, OR the password that encrypts the private key in ClientCertificate | -| ClientCertificate | Client Certificate | Secret | | | The client certificate used to authenticate with Microsoft Graph for managing Application/Service Principal certificates. See the [requirements](#client-certificate-or-client-secret) for more information. | -| AzureCloud | Azure Global Cloud Authority Host | MultipleChoice | public,china,germany,government | | Specifies the Azure Cloud instance used by the organization. | -| ServerUseSsl | Use SSL | Bool | true | ✅ | Specifies whether SSL should be used for communication with the server. Set to 'true' to enable SSL, and 'false' to disable it. | The Custom Fields tab should look like this: @@ -175,18 +150,13 @@ After creating the `AzureApp` Certificate Store Type and installing the Azure Ap The following table describes the required and optional fields for the `AzureApp` certificate store type. -| Attribute | Description | -| --------- | ----------- | -| Category | Select "Azure App Registration (Application)" or the customized certificate store name from the previous step. | -| Container | Optional container to associate certificate store with. | -| Client Machine | The Azure Tenant (directory) ID that owns the Service Principal. | -| Store Path | The Application ID of the target Application/Service Principal that will be managed by the Azure App Registration and Enterprise Application Orchestrator extension. | -| Orchestrator | Select an approved orchestrator capable of managing `AzureApp` certificates. Specifically, one with the `AzureApp` capability. | -| ServerUsername | The Application ID of the Service Principal used to authenticate with Microsoft Graph for managing Application/Service Principal certificates. | -| ServerPassword | A Client Secret that the extension will use to authenticate with Microsoft Graph for managing Application/Service Principal certificates, OR the password that encrypts the private key in ClientCertificate | -| ClientCertificate | The client certificate used to authenticate with Microsoft Graph for managing Application/Service Principal certificates. See the [requirements](#client-certificate-or-client-secret) for more information. | -| AzureCloud | Specifies the Azure Cloud instance used by the organization. | -| ServerUseSsl | Specifies whether SSL should be used for communication with the server. Set to 'true' to enable SSL, and 'false' to disable it. | +| Attribute | Description | Attribute is PAM Eligible | +| --------- | ----------- | ------------------------- | +| Category | Select "Azure App Registration (Application)" or the customized certificate store name from the previous step. | | +| Container | Optional container to associate certificate store with. | | +| Client Machine | The Azure Tenant (directory) ID that owns the Service Principal. | | +| Store Path | The Application ID of the target Application/Service Principal that will be managed by the Azure App Registration and Enterprise Application Orchestrator extension. | | +| Orchestrator | Select an approved orchestrator capable of managing `AzureApp` certificates. Specifically, one with the `AzureApp` capability. | | * **Using kfutil** diff --git a/docs/azuresp.md b/docs/azuresp.md index 5335d60..8f61d11 100644 --- a/docs/azuresp.md +++ b/docs/azuresp.md @@ -17,7 +17,7 @@ The Azure Enterprise Application/Service Principal certificate operations are im ## Requirements -### Azure Service Principal (Graph API Authentication) +#### Azure Service Principal (Graph API Authentication) The Azure App Registration and Enterprise Application Orchestrator extension uses an [Azure Service Principal](https://learn.microsoft.com/en-us/entra/identity-platform/app-objects-and-service-principals?tabs=browser) for authentication. Follow [Microsoft's documentation](https://learn.microsoft.com/en-us/entra/identity-platform/howto-create-service-principal-portal) to create a service principal. Currently, Client Secret authentication is supported. The Service Principal must have the following API Permission: - **_Microsoft Graph Application Permissions_**: @@ -27,7 +27,7 @@ The Azure App Registration and Enterprise Application Orchestrator extension use Alternatively, the Service Principal can be granted the `Application.ReadWrite.OwnedBy` permission if the Service Principal is only intended to manage its own App Registration/Application. -#### Client Certificate or Client Secret +##### Client Certificate or Client Secret Beginning in version 3.0.0, the Azure App Registration and Enterprise Application Orchestrator extension supports both [client certificate authentication](https://learn.microsoft.com/en-us/graph/auth-register-app-v2#option-1-add-a-certificate) and [client secret](https://learn.microsoft.com/en-us/graph/auth-register-app-v2#option-2-add-a-client-secret) authentication. @@ -76,34 +76,14 @@ Beginning in version 3.0.0, the Azure App Registration and Enterprise Applicatio > > You will use `clientcert.[pem|pfx].base64` as the **ClientCertificate** field in the [Certificate Store Configuration](#certificate-store-configuration) section. -### Enterprise Application (Service Principal) +#### Enterprise Application (Service Principal) -#### Service Principal Certificates +##### Service Principal Certificates Service Principal certificates are typically used for SAML Token signing. Service Principals are created from Enterprise Applications, and will mostly be configured with a variation of Microsoft's [SAML-based single sign-on](https://learn.microsoft.com/en-us/entra/identity/enterprise-apps/add-application-portal) documentation. For more information on the mechanics of the Service Principal certificate management capabilities of this extension, please see the [mechanics](#extension-mechanics) section. -## Extension Mechanics - -The Azure App Registration and Enterprise Application Orchestrator extension uses the [Microsoft Dotnet Graph SDK](https://learn.microsoft.com/en-us/graph/sdks/sdks-overview) to interact with the Microsoft Graph API. The extension uses the following Graph API endpoints to manage Service Principal certificates: - -* [Get Service Principal](https://learn.microsoft.com/en-us/graph/api/serviceprincipal-get?view=graph-rest-1.0&tabs=http) - Used to obtain the Object ID of the Enterprise Application, and to download the certificates owned by the Service Principal. -* [Update Service Principal](https://learn.microsoft.com/en-us/graph/api/serviceprincipal-update?view=graph-rest-1.0&tabs=http) - Used to modify the Enterprise Application to add or remove certificates. - * Specifically, the extension manipulates the [`keyCredentials` resource](https://learn.microsoft.com/en-us/graph/api/resources/keycredential?view=graph-rest-1.0) of the Service Principal object. - -### Discovery Job - -The Discovery operation discovers all Azure Enterprise Applications that the Service Principal has access to. The discovered Enterprise Applications (specifically, their Application IDs) are reported back to Command and can be easily added as certificate stores from the Locations tab. - -The Discovery operation uses the "Directories to search" field, and accepts input in one of the following formats: -- `*` - If the asterisk symbol `*` is used, the extension will search for all Azure Enterprise Applications that the Service Principal has access to, but only in the tenant that the discovery job was configured for as specified by the "Client Machine" field in the certificate store configuration. -- `,,...` - If a comma-separated list of tenant IDs is used, the extension will search for all Azure Enterprise Applications available in each tenant specified in the list. The tenant IDs should be the GUIDs associated with each tenant, and it's the user's responsibility to ensure that the service principal has access to the specified tenants. - -> The Discovery Job only supports Client Secret authentication. - - - ## Certificate Store Type Configuration The recommended method for creating the `AzureSP` Certificate Store Type is to use [kfutil](https://github.com/Keyfactor/kfutil). After installing, use the following command to create the `` Certificate Store Type: @@ -154,11 +134,6 @@ Custom fields operate at the certificate store level and are used to control how | Name | Display Name | Type | Default Value/Options | Required | Description | | ---- | ------------ | ---- | --------------------- | -------- | ----------- | -| ServerUsername | Server Username | Secret | | | The Application ID of the Service Principal used to authenticate with Microsoft Graph for managing Application/Service Principal certificates. | -| ServerPassword | Server Password | Secret | | | A Client Secret that the extension will use to authenticate with Microsoft Graph for managing Application/Service Principal certificates, OR the password that encrypts the private key in ClientCertificate | -| ClientCertificate | Client Certificate | Secret | | | The client certificate used to authenticate with Microsoft Graph for managing Application/Service Principal certificates. See the [requirements](#client-certificate-or-client-secret) for more information. | -| AzureCloud | Azure Global Cloud Authority Host | MultipleChoice | public,china,germany,government | | Specifies the Azure Cloud instance used by the organization. | -| ServerUseSsl | Use SSL | Bool | true | ✅ | Specifies whether SSL should be used for communication with the server. Set to 'true' to enable SSL, and 'false' to disable it. | The Custom Fields tab should look like this: @@ -175,18 +150,13 @@ After creating the `AzureSP` Certificate Store Type and installing the Azure App The following table describes the required and optional fields for the `AzureSP` certificate store type. -| Attribute | Description | -| --------- | ----------- | -| Category | Select "Azure Enterprise Application (Service Principal)" or the customized certificate store name from the previous step. | -| Container | Optional container to associate certificate store with. | -| Client Machine | The Azure Tenant (directory) ID that owns the Service Principal. | -| Store Path | The Application ID of the target Application/Service Principal that will be managed by the Azure App Registration and Enterprise Application Orchestrator extension. | -| Orchestrator | Select an approved orchestrator capable of managing `AzureSP` certificates. Specifically, one with the `AzureSP` capability. | -| ServerUsername | The Application ID of the Service Principal used to authenticate with Microsoft Graph for managing Application/Service Principal certificates. | -| ServerPassword | A Client Secret that the extension will use to authenticate with Microsoft Graph for managing Application/Service Principal certificates, OR the password that encrypts the private key in ClientCertificate | -| ClientCertificate | The client certificate used to authenticate with Microsoft Graph for managing Application/Service Principal certificates. See the [requirements](#client-certificate-or-client-secret) for more information. | -| AzureCloud | Specifies the Azure Cloud instance used by the organization. | -| ServerUseSsl | Specifies whether SSL should be used for communication with the server. Set to 'true' to enable SSL, and 'false' to disable it. | +| Attribute | Description | Attribute is PAM Eligible | +| --------- | ----------- | ------------------------- | +| Category | Select "Azure Enterprise Application (Service Principal)" or the customized certificate store name from the previous step. | | +| Container | Optional container to associate certificate store with. | | +| Client Machine | The Azure Tenant (directory) ID that owns the Service Principal. | | +| Store Path | The Application ID of the target Application/Service Principal that will be managed by the Azure App Registration and Enterprise Application Orchestrator extension. | | +| Orchestrator | Select an approved orchestrator capable of managing `AzureSP` certificates. Specifically, one with the `AzureSP` capability. | | * **Using kfutil** diff --git a/docsource/azureapp.md b/docsource/azureapp.md index 457bb74..c0d0015 100644 --- a/docsource/azureapp.md +++ b/docsource/azureapp.md @@ -61,8 +61,7 @@ Beginning in version 3.0.0, the Azure App Registration and Enterprise Applicatio > ``` > 7. Follow [Microsoft's documentation](https://learn.microsoft.com/en-us/graph/auth-register-app-v2#option-1-add-a-certificate) to add the public key certificate to the service principal used for authentication. > -> You will use `clientcert.[pem|pfx].base64` as the **ClientCertificate** field in the [Certificate Store Configuration](#certificate-store-configuration) section. - +> You will use `clientcert.[pem|pfx].base64` as the **ClientCertificate** field in the [Certificate Store Configuration](#certificate-store-configuration) section. ### Azure App Registration (Application) @@ -70,20 +69,3 @@ Beginning in version 3.0.0, the Azure App Registration and Enterprise Applicatio Application certificates are used for client authentication and are typically public key only. No additional configuration in Azure is necessary to manage Application certificates since all App Registrations can contain any number of [Certificates and Secrets](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app#add-credentials). Unless the Discovery job is used, you should collect the Application IDs for each App Registration that contains certificates to be managed. -# Extension Mechanics - -The Azure App Registration and Enterprise Application Orchestrator extension uses the [Microsoft Dotnet Graph SDK](https://learn.microsoft.com/en-us/graph/sdks/sdks-overview) to interact with the Microsoft Graph API. The extension uses the following Graph API endpoints to manage Application certificates: - -* [Get Application](https://learn.microsoft.com/en-us/graph/api/application-get?view=graph-rest-1.0&tabs=http) - Used to obtain the Object ID of the App Registration, and to download the certificates owned by the App Registration. -* [Update Application](https://learn.microsoft.com/en-us/graph/api/application-update?view=graph-rest-1.0&tabs=http) - Used to modify the App Registration to add or remove certificates. - * Specifically, the extension manipulates the [`keyCredentials` resource](https://learn.microsoft.com/en-us/graph/api/resources/keycredential?view=graph-rest-1.0) of the Application object. - -### Discovery Job - -The Discovery operation discovers all Azure App Registrations that the Service Principal has access to. The discovered App Registrations (specifically, their Application IDs) are reported back to Command and can be easily added as certificate stores from the Locations tab. - -The Discovery operation uses the "Directories to search" field, and accepts input in one of the following formats: -- `*` - If the asterisk symbol `*` is used, the extension will search for all Azure App Registrations that the Service Principal has access to, but only in the tenant that the discovery job was configured for as specified by the "Client Machine" field in the certificate store configuration. -- `,,...` - If a comma-separated list of tenant IDs is used, the extension will search for all Azure App Registrations available in each tenant specified in the list. The tenant IDs should be the GUIDs associated with each tenant, and it's the user's responsibility to ensure that the service principal has access to the specified tenants. - -> The Discovery Job only supports Client Secret authentication. diff --git a/docsource/azuresp.md b/docsource/azuresp.md index 864b84a..7b961da 100644 --- a/docsource/azuresp.md +++ b/docsource/azuresp.md @@ -69,20 +69,3 @@ Beginning in version 3.0.0, the Azure App Registration and Enterprise Applicatio Service Principal certificates are typically used for SAML Token signing. Service Principals are created from Enterprise Applications, and will mostly be configured with a variation of Microsoft's [SAML-based single sign-on](https://learn.microsoft.com/en-us/entra/identity/enterprise-apps/add-application-portal) documentation. For more information on the mechanics of the Service Principal certificate management capabilities of this extension, please see the [mechanics](#extension-mechanics) section. -# Extension Mechanics - -The Azure App Registration and Enterprise Application Orchestrator extension uses the [Microsoft Dotnet Graph SDK](https://learn.microsoft.com/en-us/graph/sdks/sdks-overview) to interact with the Microsoft Graph API. The extension uses the following Graph API endpoints to manage Service Principal certificates: - -* [Get Service Principal](https://learn.microsoft.com/en-us/graph/api/serviceprincipal-get?view=graph-rest-1.0&tabs=http) - Used to obtain the Object ID of the Enterprise Application, and to download the certificates owned by the Service Principal. -* [Update Service Principal](https://learn.microsoft.com/en-us/graph/api/serviceprincipal-update?view=graph-rest-1.0&tabs=http) - Used to modify the Enterprise Application to add or remove certificates. - * Specifically, the extension manipulates the [`keyCredentials` resource](https://learn.microsoft.com/en-us/graph/api/resources/keycredential?view=graph-rest-1.0) of the Service Principal object. - -### Discovery Job - -The Discovery operation discovers all Azure Enterprise Applications that the Service Principal has access to. The discovered Enterprise Applications (specifically, their Application IDs) are reported back to Command and can be easily added as certificate stores from the Locations tab. - -The Discovery operation uses the "Directories to search" field, and accepts input in one of the following formats: -- `*` - If the asterisk symbol `*` is used, the extension will search for all Azure Enterprise Applications that the Service Principal has access to, but only in the tenant that the discovery job was configured for as specified by the "Client Machine" field in the certificate store configuration. -- `,,...` - If a comma-separated list of tenant IDs is used, the extension will search for all Azure Enterprise Applications available in each tenant specified in the list. The tenant IDs should be the GUIDs associated with each tenant, and it's the user's responsibility to ensure that the service principal has access to the specified tenants. - -> The Discovery Job only supports Client Secret authentication. diff --git a/integration-manifest.json b/integration-manifest.json index 7c7f817..a008eb0 100644 --- a/integration-manifest.json +++ b/integration-manifest.json @@ -1,5 +1,5 @@ { - "$schema": "https://keyfactor.github.io/integration-manifest-schema.json", + "$schema": "/Users/hroszell/coding/dev/staff-tools/keyfactor.github.io/v2/integration-manifest-schema.json", "name": "Azure App Registration and Enterprise Application Orchestrator", "integration_type": "orchestrator", "status": "production", @@ -43,45 +43,7 @@ "Discovery": true, "Inventory": true }, - "Properties": [ - { - "Name": "ServerUsername", - "DisplayName": "Server Username", - "Type": "Secret", - "Description": "The Application ID of the Service Principal used to authenticate with Microsoft Graph for managing Application/Service Principal certificates.", - "Required": false - }, - { - "Name": "ServerPassword", - "DisplayName": "Server Password", - "Type": "Secret", - "Description": "A Client Secret that the extension will use to authenticate with Microsoft Graph for managing Application/Service Principal certificates, OR the password that encrypts the private key in ClientCertificate", - "Required": false - }, - { - "Name": "ClientCertificate", - "DisplayName": "Client Certificate", - "Type": "Secret", - "Description": "The client certificate used to authenticate with Microsoft Graph for managing Application/Service Principal certificates. See the [requirements](#client-certificate-or-client-secret) for more information.", - "Required": false - }, - { - "Name": "AzureCloud", - "DisplayName": "Azure Global Cloud Authority Host", - "Type": "MultipleChoice", - "DefaultValue": "public,china,germany,government", - "Description": "Specifies the Azure Cloud instance used by the organization.", - "Required": false - }, - { - "Name": "ServerUseSsl", - "DisplayName": "Use SSL", - "Type": "Bool", - "DefaultValue": "true", - "Description": "Specifies whether SSL should be used for communication with the server. Set to 'true' to enable SSL, and 'false' to disable it.", - "Required": true - } - ], + "Properties": [], "PasswordOptions": { "EntrySupported": false, "StoreRequired": false, @@ -91,7 +53,8 @@ "ServerRequired": true, "PowerShell": false, "BlueprintAllowed": false, - "CustomAliasAllowed": "Required" + "CustomAliasAllowed": "Required", + "EntryParameters": [] }, { "Name": "Azure Enterprise Application (Service Principal)", @@ -107,45 +70,7 @@ "Discovery": true, "Inventory": true }, - "Properties": [ - { - "Name": "ServerUsername", - "DisplayName": "Server Username", - "Type": "Secret", - "Description": "The Application ID of the Service Principal used to authenticate with Microsoft Graph for managing Application/Service Principal certificates.", - "Required": false - }, - { - "Name": "ServerPassword", - "DisplayName": "Server Password", - "Type": "Secret", - "Description": "A Client Secret that the extension will use to authenticate with Microsoft Graph for managing Application/Service Principal certificates, OR the password that encrypts the private key in ClientCertificate", - "Required": false - }, - { - "Name": "ClientCertificate", - "DisplayName": "Client Certificate", - "Type": "Secret", - "Description": "The client certificate used to authenticate with Microsoft Graph for managing Application/Service Principal certificates. See the [requirements](#client-certificate-or-client-secret) for more information.", - "Required": false - }, - { - "Name": "AzureCloud", - "DisplayName": "Azure Global Cloud Authority Host", - "Type": "MultipleChoice", - "DefaultValue": "public,china,germany,government", - "Description": "Specifies the Azure Cloud instance used by the organization.", - "Required": false - }, - { - "Name": "ServerUseSsl", - "DisplayName": "Use SSL", - "Type": "Bool", - "DefaultValue": "true", - "Description": "Specifies whether SSL should be used for communication with the server. Set to 'true' to enable SSL, and 'false' to disable it.", - "Required": true - } - ], + "Properties": [], "PasswordOptions": { "EntrySupported": false, "StoreRequired": false, @@ -155,10 +80,10 @@ "ServerRequired": true, "PowerShell": false, "BlueprintAllowed": false, - "CustomAliasAllowed": "Required" + "CustomAliasAllowed": "Required", + "EntryParameters": [] } ] - }, - "pam": {} + } } -} +} \ No newline at end of file