Skip to content

Commit

Permalink
Update readme based on internal redesign (#236)
Browse files Browse the repository at this point in the history 
* Update readme based on internal redesign

* update

* Fix typo

* Add banner

* Avoid relative links and fix docs

* Use banner from CDN
  • Loading branch information
@frederikprijck
frederikprijck authored Oct 20, 2022
1 parent 3771c7e commit 6a78d47
Show file tree
Hide file tree
Showing 2 changed files with 174 additions and 59 deletions.
112 changes: 98 additions & 14 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,28 +1,112 @@
# Auth0 OIDC Client for .NET

[![Build Status](https://dev.azure.com/Auth0SDK/Auth0%20OIDC%20Client.NET/_apis/build/status/auth0.auth0-oidc-client-net?branchName=master)](https://dev.azure.com/Auth0SDK/Auth0%20OIDC%20Client.NET/_build/latest?definitionId=4&branchName=master) [![NuGet version](https://img.shields.io/nuget/v/auth0.oidcclient.core.svg?style=flat)](https://www.nuget.org/packages/Auth0.OidcClient.Core/)
[![FOSSA Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2Fauth0%2Fauth0-oidc-client-net.svg?type=shield)](https://app.fossa.com/projects/git%2Bgithub.com%2Fauth0%2Fauth0-oidc-client-net?ref=badge_shield)
![Auth0 SDK for .NET Desktop and Mobile applications](https://cdn.auth0.com/website/sdks/banners/auth0-oidc-client-net-banner.png)

OIDC Client for .NET Desktop (WinForms, WPF and UWP) as well as Xamarin-based iOS and Android mobile applications.

This library makes use of the the [IdentityModel/IdentityModel.OidcClient](https://github.com/IdentityModel/IdentityModel.OidcClient) library and uses code from the [IdentityModel/IdentityModel.OidcClient.Samples](https://github.com/IdentityModel/IdentityModel.OidcClient.Samples) repository to achieve browser integration.
[![NuGet version](https://img.shields.io/nuget/v/auth0.oidcclient.core.svg?style=flat)](https://www.nuget.org/packages/Auth0.OidcClient.Core/)
![Downloads](https://img.shields.io/nuget/dt/Auth0.OidcClient.Core)
[![License](https://img.shields.io/:license-Apache2.0-blue.svg?style=flat)](https://opensource.org/licenses/Apache-2.0)
[![Build Status](https://dev.azure.com/Auth0SDK/Auth0%20OIDC%20Client.NET/_apis/build/status/auth0.auth0-oidc-client-net?branchName=master)](https://dev.azure.com/Auth0SDK/Auth0%20OIDC%20Client.NET/_build/latest?definitionId=4&branchName=master)

:books: [Documentation](#documentation) - :rocket: [Getting Started](#getting-started) - :computer: [API Reference](#api-reference) - :speech_balloon: [Feedback](#feedback)

This library makes use of the [IdentityModel/IdentityModel.OidcClient](https://github.com/IdentityModel/IdentityModel.OidcClient) library and uses code from the [IdentityModel/IdentityModel.OidcClient.Samples](https://github.com/IdentityModel/IdentityModel.OidcClient.Samples) repository to achieve browser integration.

For information on how to use this library, please refer to the relevant Quickstarts:
## Documentation

* [UWP](https://auth0.com/docs/quickstart/native/windows-uwp-csharp)
* [WPF/WinForms](https://auth0.com/docs/quickstart/native/wpf-winforms)
* [Xamarin](https://auth0.com/docs/quickstart/native/xamarin)
- [UWP Quickstart](https://auth0.com/docs/quickstart/native/windows-uwp-csharp) - our interactive guide for quickly adding login, logout and user information to a UWP application using Auth0.
- [WPF/WinForms Quickstart](https://auth0.com/docs/quickstart/native/wpf-winforms) - our interactive guide for quickly adding login, logout and user information to a WPF and WinForms application using Auth0.
- [Xamarin Quickstart](https://auth0.com/docs/quickstart/native/xamarin) - our interactive guide for quickly adding login, logout and user information to a Xamarin application using Auth0.
- [WPF Sample App](https://github.com/auth0-samples/auth0-WinFormsWPF-oidc-samples/tree/master/Quickstart/00-Starter-Seed/WPF) - a WPF application integrated with Auth0.
- [WinForms Sample App](https://github.com/auth0-samples/auth0-WinFormsWPF-oidc-samples/tree/master/Quickstart/00-Starter-Seed/WinForms) - a WinForms application integrated with Auth0.
- [Xamarin Sample App](https://github.com/auth0-samples/auth0-xamarin-oidc-samples/tree/master/Quickstart/01-Login) - a Xamarin application integrated with Auth0.
- [SDK docs](https://auth0.github.io/auth0-oidc-client-net/documentation/intro.html) - explore the documentation for this SDK.
- [Auth0 docs](https://www.auth0.com/docs) - explore our docs site and learn more about

and also to our [docs for this library](https://auth0.github.io/auth0-oidc-client-net/documentation/intro.html).

## Getting started

### Requirements

For a list of supported platforms, please refer to the relevant documentation from Microsoft:

* [Xamarin](https://docs.microsoft.com/en-us/xamarin/get-started/supported-platforms)
* [UWP/WPF/WinForms](https://docs.microsoft.com/en-us/lifecycle/faq/windows)

## Breaking changes in v3
### Installation
The SDK is available on [Nuget](https://www.nuget.org/packages?q=Auth0.OidcClient) for different platforms:

```
Install-Package Auth0.OidcClient.UWP
Install-Package Auth0.OidcClient.WPF
Install-Package Auth0.OidcClient.WinForms
Install-Package Auth0.OidcClient.iOS
Install-Package Auth0.OidcClient.Android
Install-Package Auth0.OidcClient.AndroidX
```

### Configure Auth0

Create a **Native Application** in the [Auth0 Dashboard](https://manage.auth0.com/#/applications).

> **If you're using an existing application**, verify that you have configured the following settings in your Native Application:
>
> - Click on the "Settings" tab of your application's page.
> - Ensure that "Token Endpoint Authentication Method" under "Application Properties" is set to "None"
> - Scroll down and click on the "Show Advanced Settings" link.
> - Under "Advanced Settings", click on the "OAuth" tab.
> - Ensure that "JsonWebToken Signature Algorithm" is set to `RS256` and that "OIDC Conformant" is enabled.
Next, configure the following URLs for your application under the "Application URIs" section of the "Settings" page:

- **Allowed Callback URLs**
- **Allowed Logout URLs**

> For the values for these URLs, please refer to the corresponding quickstart from our [documentation](#documentation).
Take note of the **Client ID** and **Domain** values under the "Basic Information" section. You'll need these values to configure the SDK.

### Configure the SDK
All platforms share the same interface, so you can use the following code to instantiate the `Auth0Client`:

```csharp
using Auth0.OidcClient;
// ...
var auth0Client = new Auth0Client(new Auth0ClientOptions
{
Domain = "YOUR_AUTH0_DOMAIN",
ClientId = "YOUR_AUTH0_CLIENT_ID"
});
```

## API reference
Read [the full API reference](https://auth0.github.io/auth0-oidc-client-net/api/Auth0.OidcClient.html) to find out about the public API's this SDK exposes.

## Feedback
### Contributing

We appreciate feedback and contribution to this repo! Before you get started, please see the following:

- [Auth0's general contribution guidelines](https://github.com/auth0/open-source-template/blob/master/GENERAL-CONTRIBUTING.md)
- [Auth0's code of conduct guidelines](https://github.com/auth0/open-source-template/blob/master/CODE-OF-CONDUCT.md)
- [This repo's contribution guide](CONTRIBUTING.md)

### Raise an issue

To provide feedback or report a bug, please [raise an issue on our issue tracker](https://github.com/auth0/auth0-oidc-client-net/issues).

### Vulnerability Reporting

Please do not report security vulnerabilities on the public GitHub issue tracker. The [Responsible Disclosure Program](https://auth0.com/responsible-disclosure-policy) details the procedure for disclosing security issues.

Version 3 of this library includes many potential breaking changes depending on your usage. Please read [Migrating to Auth0-OIDC-Client-NET v3](https://auth0.github.io/auth0-oidc-client-net/documentation/migration/v3.html).
---

## License
[![FOSSA Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2Fauth0%2Fauth0-oidc-client-net.svg?type=large)](https://app.fossa.com/projects/git%2Bgithub.com%2Fauth0%2Fauth0-oidc-client-net?ref=badge_large)
<p align="center">
<picture>
<source media="(prefers-color-scheme: light)" srcset="https://cdn.auth0.com/website/sdks/logos/auth0_light_mode.png" width="150">
<source media="(prefers-color-scheme: dark)" srcset="https://cdn.auth0.com/website/sdks/logos/auth0_dark_mode.png" width="150">
<img alt="Auth0 Logo" src="https://cdn.auth0.com/website/sdks/logos/auth0_light_mode.png" width="150">
</picture>
</p>
<p align="center">Auth0 is an easy to implement, adaptable authentication and authorization platform. To learn more checkout <a href="https://auth0.com/why-auth0">Why Auth0?</a></p>
<p align="center">
This project is licensed under the Apache-2.0 license. See the <a href="https://github.com/auth0/auth0-oidc-client-net/blob/master/LICENSE"> LICENSE</a> file for more info.</p>
121 changes: 76 additions & 45 deletions docs-source/index.md
View file
Original file line number Diff line number Diff line change
@@ -1,81 +1,112 @@
# Auth0 OIDC Client
![](https://cdn.auth0.com/website/sdks/banners/auth0-oidc-client-net-banner.png)

The Auth0 OIDC Client allows you to add authentication for your .NET Client applications. The Auth0 OIDC Client supports the following platforms:
OIDC Client for .NET Desktop (WinForms, WPF and UWP) as well as Xamarin-based iOS and Android mobile applications.

* Universal Windows Platform (UWP 10.0.16299 and higher)
* Windows Presentation Foundation (.NET 4.6.2 and higher)
* Windows Forms (.NET 4.6.2 and higher)
* iOS (uses Xamarin)
* Android (uses Xamarin)
[![NuGet version](https://img.shields.io/nuget/v/auth0.oidcclient.core.svg?style=flat)](https://www.nuget.org/packages/Auth0.OidcClient.Core/)
![Downloads](https://img.shields.io/nuget/dt/Auth0.OidcClient.Core)
[![License](https://img.shields.io/:license-Apache2.0-blue.svg?style=flat)](https://opensource.org/licenses/Apache-2.0)
[![Build Status](https://dev.azure.com/Auth0SDK/Auth0%20OIDC%20Client.NET/_apis/build/status/auth0.auth0-oidc-client-net?branchName=master)](https://dev.azure.com/Auth0SDK/Auth0%20OIDC%20Client.NET/_build/latest?definitionId=4&branchName=master)

## Quick Start
:books: [Documentation](#documentation) - :rocket: [Getting Started](#getting-started) - :computer: [API Reference](#api-reference) - :speech_balloon: [Feedback](#feedback)

> Before you start, ensure that you have configured the Callback URL in the Clients Settings section in the [Auth0 dashboard](https://manage.auth0.com/#/). See the [Callback URLs documentation](documentation/getting-started/callbacks.md) for more information on what Callback URL you need to use for your particular platform.
This library makes use of the [IdentityModel/IdentityModel.OidcClient](https://github.com/IdentityModel/IdentityModel.OidcClient) library and uses code from the [IdentityModel/IdentityModel.OidcClient.Samples](https://github.com/IdentityModel/IdentityModel.OidcClient.Samples) repository to achieve browser integration.

> [!Note]
> You will also need to ensure that the JWT Signature Algorithm for your client is set to RS256
## Documentation

### 1. Install the NuGet Package for your platform
- [UWP Quickstart](https://auth0.com/docs/quickstart/native/windows-uwp-csharp) - our interactive guide for quickly adding login, logout and user information to a UWP application using Auth0.
- [WPF/WinForms Quickstart](https://auth0.com/docs/quickstart/native/wpf-winforms) - our interactive guide for quickly adding login, logout and user information to a WPF and WinForms application using Auth0.
- [Xamarin Quickstart](https://auth0.com/docs/quickstart/native/xamarin) - our interactive guide for quickly adding login, logout and user information to a Xamarin application using Auth0.
- [WPF Sample App](https://github.com/auth0-samples/auth0-WinFormsWPF-oidc-samples/tree/master/Quickstart/00-Starter-Seed/WPF) - a WPF application integrated with Auth0.
- [WinForms Sample App](https://github.com/auth0-samples/auth0-WinFormsWPF-oidc-samples/tree/master/Quickstart/00-Starter-Seed/WinForms) - a WinForms application integrated with Auth0.
- [Xamarin Sample App](https://github.com/auth0-samples/auth0-xamarin-oidc-samples/tree/master/Quickstart/01-Login) - a Xamarin application integrated with Auth0.
- [SDK docs](https://auth0.github.io/auth0-oidc-client-net/documentation/intro.html) - explore the documentation for this SDK.
- [Auth0 docs](https://www.auth0.com/docs) - explore our docs site and learn more about

**Universal Windows Platform (UWP)**

```text
Install-Package Auth0.OidcClient.UWP
```
## Getting started

**Windows Presentation Foundation (WPF)**
### Requirements

```text
Install-Package Auth0.OidcClient.WPF
```
For a list of supported platforms, please refer to the relevant documentation from Microsoft:

* [Xamarin](https://docs.microsoft.com/en-us/xamarin/get-started/supported-platforms)
* [UWP/WPF/WinForms](https://docs.microsoft.com/en-us/lifecycle/faq/windows)

**Windows Forms**
### Installation
The SDK is available on [Nuget](https://www.nuget.org/packages?q=Auth0.OidcClient) for different platforms:

```text
```
Install-Package Auth0.OidcClient.UWP
Install-Package Auth0.OidcClient.WPF
Install-Package Auth0.OidcClient.WinForms
Install-Package Auth0.OidcClient.iOS
Install-Package Auth0.OidcClient.Android
Install-Package Auth0.OidcClient.AndroidX
```

**iOS (uses Xamarin)**
### Configure Auth0

```text
Install-Package Auth0.OidcClient.iOS
```
Create a **Native Application** in the [Auth0 Dashboard](https://manage.auth0.com/#/applications).

**Android (uses Xamarin)**
> **If you're using an existing application**, verify that you have configured the following settings in your Native Application:
>
> - Click on the "Settings" tab of your application's page.
> - Ensure that "Token Endpoint Authentication Method" under "Application Properties" is set to "None"
> - Scroll down and click on the "Show Advanced Settings" link.
> - Under "Advanced Settings", click on the "OAuth" tab.
> - Ensure that "JsonWebToken Signature Algorithm" is set to `RS256` and that "OIDC Conformant" is enabled.
```text
Install-Package Auth0.OidcClient.Android
```
Next, configure the following URLs for your application under the "Application URIs" section of the "Settings" page:

- **Allowed Callback URLs**
- **Allowed Logout URLs**

> For the values for these URLs, please refer to the corresponding quickstart from our [documentation](#documentation).
Take note of the **Client ID** and **Domain** values under the "Basic Information" section. You'll need these values to configure the SDK.

### 2. Initialize
### Configure the SDK
All platforms share the same interface, so you can use the following code to instantiate the `Auth0Client`:

```csharp
using Auth0.OidcClient;

var client = new Auth0Client(new Auth0ClientOptions
// ...
var auth0Client = new Auth0Client(new Auth0ClientOptions
{
Domain = "YOUR_AUTH0_DOMAIN",
ClientId = "YOUR_AUTH0_CLIENT_ID"
});
```

### 3. Authenticate
## API reference
Read [the full API reference](https://auth0.github.io/auth0-oidc-client-net/api/Auth0.OidcClient.html) to find out about the public API's this SDK exposes.

For Windows clients, you can simply call @Auth0.OidcClient.Auth0Client.LoginAsync(System.Object)
## Feedback
### Contributing

```csharp
var loginResult = await client.LoginAsync();
```
We appreciate feedback and contribution to this repo! Before you get started, please see the following:

- [Auth0's general contribution guidelines](https://github.com/auth0/open-source-template/blob/master/GENERAL-CONTRIBUTING.md)
- [Auth0's code of conduct guidelines](https://github.com/auth0/open-source-template/blob/master/CODE-OF-CONDUCT.md)
- [This repo's contribution guide](https://github.com/auth0/auth0-oidc-client-net/blob/master/CONTRIBUTING.md)

### Raise an issue

For Android and iOS clients, you need to do some manual work to log a user in. The basic flow is as follows:
To provide feedback or report a bug, please [raise an issue on our issue tracker](https://github.com/auth0/auth0-oidc-client-net/issues).

1. Obtain an `AuthorizeState` by calling @Auth0.OidcClient.Auth0Client.PrepareLoginAsync(System.Object). You will need to save the instance of `AuthorizeState` as you will need it later on.
2. Launch the system browser and direct the user to the `StartUrl` in the returned `AuthorizeState`. After the user has logged in, Auth0 will call back to your application on the Callback URL.
3. Your application will need to handle the callback. The means either creating an `Intent` or Android, or handling `OpenUrl` in your `AppDelegate` on iOS.
### Vulnerability Reporting

For a more detailed walkthrough, please see the relevant [Quickstarts](https://auth0.com/docs/quickstart/native).
Please do not report security vulnerabilities on the public GitHub issue tracker. The [Responsible Disclosure Program](https://auth0.com/responsible-disclosure-policy) details the procedure for disclosing security issues.

## Further Reading
---

For more information please refer to the [Documentation](documentation/intro.md) section, or to the [API Documentation](api/index.md)
<p align="center">
<picture>
<source media="(prefers-color-scheme: light)" srcset="https://cdn.auth0.com/website/sdks/logos/auth0_light_mode.png" width="150">
<source media="(prefers-color-scheme: dark)" srcset="https://cdn.auth0.com/website/sdks/logos/auth0_dark_mode.png" width="150">
<img alt="Auth0 Logo" src="https://cdn.auth0.com/website/sdks/logos/auth0_light_mode.png" width="150">
</picture>
</p>
<p align="center">Auth0 is an easy to implement, adaptable authentication and authorization platform. To learn more checkout <a href="https://auth0.com/why-auth0">Why Auth0?</a></p>
<p align="center">
This project is licensed under the Apache-2.0 license. See the <a href="https://github.com/auth0/auth0-oidc-client-net/blob/master/LICENSE"> LICENSE</a> file for more info.</p>

0 comments on commit 6a78d47

Please sign in to comment.