Skip to content

Commit 3ad49e4

Browse files
jaredmooshahabhijeet
jaredmoo
authored and
shahabhijeet
committed
Explained how to create service principal (Azure#3530)
* Explained how to create service principal Also made several other minor formatting edits * Fixed formatting around Service Principal conn str * Updated Nuget instructions
1 parent a71bfac commit 3ad49e4

File tree

1 file changed

+60
-34
lines changed

1 file changed

+60
-34
lines changed

‎documentation/Using-Azure-TestFramework.md

Lines changed: 60 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -22,24 +22,23 @@
2222
3. Get-Help <CommandName> to get help on individual commands.
2323

2424
## 2. Accquring TestFramework
25-
Current Version: [1.4.0-preview](https://www.nuget.org/packages/Microsoft.Rest.ClientRuntime.Azure.TestFramework/1.4.0-preview)
2625

27-
Nuget command to install current version
26+
TestFramework is available on NuGet at https://www.nuget.org/packages/Microsoft.Rest.ClientRuntime.Azure.TestFramework/ .
2827

29-
Install-Package Microsoft.Rest.ClientRuntime.Azure.TestFramework -v 1.4.0-preview -Pre
28+
Instructions to manually download it are available on NuGet. However TestFramework will be downloaded automatically as part of the build process, so manually downloading it should generally be unnecessary.
3029

3130
## 3. Setup prior to Record/Playback of tests
3231
In order to Record/Playback a test, you need to setup a connection string that consists various key/value pairs that provides information to the test environment.
3332

3433
#### 3.1 Environment Variables
34+
3535
> TEST_CSM_ORGID_AUTHENTICATION
3636
37-
> AZURE_TEST_MODE
37+
This is the connection string that determined how to connect to Azure. This includes both your authentiation and the Azure environment to connect to.
3838

39-
e.g.
40-
TEST_CSM_ORGID_AUTHENTICATION=SubscriptionId=<valid SubscriptionId>;ServicePrincipal=<ClientId>;ServicePrincipalSecret=<Client Secret>;AADTenant=<tenantId>;Environment=Prod;BaseUri=https://management.azure.com/;AADAuthEndpoint=https://login.windows.net/;GraphUri=https://graph.windows.net/
39+
> AZURE_TEST_MODE
4140
42-
AZURE_TEST_MODE=Record
41+
This specifies whether test framework will `Record` test sessions or `Playback` previously recorded test sessions.
4342

4443
#### 3.2. Supported Keys in connection string
4544
* ManagementCertificate
@@ -63,24 +62,27 @@ In order to Record/Playback a test, you need to setup a connection string that c
6362
* AADAuthEndpoint
6463
* GraphTokenAudienceUri
6564

66-
#### 3.3. Existing Defaults
67-
Environment.Prod
68-
AADAuthUri = "https://login.microsoftonline.com"
69-
GalleryUri = "https://gallery.azure.com/"
70-
GraphUri = "https://graph.windows.net/"
71-
IbizaPortalUri = "https://portal.azure.com/"
72-
RdfePortalUri = "http://go.microsoft.com/fwlink/?LinkId=254433"
73-
ResourceManagementUri = "https://management.azure.com/"
74-
ServiceManagementUri = "https://management.core.windows.net"
75-
AADTokenAudienceUri = "https://management.core.windows.net"
76-
GraphTokenAudienceUri = "https://graph.windows.net/"
77-
DataLakeStoreServiceUri = "https://azuredatalakestore.net"
78-
DataLakeAnalyticsJobAndCatalogServiceUri = "https://azuredatalakeanalytics.net"
79-
80-
----------
81-
82-
Environment.Dogfood
83-
AADAuthUri = "https://login.windows-ppe.net";
65+
#### 3.3. Environment Defaults
66+
67+
Setting `Environment` in the connection string will result in the following default values:
68+
69+
##### Environment = Prod
70+
71+
AADAuthUri = "https://login.microsoftonline.com"
72+
GalleryUri = "https://gallery.azure.com/"
73+
GraphUri = "https://graph.windows.net/"
74+
IbizaPortalUri = "https://portal.azure.com/"
75+
RdfePortalUri = "http://go.microsoft.com/fwlink/?LinkId=254433"
76+
ResourceManagementUri = "https://management.azure.com/"
77+
ServiceManagementUri = "https://management.core.windows.net"
78+
AADTokenAudienceUri = "https://management.core.windows.net"
79+
GraphTokenAudienceUri = "https://graph.windows.net/"
80+
DataLakeStoreServiceUri = "https://azuredatalakestore.net"
81+
DataLakeAnalyticsJobAndCatalogServiceUri = "https://azuredatalakeanalytics.net"
82+
83+
##### Environment = Dogfood
84+
85+
AADAuthUri = "https://login.windows-ppe.net";
8486
GalleryUri = "https://df.gallery.azure-test.net/";
8587
GraphUri = "https://graph.ppe.windows.net/";
8688
IbizaPortalUri = "http://df.onecloud.azure-test.net";
@@ -92,10 +94,9 @@ In order to Record/Playback a test, you need to setup a connection string that c
9294
DataLakeStoreServiceUri = "https://caboaccountdogfood.net";
9395
DataLakeAnalyticsJobAndCatalogServiceUri = "https://konaaccountdogfood.net";
9496

95-
----------
97+
##### Environment = Next
9698

97-
Environment.Next
98-
AADAuthUri = "https://login.windows-ppe.net"
99+
AADAuthUri = "https://login.windows-ppe.net"
99100
GalleryUri = "https://next.gallery.azure-test.net/"
100101
GraphUri = "https://graph.ppe.windows.net/"
101102
IbizaPortalUri = "http://next.onecloud.azure-test.net"
@@ -107,10 +108,9 @@ In order to Record/Playback a test, you need to setup a connection string that c
107108
DataLakeStoreServiceUri = "https://caboaccountdogfood.net"
108109
DataLakeAnalyticsJobAndCatalogServiceUri = "https://konaaccountdogfood.net"
109110

110-
----------
111+
##### Environment = Current
111112

112-
Environment.Current
113-
AADAuthUri = "https://login.windows-ppe.net"
113+
AADAuthUri = "https://login.windows-ppe.net"
114114
GalleryUri = "https://df.gallery.azure-test.net/"
115115
GraphUri = "https://graph.ppe.windows.net/"
116116
IbizaPortalUri = "http://df.onecloud.azure-test.net"
@@ -123,17 +123,43 @@ In order to Record/Playback a test, you need to setup a connection string that c
123123
DataLakeAnalyticsJoAbndCatalogServiceUri = "https://konaaccountdogfood.net"
124124

125125
## 4. Record/Playback Test
126+
126127
#### Playback Test
127-
1. The default mode is Playback mode, so no setting up of connection string is required.
128+
129+
The default mode is Playback mode, so no setting up of connection string is required.
128130

129131
#### Record Test with Interactive login using OrgId
132+
133+
This is no longer the preferred option because it only works when running on .NET Framework. When running on .NET Core you may get an error like `Interactive Login is supported only in NET45 projects`.
134+
135+
To use this option, set the following environment variable before starting Visual Studio:
136+
130137
TEST_CSM_ORGID_AUTHENTICATION=SubscriptionId={SubId};UserId={orgId};AADTenant={tenantId};Environment={env};HttpRecorderMode=Record;
131138

132139
#### Record Test with ServicePrincipal
140+
141+
This is the preferred option because it works with both .NET Framework and .NET Core.
142+
143+
To create a service principal, follow the [Azure AD guide to create a Application Service Principal](https://docs.microsoft.com/en-us/azure/azure-resource-manager/resource-group-create-service-principal-portal#create-an-active-directory-application). The application type should be `Web app / API` and the sign-on URL value is irrelevant (you can set any value).
144+
145+
After the service principal is created, you will need to give it access to Azure resources. This can be done with the following PowerShell command, with the [Service Principal Application ID](https://docs.microsoft.com/en-us/azure/azure-resource-manager/resource-group-create-service-principal-portal#get-application-id-and-authentication-key) (this is a guid, not the display name of the service principal) substituted in for `{clientId}`.
146+
147+
New-AzureRmRoleAssignment -ServicePrincipalName {clientId} -RoleDefinitionName Contributor
148+
149+
To use this option, set the following environment variable before starting Visual Studio. The following values are substituted into the below connection string:
150+
151+
`clientId`: The [Service Principal Application ID](https://docs.microsoft.com/en-us/azure/azure-resource-manager/resource-group-create-service-principal-portal#get-application-id-and-authentication-key)
152+
153+
`clientSecret`: A [Service Principal Authentication Key](https://docs.microsoft.com/en-us/azure/azure-resource-manager/resource-group-create-service-principal-portal#get-application-id-and-authentication-key)
154+
155+
`tenantId`: The [AAD Tenant ID](https://docs.microsoft.com/en-us/azure/azure-resource-manager/resource-group-create-service-principal-portal#get-tenant-id)
156+
157+
133158
TEST_CSM_ORGID_AUTHENTICATION=SubscriptionId={SubId};ServicePrincipal={clientId};ServicePrincipalSecret={clientSecret};AADTenant={tenantId};Environment={env};HttpRecorderMode=Record;
134159

135-
2. Run the test and make sure that you got a generated .json file that matches the test name in the bin folder under *SessionRecords folder
136-
3. Copy SessionRecords folder inside the test project and add all *.json files in Visual Studio setting "Copy to Output Directory" property to "Copy if newer"
160+
161+
2. Run the test and make sure that you got a generated .json file that matches the test name in the bin folder under *SessionRecords folder
162+
3. Copy SessionRecords folder inside the test project and add all *.json files in Visual Studio setting "Copy to Output Directory" property to "Copy if newer"
137163
4. To assure that the records work fine, delete the connection string (default mode is Playback mode) OR change HttpRecorderMode within the connection string to "Playback"
138164

139165
## 5. Change Test Environment settings at run-time

0 commit comments

Comments
 (0)