diff --git a/AUTH.md b/AUTH.md
new file mode 100644
index 0000000000000..004eafb6617fb
--- /dev/null
+++ b/AUTH.md
@@ -0,0 +1,101 @@
+#Authentication in Azure Management Libraries for Java
+
+To use the APIs in the Azure Management Libraries for Java, as the first step you need to
+create an authenticated client. There are several possible approaches to authentication. This document illustrates a couple of the simpler ones.
+
+## Using an authentication file
+
+> :warning: Note, file-based authentication is an experimental feature that may or may not be available in later releases. The file format it relies on is subject to change as well.
+
+To create an authenticated Azure client:
+
+```java
+Azure azure = Azure.authenticate(new File("my.azureauth")).withDefaultSubscription();
+```
+
+The authentication file, referenced as "my.azureauth" in the example above, uses the Java properties file format and must contain the following information:
+```
+subscription=########-####-####-####-############
+client=########-####-####-####-############
+key=XXXXXXXXXXXXXXXX
+tenant=########-####-####-####-############
+managementURI=https\://management.core.windows.net/
+baseURL=https\://management.azure.com/
+authURL=https\://login.windows.net/
+```
+
+This approach enables unattended authentication for your application (i.e. no interactive user login, no token management needed). The `client`, `key` and `tenant` are from [your service principal registration](#creating-a-service-principal-in-azure). The `subscription` represents the subscription ID you want to use as the default subscription. The remaining URIs and URLs represent the end points for the needed Azure services, and the example above assumes you are using the Azure worldwide cloud.
+
+## Using `ApplicationTokenCredentials`
+
+Similarly to the [file-based approach](#using-an-authentication-file), this method requires a [service principal registration](#creating-a-service-principal-in-azure), but instead of storing the credentials in a local file, the required inputs can be supplied directly via an instance of the `ApplicationTokenCredentials` class:
+
+```
+ServiceClientCredentials credentials = new ApplicationTokenCredentials(client, tenant, key, AzureEnvironment.AZURE);
+Azure azure = Azure.authenticate(credentials).withSubscription(subscriptionId);
+```
+
+where `client`, `tenant`, `key` and `subscriptionId` are strings with the required pieces of information about your service principal and subscription. The last parameter, `AzureEnvironment.AZURE` represents the Azure worldwide public cloud. You can use a different value out of the currently supported alternatives in the `AzureEnvironment` enum.
+
+## Creating a Service Principal in Azure
+
+In order for your application to log into your Azure subscription without requiring the user to log in manually, you can take advantage of credentials based on the Azure Active Directory *service principal* functionality. A service principal is analogous to a user account, but it is intended for applications to authenticate themselves without human intervention.
+
+If you save such service principal-based credentials as a file, or store them in environment variables, this can simplify and speed up your coding process.
+
+>:warning: Note: exercise caution when saving credentials in a file. Anyone that gains access to that file will have the same access privileges to Azure as your application. In general, file-based authentication is not recommended in production scenarios and should only be used as a quick shortcut to getting started in dev/test scenarios.
+
+You can create a service principal and grant it access privileges for a given subscription by following these steps:
+
+1. Log into [your Azure account](http://portal.azure.com).
+1. Select **Browse > Active Directory**.
+
+1. Select the active directory (if you have more than one listed) that you want to register your app in.
+1. Click the **Applications** link.
+1. Click the **Add** button at the bottom of the page.
+
+1. Type in a name for your application. After your app is registered, it will be listed under that name in the Active Directory instance you have selected earlier. You will need to reference that name in a later step.
+1. Select the **Web application and/or web API** option, *regardless* of whether your application is actually going to run on the web or on a desktop computer, and click the arrow to go to the next step.
+
+1. One the next screen, type in some URL in the **Sign-on URL**. If your application is not a web app, it does not matter what you type in here, as long as it is a syntactically correct URL format.
+1. Type in some **App ID URI**. This is just a unique identifier of your choice for your app in the proper URI format that needs to be unique in your selected Active Directory instance.
+1. Click the checkmark when done.
+
+1. Wait for the task to complete. You may see a notification like the following in the meantime:
+
+1. When you see the app dashboard page, click **Configure**.
+
+1. Scroll down the page till you see **Client ID** and **Keys**
+
+1. Create a new blank text file to put your credential information into, and save it as - for example - **"my.azureauth"**
+1. Copy the **client ID** value into your text file, typing "`client=`" in front of it, for example:
+
`client=123456-abcd-1234-abcd-1234567890ab`
+1. In the **Keys** section, select a duration.
+1. Click **Save** at the bottom of the page
+
+1. After a few seconds, you will see the generated key and a prompt for you to save it:
+
+1. Copy the shown key into your text file and prefix it with "`key=`", for example:
+
`key=01234567890123456789abcdef01234567890abcdef0123456789abcdef02345`
+1. In the current URL shown in your browser, select the text between the word: "Directory/" and the next slash (/) and copy it.
+
+1. Paste the copied value into your text file and prefix it with "`tenant=`", for example:
+
`tenant=abcdef01-1234-dcba-9876-abcdef012345`
+
This represents the Active Directory instance you selected earlier.
+1. Assuming you are using the Azure worldwide public cloud, also add the following to your text file: \(Note that this file follows the Java properties file format, so certain characters, such as colons, need to be escaped with a backslash\)
+ `managementURI=https\\://management.core.windows.net/`
+ `baseURL=https\\://management.azure.com/`
+ `authURL=https\\://login.windows.net/`
+ Make sure to escape the colons (:) with backslashes (\\).
+1. You need to grant the created service principal a permission to access the desired Azure subscription. Go to the [Azure portal](http://portal.azure.com) again.
+1. Click **Subscriptions** and select the subscription in the list that you want to enable your application to access.
+
+1. Click **Users**, **Add**
+
+1. In the **Add Access** page, for the **Select a role** question, select **Owner** if you want to give your application the ability to modify resources in this subscription.
+
+1. Click **Add Users**, then find and select your application using the name you provided earlier, and click the **Select** button near the bottom of the page.
+
+
+Now all the pieces are in place to enable authenticating your code without requiring an interactive login nor the need to manage access tokens.
+
diff --git a/README.md b/README.md
index 8d26ae080bda8..5a8d381f5d536 100644
--- a/README.md
+++ b/README.md
@@ -1,15 +1,130 @@
[](https://travis-ci.org/Azure/azure-sdk-for-java)
-#Microsoft Azure SDK for Java
-This project provides a client library in Java that makes it easy to consume Microsoft Azure services. For documentation please see the [JavaDocs](http://azure.github.io/azure-sdk-for-java). For a list of libraries and how they are organized, please see the [Azure SDK for Java Features Wiki page] (https://github.com/Azure/azure-sdk-for-java/wiki/Azure-SDK-for-Java-Features).
+#Azure Management Libraries for Java
-#Download
-**Notes:** If you are using snapshots builds from beta1 we recommend going to http://adxsnapshots.azurewebsites.net/ and find the exact version number. The latest beta1 snapshot versions are
-- client-runtime: 1.0.0-20160513.000825-29
-- azure-client-runtime: 1.0.0-20160513.000812-28
-- azure-client-authentication: 1.0.0-20160513.000802-24
+This README is based on the latest released preview version (1.0.0-beta2). If you are looking for other releases, see [More Information](#more-information)
+
+The Azure Management Libraries for Java is a higher-level, object-oriented API for managing Azure resources.
+
+
+> **1.0.0-beta2** is a developer preview that supports major parts of Azure Compute, Storage, Networking and Resource Manager. The next preview version of the Azure Management Libraries for Java is a work in-progress. We will be adding support for more Azure services and tweaking the API over the next few months.
+
+**Azure Authentication**
+
+The `Azure` class is the simplest entry point for creating and interacting with Azure resources.
+
+`Azure azure = Azure.authenticate(credFile).withDefaultSubscription();`
+
+**Create a Virtual Machine**
+
+You can create a virtual machine instance by using the `define() … create()` method chain.
+
+```java
+System.out.println("Creating a Linux VM");
+
+VirtualMachine linuxVM = azure.virtualMachines().define("myLinuxVM")
+ .withRegion(Region.US_EAST)
+ .withNewResourceGroup("myResourceGroup")
+ .withNewPrimaryNetwork("10.0.0.0/28")
+ .withPrimaryPrivateIpAddressDynamic()
+ .withNewPrimaryPublicIpAddress("mylinuxvmdns")
+ .withPopularLinuxImage(KnownLinuxVirtualMachineImage.UBUNTU_SERVER_16_04_LTS)
+ .withRootUserName("tirekicker")
+ .withSsh(sshKey)
+ .withSize(VirtualMachineSizeTypes.STANDARD_D3_V2)
+ .create();
+```
+
+System.out.println("Created a Linux VM: " + linuxVM.id());
+
+
+**Update a Virtual Machine**
+
+You can update a virtual machine instance by using the `update() … apply()` method chain.
+
+```java
+linuxVM.update()
+ .defineNewDataDisk(dataDiskName)
+ .withSizeInGB(20)
+ .withCaching(CachingTypes.READ_WRITE)
+ .attach()
+ .apply();
+```
+
+**Create a Network Security Group**
+
+You can create a network security group instance by using the `define() … create()` method chain.
+
+```java
+NetworkSecurityGroup frontEndNSG = azure.networkSecurityGroups().define(frontEndNSGName)
+ .withRegion(Region.US_EAST)
+ .withNewResourceGroup(rgName)
+ .defineRule("ALLOW-SSH")
+ .allowInbound()
+ .fromAnyAddress()
+ .fromAnyPort()
+ .toAnyAddress()
+ .toPort(22)
+ .withProtocol(NetworkSecurityRule.Protocol.TCP)
+ .withPriority(100)
+ .withDescription("Allow SSH")
+ .attach()
+ .defineRule("ALLOW-HTTP")
+ .allowInbound()
+ .fromAnyAddress()
+ .fromAnyPort()
+ .toAnyAddress()
+ .toPort(80)
+ .withProtocol(NetworkSecurityRule.Protocol.TCP)
+ .withPriority(101)
+ .withDescription("Allow HTTP")
+ .attach()
+ .create();
+```
+
+
+#Sample Code
+
+You can find plenty of sample code that illustrates management scenarios in Azure Compute, Storage, Network and Resource Manager …
+
+
+
+- [Manage virtual machine](https://github.com/Azure-Samples/compute-java-manage-vm)
+- [Manage availability set](https://github.com/Azure-Samples/compute-java-manage-availability-sets)
+- [List virtual machine images](https://github.com/Azure-Samples/compute-java-list-vm-images)
+- [Manage storage accounts](https://github.com/Azure-Samples/storage-java-manage-storage-accounts)
+- [Manage virtual network](https://github.com/Azure-Samples/network-java-manage-virtual-network)
+- [Manage network interface](https://github.com/Azure-Samples/network-java-manage-network-interface)
+- [Manage network security group](https://github.com/Azure-Samples/network-java-manage-network-security-group)
+- [Manage IP address](https://github.com/Azure-Samples/network-java-manage-ip-address)
+- [Manage resource groups](https://github.com/Azure-Samples/resources-java-manage-resource-group)
+- [Manage resources](https://github.com/Azure-Samples/resources-java-manage-resource)
+- [Deploy resources with ARM templates](https://github.com/Azure-Samples/resources-java-deploy-using-arm-template)
+- Deploy resources with ARM templates (with progress). Link will become available as soon as the sample is ready
+
+# Download
+
+
+**1.0.0-beta2**
+
+If you are using released builds from 1.0.0-beta2, add the following to your POM file:
+
+```xml
+
+ com.microsoft.azure
+ azure
+ 1.0.0-beta2
+
+```
+
+or Gradle:
+
+ compile group: 'com.microsoft.azure', name: 'azure', version: '1.0.0-beta2'
+
+**Snapshots builds for this repo**
+
+If you are using snapshots builds for this repo, add the following repository and dependency to your POM file:
-To compile either this repo, you need snapshot builds in sonatype snapshots repository. Add the following to your pom:
```xml
@@ -24,6 +139,15 @@ To compile either this repo, you need snapshot builds in sonatype snapshots repo
```
+
+```xml
+
+ com.microsoft.azure
+ azure
+ 1.0.0-SNAPSHOT
+
+```
+
or Gradle:
```groovy
repositories {
@@ -32,29 +156,18 @@ repositories {
}
```
-#Getting Started
-You will need Java v1.7+. If you would like to develop on the SDK, you will also need maven.
-## Azure Resource Manager (ARM) Usage
-```java
-ResourceManagementClient client = new ResourceManagementClientImpl(
- new ApplicationTokenCredentials("client-id", "tenant-id", "secret", null) // see Authentication
-);
-client.setSubscriptionId(System.getenv("subscription-id"));
-client.setLogLevel(HttpLoggingInterceptor.Level.BODY);
-
-ResourceGroup group = new ResourceGroup();
-group.setLocation("West US");
-client.getResourceGroups().createOrUpdate("myresourcegroup", group);
-```
+ compile group: 'com.microsoft.azure', name: 'azure', version: '1.0.0-SNAPSHOTS'
+
+#Pre-requisites
-### Authentication
-The first step to using the SDK is authentication and permissioning. For people unfamilar with Azure this may be one of the more difficult concepts. For a reference on setting up a service principal from the command line see [Authenticating a service principal with Azure Resource Manager](http://aka.ms/cli-service-principal) or [Unattended Authentication](http://aka.ms/auth-unattended). For a more robust explanation of authentication in Azure, see [Developer’s guide to auth with Azure Resource Manager API](http://aka.ms/arm-auth-dev-guide).
+- A Java Developer Kit (JDK), v 1.7 or later
+- Maven
+- Azure Service Principal - see [how to create authentication info](./AUTH.md).
-After creating the service principal, you should have three pieces of information, a client id (GUID), client secret (string) and tenant id (GUID) or domain name (string). By feeding them into the `ApplicationTokenCredentials` and initialize the ARM client with it, you should be ready to go.
-## Need some help?
-If you encounter any bugs with the SDK please file an issue via [Issues](https://github.com/Azure/azure-sdk-for-java/issues) or checkout [StackOverflow for Azure Java SDK](http://stackoverflow.com/questions/tagged/azure-java-sdk).
+## Help
+If you encounter any bugs with these libraries, please file issues via [Issues](https://github.com/Azure/azure-sdk-for-java/issues) or checkout [StackOverflow for Azure Java SDK](http://stackoverflow.com/questions/tagged/azure-java-sdk).
#Contribute Code
@@ -66,5 +179,20 @@ If you would like to become an active contributor to this project please follow
4. Push to the branch (`git push origin my-new-feature`)
5. Create new Pull Request
-#Learn More
-* [JavaDocs](http://azure.github.io/azure-sdk-for-java)
+#More Information
+* [Javadoc](http://azure.github.io/azure-sdk-for-java)
+* [http://azure.com/java](http://azure.com/java)
+* If you don't have a Microsoft Azure subscription you can get a FREE trial account [here](http://go.microsoft.com/fwlink/?LinkId=330212)
+
+**Previous Releases and Corresponding Repo Branches**
+
+| Version | SHA1 | Remarks |
+|-------------------|-------------------------------------------------------------------------------------------|-------------------------------------------------------|
+| 1.0.0-beta1 | [1.0.0-beta1](https://github.com/Azure/azure-sdk-for-java/tree/1.0.0-beta1) | Maintenance branch for AutoRest generated raw clients |
+| 1.0.0-beta1+fixes | [v1.0.0-beta1+fixes](https://github.com/Azure/azure-sdk-for-java/tree/v1.0.0-beta1+fixes) | Stable build for AutoRest generated raw clients |
+| 0.9.x-SNAPSHOTS | [0.9](https://github.com/Azure/azure-sdk-for-java/tree/0.9) | Maintenance branch for service management libraries |
+| 0.9.3 | [v0.9.3](https://github.com/Azure/azure-sdk-for-java/tree/v0.9.3) | Latest release for service management libraries |
+
+---
+
+This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments.
diff --git a/media/auth/access.png b/media/auth/access.png
new file mode 100644
index 0000000000000..7f8420c728832
Binary files /dev/null and b/media/auth/access.png differ
diff --git a/media/auth/add-user.png b/media/auth/add-user.png
new file mode 100644
index 0000000000000..8099355c1b3d0
Binary files /dev/null and b/media/auth/add-user.png differ
diff --git a/media/auth/add.png b/media/auth/add.png
new file mode 100644
index 0000000000000..851203c13b58b
Binary files /dev/null and b/media/auth/add.png differ
diff --git a/media/auth/added.png b/media/auth/added.png
new file mode 100644
index 0000000000000..80f849f50a65b
Binary files /dev/null and b/media/auth/added.png differ
diff --git a/media/auth/adding.png b/media/auth/adding.png
new file mode 100644
index 0000000000000..59c732241e7aa
Binary files /dev/null and b/media/auth/adding.png differ
diff --git a/media/auth/app-props.png b/media/auth/app-props.png
new file mode 100644
index 0000000000000..0d7092266c874
Binary files /dev/null and b/media/auth/app-props.png differ
diff --git a/media/auth/app.png b/media/auth/app.png
new file mode 100644
index 0000000000000..488ba1456dc2e
Binary files /dev/null and b/media/auth/app.png differ
diff --git a/media/auth/browse-ad.png b/media/auth/browse-ad.png
new file mode 100644
index 0000000000000..baa4e93539775
Binary files /dev/null and b/media/auth/browse-ad.png differ
diff --git a/media/auth/client-id.png b/media/auth/client-id.png
new file mode 100644
index 0000000000000..47b858c1a8088
Binary files /dev/null and b/media/auth/client-id.png differ
diff --git a/media/auth/key-generated.png b/media/auth/key-generated.png
new file mode 100644
index 0000000000000..a0c769c15cfab
Binary files /dev/null and b/media/auth/key-generated.png differ
diff --git a/media/auth/keys.png b/media/auth/keys.png
new file mode 100644
index 0000000000000..1d8c2368d2093
Binary files /dev/null and b/media/auth/keys.png differ
diff --git a/media/auth/subscription-settings.png b/media/auth/subscription-settings.png
new file mode 100644
index 0000000000000..445310def7ff7
Binary files /dev/null and b/media/auth/subscription-settings.png differ
diff --git a/media/auth/subscriptions.png b/media/auth/subscriptions.png
new file mode 100644
index 0000000000000..8d5a351a3d334
Binary files /dev/null and b/media/auth/subscriptions.png differ
diff --git a/media/auth/tenant-id.png b/media/auth/tenant-id.png
new file mode 100644
index 0000000000000..ec42841337c4c
Binary files /dev/null and b/media/auth/tenant-id.png differ
diff --git a/media/auth/users.png b/media/auth/users.png
new file mode 100644
index 0000000000000..b6283c244657f
Binary files /dev/null and b/media/auth/users.png differ