diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index ddc7f75..a751d99 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -1,7 +1,38 @@ -# Description +## Purpose -Please add a meaningful description for this change. Ensure the PR has required unit tests. + -## Related issue +* ... -Kindly link any related issues (e.g. Fixes #xyz). \ No newline at end of file +## Does this introduce a breaking change? + + +``` +[ ] Yes +[ ] No +``` + +## Pull Request Type + +What kind of change does this Pull Request introduce? + + +``` +[ ] Bugfix +[ ] Feature +[ ] Code style update (formatting, local variables) +[ ] Refactoring (no functional changes, no api changes) +[ ] Documentation content changes +[ ] Other... Please describe: +``` + +## How to Test + +* Get the code +* Test the code + + + +## Other Information + + \ No newline at end of file diff --git a/README.md b/README.md index 381f152..1394b55 100644 --- a/README.md +++ b/README.md @@ -2,70 +2,15 @@ ![Build status](https://dev.azure.com/partnercenter/sdk/_apis/build/status/partner-center-java-samples-CI) -This console test app provides sample code for all the scenarios supported by the [Partner Center Java SDK](https://github.com/Microsoft/Partner-Center-Java). You can also use it for testing. +This repository contains samples for the Partner Center .NET SDK. -## Getting Started +## Samples List -Before you build the application, update the values in the *SamplesConfigurations.json* file to reflect the Azure AD authentication information you created in [Partner Center authentication](https://docs.microsoft.com/partner-center/develop/partner-center-authentication). Specifically, you should use your integration sandbox account settings during early development or for testing in production. +| Sample Name | Description | +|-------------|-------------| +| [SDK Samples](sdk/README.md) | Console application that demonstrates each scenario the Partner Center Java SDK is capable of performing.| +| [Secure App Model](secure-app-model/README.md) | A set of projects that demonstrate how a Control Panel Vendor (CPV) and a Cloud Solution Provider (CSP) should implement the Secure App Model. | -Under **ScenarioSettings** in the *SamplesConfiguration.json* file, you can set parameters that will be automatically passed into the scenarios that you run. +## Reporting Security Issues -To modify the list of scenarios that are run, comment out lines in **mainScenarios** or in an individual **Get Scenarios** method found in the *Program.java* file. - -## What to Change - -### PartnerServiceSettings - -- PartnerServiceApiEndpoint -- AuthenticationAuthorityEndpoint -- GraphEndpoint -- CommonDomain - -All thees settings are necessary for the sample API calls to properly function. - -### AppAuthentication - -The following settings must be modified, so that each scenario functions as excepted - -- **ApplicationId**: Your Azure Active Directory application identifier, used for authentication -- **ApplicationSecret**: The application secret, associated with the specified Azure AD application -- **Domain**: The Azure Active Directory domain where the Azure AD application was created - -### UserAuthentication - -The following settings must be updated, so that each scenario functions as expected - -- **ApplicationId**: Your Azure Active Directory application identifier, used for authentication -- **Username**: Your Azure Active Directory username with **AdminAgent** privileges -- **Password**: The password associated with the specified Azure Active Directory user. - -Do not change the following configurations - -- RedirectUrl -- ResourceUrl - -### ScenarioSettings - -Do not change the following setting - -- **CustomerDomainSuffix**: The domain suffix used when creating a new customer - -The following settings can be updated, if left blank information will need to be inputted when running a scenario where it is necessary - -- **CustomerIdToDelete**: The ID of the customer used for deletion. -- **DefaultCustomerId**: The customer ID to use in customer-related scenarios. -- **DefaultInvoiceId**: The invoice ID to use in invoice scenarios. -- **PartnerMpnId**: The partner MPN ID to use in indirect partner scenarios. -- **DefaultServiceRequestId**: The service request ID to use in service request scenarios. -- **DefaultSupportTopicId**: The support topic ID to use in service request scenarios. -- **DefaultOfferId**: The offer ID to use in offer scenarios. -- **DefaultOrderId**: The order ID to use in order scenarios. -- **DefaultSubscriptionId**: The subscription ID to use in subscription scenarios. - -Each of the following of settings specify the amount of entries per page when retrieving paged content. These settings can be modified if desired - -- CustomerPageSize -- DefaultOfferPageSize -- InvoicePageSize -- ServiceRequestPageSize -- SubscriptionPageSize \ No newline at end of file +Security issues and bugs should be reported privately, via email, to the Microsoft Security Response Center (MSRC) at [secure@microsoft.com](mailto:secure@microsoft.com). You should receive a response within 24 hours. If for some reason you do not, please follow up via email to ensure we received your original message. Further information, including the [MSRC PGP](https://www.microsoft.com/msrc/pgp-key-msrc) key, can be found in the [Microsoft Security Response Center](https://www.microsoft.com/msrc). \ No newline at end of file diff --git a/sdk/README.md b/sdk/README.md new file mode 100644 index 0000000..19443da --- /dev/null +++ b/sdk/README.md @@ -0,0 +1,82 @@ +# SDK Samples + +## Overview + +Console application that demonstrates each scenario the Partner Center .NET SDK is capable of performing. + +## Getting Started + +Before you build the application, update the values in the *SamplesConfiguration.json* file to reflect the Azure AD authentication information you created in [Partner Center authentication](https://docs.microsoft.com/partner-center/develop/partner-center-authentication). Specifically, you should use your integration sandbox account settings during early development or for testing in production. + +Under **ScenarioSettings** in the *SamplesConfiguration.json* file, you can set parameters that will be automatically passed into the scenarios that you run. + +To modify the list of scenarios that are run, comment out lines in **mainScenarios** or in an individual **Get Scenarios** method found in the *Program.java* file. + +## Prerequisites + +With previous versions of this sample there were configurations for user credentials. Those configurations have been removed, and now you will be prompted to enter the credentials upon execution. This change was made due to the upcoming requirement to use multi-factor authentication (MFA) when access Partner Center and the Partner Center API using app + user authentication. Please note that the approach used by this application to obtain user credentials is just one way this operation can be performed. It is recommended that you review the [Secure App Model](../secure-app-model/README.md) sample for more information. + +### Azure Active Directory + +Perform the following task to correctly configure the Azure AD application for use with this sample project. + +1. Sign in to the [Partner Center](https://partner.microsoft.com/cloud-solution-provider/csp-partner) using credentials that have *Admin Agent* and *Global Admin* privileges +2. Click on _Dashboard_ at the top of the page, then click on the cog icon in the upper right, and then click the _Partner settings_. +3. Add a new native application if one does not exist already. + +## What to Change + +### PartnerServiceSettings + +If you are connecting to one of the sovereign clouds you will need to modify the values below. These values should not be modified if you are connecting to the commercial cloud. + +- PartnerServiceApiEndpoint +- AuthenticationAuthorityEndpoint +- GraphEndpoint + +All thees settings are necessary for the sample API calls to properly function. + +### AppAuthentication + +The following settings must be modified, so that each scenario functions as excepted + +- **ApplicationId**: Your Azure Active Directory application identifier, used for authentication +- **ApplicationSecret**: The application secret, associated with the specified Azure AD application +- **Domain**: The Azure Active Directory domain where the Azure AD application was created + +### UserAuthentication + +The following settings must be updated, so that each scenario functions as expected + +- **ApplicationId**: Your Azure Active Directory application identifier, used for authentication + +Do not change the following configurations + +- RedirectUrl +- ResourceUrl + +### ScenarioSettings + +Do not change the following setting + +- **CustomerDomainSuffix**: The domain suffix used when creating a new customer + +The following settings can be updated, if left blank information will need to be inputted when running a scenario where it is necessary + +- **CustomerIdToDelete**: The ID of the customer used for deletion. +- **DefaultCustomerId**: The customer ID to use in customer-related scenarios. +- **DefaultInvoiceId**: The invoice ID to use in invoice scenarios. +- **PartnerMpnId**: The partner MPN ID to use in indirect partner scenarios. +- **DefaultServiceRequestId**: The service request ID to use in service request scenarios. +- **DefaultSupportTopicId**: The support topic ID to use in service request scenarios. +- **DefaultOfferId**: The offer ID to use in offer scenarios. +- **DefaultOrderId**: The order ID to use in order scenarios. +- **DefaultSubscriptionId**: The subscription ID to use in subscription scenarios. + +Each of the following of settings specify the amount of entries per page when retrieving paged content. These settings can be modified if desired + +- CustomerPageSize +- DefaultOfferPageSize +- InvoicePageSize +- ServiceRequestPageSize +- SubscriptionPageSize \ No newline at end of file diff --git a/secure-app-model/README.md b/secure-app-model/README.md new file mode 100644 index 0000000..8a5b7ff --- /dev/null +++ b/secure-app-model/README.md @@ -0,0 +1,35 @@ +# Secure App Model + +## Overview + +Microsoft is introducing a secure, scalable framework for authenticating Cloud Solution Provider (CSP) and Control Panel Vendors (CPV) using multi-factor authentication (MFA). This new model will elevate security for operations involving the Partner Center API. This will help all parties including Microsoft and partners to protect their infrastructure and customer data from security risk. + +## Scope + +This guide covers the following actors + +* Control Panel Vendor (CPV) - A control panel vendor is an independent software vendor that develops applications for use by Cloud Solution Provider partners to integrate with the Partner Center API. A control panel vendor is not a Cloud Solution Provider partner with direct access to the Partner Center Dashboard or the API. +* Direct and indirect Cloud Solution Provider partners who are using app + user authentication to directly integrate with the Partner Center API. + +To qualify as a CPV, you must on board to Microsoft Partner Center as a control panel vendor first, more information to come. Please note if you are an existing CSP partner who is also a CPV, this prerequisite applies to you, as well. + +## Samples List + +| Sample Name | Description | +|-------------|-------------| +| [Partner Consent](keyvault/partnerconsent/README.md) | Sample web application developed in Java, that demonstrates how a control panel vendor and Cloud Solution Provider partners can obtain the required consent. This process will store the refresh token for the authenticated user in an instance of Azure Key Vault.| + +## Application identity and concepts + +### Multi-tenant applications + +A multi-tenant application is generally a Software as a Service (SaaS) application. You can configure your application to accept sign-ins from any Azure Active Directory (Azure AD) tenants by configuring the application type as multi-tenant on the Azure dashboard. Users in any Azure AD tenant will be able to sign in to your application after consenting to use their account with your application. +Please see [How to sign in any Azure Active Directory user using the multi-tenant application pattern](https://docs.microsoft.com/azure/active-directory/develop/howto-convert-app-to-be-multi-tenant) for more information + +### Consent framework + +For a user to sign in to an application in Azure AD, the application must be represented in the user’s tenant. This allows the organization to do things like apply unique policies when users from their tenant sign in to the application. For a single tenant application, this registration is simple; it’s the one that happens when you register the application in the Azure dashboard. + +For a multi-tenant application, the initial registration for the application lives in the Azure AD tenant used by the developer. When a user from a different tenant signs in to the application for the first time, Azure AD asks them to consent to the permissions requested by the application. If they consent, then a representation of the application called a service principal is created in the user’s tenant, and the sign in process can continue. A delegation is also created in the directory that records the user’s consent to the application. + +Please note that direct and indirect provider partners who are using app + user authentication and directly integrate with the Partner Center API will have to give consent to their marketplace application using the same consent framework. \ No newline at end of file diff --git a/secure-app-model/keyvault/partnerconsent/README.md b/secure-app-model/keyvault/partnerconsent/README.md new file mode 100644 index 0000000..a90708c --- /dev/null +++ b/secure-app-model/keyvault/partnerconsent/README.md @@ -0,0 +1,13 @@ +# Partner Consent + +This is a sample web application developed in Java that utilizes the [authorization code flow](https://docs.microsoft.com/azure/active-directory/develop/v1-protocols-oauth-code) for authentication. Control panel vendors and Cloud Solution Provider partners can leverage this sample to obtain the required consent. Whenever a partner access the web application they will be redirected to Azure AD where they will authenticated using multi-factor authentication (MFA) and provide the required consent. After successfully authenticating and providing consent, the partner will be redirected back to the web application. Finally, the web application will request an access token for use with the Partner Center API. The refresh token returned as part of the token acquisition process will be stored in an instance of Azure Key Vault. This refresh token value is what control panel vendor and Cloud Solution Provider partners will use in their application to request an access to perform operations against the Partner Center API on the partner's behalf. + +## Configurations + +The required configurations for this sample are found in the [web.xml](src/main/webapp/WEB-INF/web.xml). Please update the following values with the corresponding values for your environment. + +* **client_id** - This is the application identifier that represent your application. +* **client_secret** - This is the secret associated with the application that represents your application. +* **keyvault_url** - This the base address for the instance of Azure Key Vault you have deployed (e.g. ). +* **keyvault_cient_id** - This is the application identifier that you have configured to access the instance of Azure Key Vault. +* **keyvault_client_secret** - THis the application secret associated with the application configured to access the instance of Azure Key Vault. \ No newline at end of file