This repository has been archived by the owner on Dec 13, 2018. It is now read-only.
-
Notifications
You must be signed in to change notification settings - Fork 13
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #32 from stormpath/develop
Release 0.1.0
- Loading branch information
Showing
122 changed files
with
4,126 additions
and
531 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,11 +1,9 @@ | ||
| [](https://travis-ci.org/stormpath/stormpath-sdk-csharp) | ||
|
|
||
| # Stormpath .NET SDK # | ||
| # Stormpath .NET SDK [](https://travis-ci.org/stormpath/stormpath-sdk-csharp) | ||
|
|
||
| *An advanced, reliable and easy-to-use user management API for .NET by security experts* | ||
|
|
||
| [Stormpath](https://stormpath.com) is a complete user management API. This | ||
| library gives your ASP.NET web application access to all of Stormpath's features: | ||
| library gives your ASP.NET or C# application access to all of Stormpath's features: | ||
|
|
||
| - Robust authentication and authorization. | ||
| - Schemaless user data and profiles. | ||
|
|
@@ -14,19 +12,237 @@ library gives your ASP.NET web application access to all of Stormpath's features | |
| - Secure API key authentication for your service. | ||
| - Servlet support for Java web applications. | ||
|
|
||
| In addition to these core Stormpath features, this SDK provides: | ||
|
|
||
| - Support for .NET 4.5 and later | ||
| - Support for Mono on Linux | ||
| - Easy installation using NuGet | ||
| - Fully asynchronous design using the [TPL](https://msdn.microsoft.com/en-us/library/dd460717(v=vs.110).aspx) | ||
|
|
||
| If you have feedback about this library, please get in touch and share your | ||
| thoughts! [email protected] | ||
|
|
||
| ## Current status | ||
|
|
||
| This library is currently under initial development. If you would like to be notified when we publish our first release candidate, watch this repository or send an email to [email protected]. | ||
| This library is currently under active development. If you would like to be notified when we publish releases, watch this repository or send an email to [email protected]. | ||
|
|
||
| ## Installation instructions | ||
|
|
||
| The Stormpath C# SDK consists of three packages: `Stormpath.SDK.Core`, `Stormpath.SDK.JsonNetSerializer`, and `Stormpath.SDK.RestSharpClient`. The latter two contain dependencies on external libraries ([JSON.NET](https://github.com/JamesNK/Newtonsoft.Json) and [RestSharp](https://github.com/restsharp/RestSharp)). These are required for the SDK to run properly. | ||
|
|
||
| For convenience, the meta-package `Stormpath.SDK` contains everything you need to get up an running quickly. :thumbsup: | ||
|
|
||
| #### Using the Nuget Package Manager | ||
|
|
||
| 1. Right-click on the new project in the Solution Explorer and choose **Manage Nuget Packages...** | ||
| 2. Search for Stormpath. Install the Stormpath.SDK package. | ||
|
|
||
| #### Using the Package Manager Console | ||
|
|
||
| Simply run `install-package Stormpath.SDK`. Done! | ||
|
|
||
| #### Using Mono | ||
|
|
||
| It's as easy as `mono nuget.exe install Stormpath.SDK`. | ||
|
|
||
| ## Quickstart | ||
|
|
||
| In this quickstart, you'll use Visual Studio to make a simple console application that creates a user and logs them into an application. | ||
|
|
||
| #### Get an API Key | ||
|
|
||
| 1. If you haven't already, [sign up for Stormpath here](https://api.stormpath.com/register). Check your email for a verification link. | ||
| 2. Click the link in the verification email. | ||
| 3. Log in to the [Stormpath Admin Console](https://api.stormpath.com/) using the email address and password you used to register with Stormpath. | ||
| 4. Click the **Create API Key** or **Manage Existing Keys** button in the middle of the page. | ||
| 5. Under **Security Credentials**, click **Create API Key**. This will generate your API Key and download it to your computer as an `apiKey.properties` file. If you open the file in a text editor, you will see something similar to the following: | ||
| ``` | ||
| apiKey.id = 144JVZINOF5EBNCMG9EXAMPLE | ||
| apiKey.secret = lWxOiKqKPNwJmSldbiSkEbkNjgh2uRSNAb+AEXAMPLE | ||
| ``` | ||
|
|
||
| Save this file in a secure location, such as a `.stormpath` directory in your home directory. (This is the default location the SDK checks, but you can specify a different location if you'd like.) | ||
|
|
||
| For example: | ||
|
|
||
| ``` | ||
| C:\>cd %homedrive%%homepath% | ||
| C:\Users\yourname>mkdir .stormpath | ||
| C:\Users\yourname>cd .stormpath | ||
| C:\Users\yourname\.stormpath>copy C:\Users\yourname\Downloads\apiKey.properties apiKey.Properties | ||
| ``` | ||
|
|
||
| The `apiKey.properties` file holds your API key information, and can be used to easily authenticate with the Stormpath SDK. Treat it as a sensitive file! | ||
|
|
||
| #### Creating a project | ||
|
|
||
| Next, create a simple Visual Studio project and add the Stormpath SDK. | ||
|
|
||
| 1. Create a new Console Application project. | ||
| 2. Use the [instructions above](#installation-instructions) to install the Stormpath SDK into your project. | ||
| 3. Add the following using statements to the top of your `Program.cs` file: | ||
|
|
||
| ```csharp | ||
| using Stormpath.SDK; | ||
| using Stormpath.SDK.Client; | ||
| using Stormpath.SDK.Error; | ||
| ``` | ||
|
|
||
| #### `await` a minute | ||
|
|
||
| The Stormpath SDK performs `await`able asynchronous operations by default. This makes it possible to make requests to the Stormpath API without tying up a worker thread - super cool for ASP.NET projects! | ||
|
|
||
| In the Console Application template, however, the entry point is `static void Main()`, so you can't use the `await` keyword. (In an ASP.NET application, you could just change the method signature to `async Task`, but that doesn't work well in a console app.) | ||
|
|
||
| You can work around this by writing a separate method instead: | ||
|
|
||
| ```csharp | ||
| static Task MainAsync() | ||
| { | ||
| } | ||
| ``` | ||
|
|
||
| and calling it synchronously from `Main()`: | ||
|
|
||
| ```csharp | ||
| static void Main(string[] args) | ||
| { | ||
| MainAsync().GetAwaiter().GetResult(); | ||
| } | ||
| ``` | ||
|
|
||
| If you are confused by all this `async` business, check out Stephen Cleary's [excellent introductory blog post](http://blog.stephencleary.com/2012/02/async-and-await.html) on the subject. | ||
|
|
||
| #### Creating a client | ||
|
|
||
| The first thing you need to connect to the Stormpath API is a `IClient` object. Create one in your new `MainAsync` method: | ||
|
|
||
| ```csharp | ||
| // If you put the apiKey.properties file in the default location | ||
| // (%homedrive%%homepath\.stormpath\apiKey.properties), you can skip this! | ||
| IClientApiKey myApiKey = ClientApiKeys.Builder() | ||
| .SetFileLocation("path\\to\\apiKey.properties") | ||
| .Build(); | ||
|
|
||
| // Create an IClient object. Everything starts here! | ||
| IClient client = Clients.Builder() | ||
| .SetApiKey(myApiKey) | ||
| .Build(); | ||
| ``` | ||
|
|
||
| You can skip building the `IClientApiKey` object and the call to `.SetApiKey()` if you put your `apiKey.properties` file in the default location. Calling `.Build()` without specifying an API Key will check the default location. :thumbsup: | ||
|
|
||
| Once you have built a `IClient`, keep it around! You should only need to create it **once** per application. It's thread-safe, so you can safely reuse it, even in an ASP.NET application. | ||
|
|
||
| #### Retrieving your application | ||
|
|
||
| Now that you have a `IClient`, you need to get an `IApplication` object that represents an Application in Stormpath. You should have a default application called "My Application" in your Stormpath account. It's easy to retrieve: | ||
|
|
||
| ```csharp | ||
| var myApp = await client.GetApplications() | ||
| .Where(x => x.Name == "My Application") | ||
| .SingleAsync(); | ||
| ``` | ||
|
|
||
| You can use this `IApplication` object to create user accounts, log in user accounts, and all sorts of other cool stuff. | ||
|
|
||
| #### Creating a user account | ||
|
|
||
| You can create a new user by calling `CreateAccountAsync`: | ||
|
|
||
| ```csharp | ||
| var joe = await myApp.CreateAccountAsync("Joe", "Stormtrooper", | ||
| "[email protected]", | ||
| "Changeme123!"); | ||
| Console.WriteLine("User " + joe.FullName + " created"); | ||
| ``` | ||
|
|
||
| The returned `IAccount` object will contain all the account's data. Easy! :smile: | ||
|
|
||
| #### Logging in | ||
|
|
||
| Now that you have a valid user in the Stormpath application, you can perform a login request. | ||
|
|
||
| ```csharp | ||
| // Imagine that we got these values from a web request: | ||
| var usernameOrEmail = "[email protected]"; | ||
| var password = "Changeme123!"; | ||
|
|
||
| try | ||
| { | ||
| var loginResult = await myApp.AuthenticateAccountAsync(usernameOrEmail, password); | ||
| var loggedInAccount = await loginResult.GetAccountAsync(); | ||
| Console.WriteLine("User {0} logged in", loggedInAccount.FullName); | ||
| } | ||
| catch (ResourceException rex) | ||
| { | ||
| Console.WriteLine("Could not log in. Error: " + rex.Message); | ||
| } | ||
| ``` | ||
|
|
||
| :bulb: You can also use the `TryAuthenticateAccountAsync(username, password)` overload to get a `bool` result if you don't need to access the account's data after login. | ||
|
|
||
| #### Clean up | ||
|
|
||
| Cleaning up your Stormpath application is easy: | ||
|
|
||
| ```csharp | ||
| try | ||
| { | ||
| await joe.DeleteAsync(); | ||
| } | ||
| catch (ResourceException rex) | ||
| { | ||
| Console.WriteLine("Unexpected error when deleting " + joe.Email + ". Error: " + rex.Message); | ||
| } | ||
| Console.WriteLine("Done!"); | ||
| ``` | ||
|
|
||
| As a final touch, you can add this line at the end so the console window doesn't disappear immediately: | ||
|
|
||
| ```csharp | ||
| Console.ReadKey(false); | ||
| ``` | ||
|
|
||
| #### Other things you can do with the SDK | ||
|
|
||
| * Create and delete entire applications | ||
| * Search for accounts using LINQ | ||
| * Modify and save account data | ||
| * Reset an account's password | ||
|
|
||
| ## Build Instructions | ||
|
|
||
| #### Building with Visual Studio | ||
|
|
||
| Building the SDK requires Visual Studio 2015. | ||
|
|
||
| 1. Use `git clone` or the Visual Studio GitHub extension to clone the branch you want to build (`master` or `develop`). | ||
| 2. Open `stormpath-sdk-csharp\Stormpath.SDK\Stormpath.SDK.sln` in Visual Studio. | ||
| 3. On first build, the required NuGet packages should resore. If not, [enable automatic package restore](http://stackoverflow.com/a/29708080/3191599). | ||
|
|
||
| #### Building with MSBuild | ||
|
|
||
| 1. Clone the repository: `git clone https://github.com/stormpath/stormpath-sdk-csharp.git` | ||
| 2. `cd stormpath-sdk-csharp\Stormpath.SDK` | ||
| 2. Assuming you have [nuget.exe](https://docs.nuget.org/consume/installing-nuget#command-line-utility) in your `PATH`: `nuget restore Stormpath.SDK.sln` | ||
| 3. `msbuild Stormpath.SDK.sln` | ||
|
|
||
| #### Building with Mono | ||
|
|
||
| Building with Mono requires Mono 4.0 or greater installed on your machine. | ||
|
|
||
| 1. Clone the repository: `git clone https://github.com/stormpath/stormpath-sdk-csharp.git` | ||
| 2. `cd stormpath-sdk-csharp\Stormpath.SDK` | ||
| 3. If you don't have NuGet available otherwise, use your favorite command line tool to download NuGet: `wget https://nuget.org/nuget.exe` | ||
| 4. `mono nuget.exe restore Stormpath.SDK.sln` | ||
| 5. `xbuild Stormpath.SDK.sln` | ||
|
|
||
| ## Contributing | ||
|
|
||
| Contributions, bug reports and issues are very welcome. Stormpath regularly maintains this repository, and are quick to review pull requests and accept changes! | ||
|
|
||
| You can make your own contributions by forking the develop branch of this | ||
| repository, making your changes, and issuing pull request on the develop branch. | ||
| You can make your own contributions by forking the develop branch of this repository, making your changes, and issuing pull request on the develop branch. | ||
|
|
||
| ## Copyright | ||
|
|
||
|
|
||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,5 +1,5 @@ | ||
| <?xml version="1.0" encoding="utf-8"?> | ||
| <packages> | ||
| <package id="Newtonsoft.Json" version="7.0.1" targetFramework="net452" /> | ||
| <package id="StyleCop.Analyzers" version="1.0.0-beta011" targetFramework="net45" developmentDependency="true" /> | ||
| <package id="StyleCop.Analyzers" version="1.0.0-beta012" targetFramework="net45" developmentDependency="true" /> | ||
| </packages> |
Oops, something went wrong.