README

Overview

This is a C# library for Authlete Web APIs.

Authlete is a cloud service that provides an implementation of OAuth 2.0 & OpenID Connect. By using the Web APIs provided by Authlete, you can develop a DB-less authorization server and/or OpenID provider. "DB-less" here means that you don't have to manage a database server that stores authorization data (e.g. access tokens), settings of authorization servers and settings of client applications. These data are stored in the Authlete server on cloud.

Please read New Architecture of OAuth 2.0 and OpenID Connect Implementation for details about the architecture of Authlete. True engineers will love the architecture ;-)

The primary advantage of this architecture is in that the backend service can focus on implementing OAuth 2.0 and OpenID Connect without caring about other components such as identity management, user authentication, login session management, API management and fraud detection. And, consequently, it leads to another major advantage which enables the backend service (implementation of OAuth 2.0 and OpenID Connect) to be combined with any solution of other components and thus gives flexibility to frontend server implementations.

License

Apache License, Version 2.0

Source Code (authlete-csharp)

https://github.com/authlete/authlete-csharp

API Reference (authlete-csharp)

https://authlete.github.io/authlete-csharp/

API Reference (Authlete)

https://docs.authlete.com/

NuGet

Authlete.Authlete

Samples

csharp-oauth-server - Authorization server
csharp-resource-server - Resource server
OAuth 2.0 and OpenID Connect implementation in C# (Authlete) - Article about the two servers above

Description

How To Get IAuthleteApi

All the methods to communicate with Authlete Web APIs are gathered in IAuthleteApi interface. Currently, AuthleteApi class is the only class that implements the interface.

The constructor of AuthleteApi class requires an implementation of IAuthleteConfiguration interface. Once you prepare an implementation of IAuthleteConfiguration interface, you can create an AuthleteApi instance as follows.

// Prepare configuration to access Authlete Web APIs.
IAuthleteConfiguration conf = ...;

// Create an instance that implements IAuthleteApi.
IAuthleteApi api = new AuthleteApi(conf);

IAuthleteConfiguration is an interface that holds configuration values to access Authlete Web APIs such as the URL of an Authlete server and API credentials of a service. To be concrete, the interface has the following properties.

Property	Description
`BaseUrl`	URL of an Authlete server
`ServiceApiKey`	API key of a service
`ServiceApiSecret`	API secret of a service
`ServiceOwnerApiKey`	API key of your account
`ServiceOwnerApiSecret`	API secret of your account

authlete-csharp includes three implementations of IAuthleteConfiguration interface as listed below.

Class	Description
`AuthleteEnvConfiguration`	Configuration by environment variables
`AuthletePropertiesConfiguration`	Configuration by a properties file
`AuthleteSimpleConfiguration`	Configuration by C# properties

AuthletePropertiesConfiguration

Among the three implementations of IAuthleteConfiguration interface, this section explains AuthletePropertiesConfiguration class.

AuthletePropertiesConfiguration class provides a mechanism to use a properties file to set configuration values to access Authlete Web APIs. Properties file here is a kind of configuration files used in Java world. The specification of the file format is described in the JavaDoc of java.util.Properties.load(java.io.Reader). authlete-csharp includes an implementation that can interpret the format (Authlete.Util.PropertiesLoader).

AuthletePropertiesConfiguration class has three constructors. The following examples show the usage of the constructors.

// (1) Constructor with no argument. This tries to read a file
//     named "authlete.properties". The environment variable,
//     AUTHLETE_CONFIGURATION_FILE, can be used to specify
//     another different file name.
IAuthleteConfiguration conf =
    new AuthletePropertiesConfiguration();

// (2) Constructor with the name of a configuration file.
IAuthleteConfiguration conf =
    new AuthletePropertiesConfiguration("authlete.properties");

// (3) Constructor with a TextReader.
using (TextReader reader = File.OpenText("authlete.properties"))
{
    IAuthleteConfiguration conf =
        new AuthletePropertiesConfiguration(reader);
}

AuthletePropertiesConfiguration class expects entries in the table below to be found in the given configuration file.

Property Key	Description
`base_url`	URL of an Authlete server
`service.api_key`	API key of a service
`service.api_secret`	API secret of a service
`service_owner.api_key`	API key of your account
`service_owner.api_secret`	API secret of your account

Below is an example of a configuration file.

base_url                 = https://api.authlete.com
service_owner.api_key    = 1532787510
service_owner.api_secret = 9Y0ZARGatedJRhsYLNfiK_aKQIBCug2O3JQU6srZrpk
service.api_key          = 9463955934
service.api_secret       = AAw0rner_wjRCpk-y1A6J9s20Bvez3GxEBoL9jOJVR0

IAuthleteApi Settings

Settings property of IAuthleteApi returns an instance of ISettings interface whereby you can adjust the behaviors of the implementation of IAuthleteApi interface.

// Get an implementation of IAuthleteApi interface.
IAuthleteApi api = ...;

// Get the instance which holds settings of the implementation.
ISettings settings = api.Setting;

// Set a network timeout.
//
// In the current implementation, the value set to the Timeout
// property is passed to HttpClient.Timeout.
//
settings.Timeout = TimeSpan.FromSeconds(5);

IAuthleteApi Method Categories

Methods in the IAuthleteApi interface can be divided into some categories.

Methods for Authorization Endpoint Implementation

- `Authorization(AuthorizationRequest request)`
- `AuthorizationFail(AuthorizationFailRequest request)`
- `AuthorizationIssue(AuthorizationIssueRequest request)`

Methods for Token Endpoint Implementation

- `Token(TokenRequest request)`
- `TokenFail(TokenFailRequest request)`
- `TokenIssue(TokenIssueRequest request)`

Methods for Service Management

- `CreateService(Service service)`
- `DeleteService(long serviceApiKey)`
- `GetService(long serviceApiKey)`
- `GetServiceList()`
- `GetServiceList(int start, int end)`
- `UpdateService(Service service)`

Methods for Client Application Management

- `CreateClient(Client client)`
- `DeleteClient(long clientId)`
- `GetClient(long clientId)`
- `GetClientList()`
- `GetClientList(string developer)`
- `GetClientList(int start, int end)`
- `GetClientList(string developer, int start, int end)`
- `UpdateClient(Client client)`
- `RefreshClientSecret(long clientId)`
- `RefreshClientSecret(string clientIdentifier)`
- `UpdateClientSecret(long clientId, string clientSecret)`
- `UpdateClientSecret(string clientIdentifier, string clientSecret)`

Methods for Access Token Introspection

- `Introspection(IntrospectionRequest request)`
- `StandardIntrospection(StandardIntrospectionRequest request)`

Methods for Revocation Endpoint Implementation

- `Revocation(RevocationRequest request)`

Methods for User Info Endpoint Implementation

- `Userinfo(UserInfoRequest request)`
- `UserinfoIssue(UserInfoIssueRequest request)`

Methods for JWK Set Endpoint Implementation

- `GetServiceJwks()`
- `GetServiceJwks(bool pretty, bool includePrivateKeys)`

Methods for OpenID Connect Discovery

- `GetServiceConfiguration()`
- `GetServiceConfiguration(bool pretty)`

Methods for Token Operations

- `TokenCreate(TokenCreateRequest request)`
- `TokenDelete(string token)`
- `TokenUpdate(TokenUpdateRequest request)`

Methods for Records of Granted Scopes

- `GetGrantedScopes(long clientId, string subject)`
- `DeleteGrantedScopes(long clientId, string subject)`

Methods for Authorization Management on a User-Client Combination Basis

- `DeleteClientAuthorization(long clientId, string subject)`
- `GetClientAuthorizationList(ClientAuthorizationGetListRequest request)`
- `UpdateClientAuthorization(long clientId, ClientAuthorizationUpdateRequest request)`

Methods for CIBA (Client Initiated Backchannel Authentication)

- `BackchannelAuthentication(BackchannelAuthenticationRequest request)`
- `BackchannelAuthenticationIssue(BackchannelAuthenticationIssueRequest request)`
- `BackchannelAuthenticationFail(BackchannelAuthenticationFailRequest request)`
- `BackchannelAuthenticationComplete(BackchannelAuthenticationCompleteRequest request)`

Methods for Device Flow

- `DeviceAuthorization(DeviceAuthorizationRequest request)`
- `DeviceComplete(DeviceCompleteRequest request)`
- `DeviceVerification(DeviceVerificationRequest request)`

Methods for Pushed Authorization Requests

- `PushAuthorizationRequest(PushedAuthReqRequest request)`

Example

The following code snippet is an example to get the list of your services. Each service corresponds to an authorization server.

// Prepare configuration to access Authlete APIs.
// AuthleteSimpleConfiguration is used here as one
// implementation of IAuthleteConfiguration interface.
// As described above, there are other implementations
// such as AuthletePropertiesConfiguraiton.
IAuthleteConfiguration conf = new AuthleteSimpleConfiguration
{
    BaseUrl               = "https://api.authlete.com",
    ServiceOwnerApiKey    = "1532787510",
    ServiceOwnerApiSecret = "9Y0ZARGatedJRhsYLNfiK_aKQIBCug2O3JQU6srZrpk",
    ServiceApiKey         = "9463955934",
    ServiceApiSecret      = "AAw0rner_wjRCpk-y1A6J9s20Bvez3GxEBoL9jOJVR0"
};

// Get an implementation of IAuthleteApi interface.
// Currently, AuthleteApi is the only class that
// implements the IAuthleteApi interface.
IAuthleteApi api = new AuthleteApi(conf);

// Get the list of services.
ServiceListResponse response = await api.GetServiceList();

Handlers

It is possible to develop an authorization server and/or OpenID provider only with the methods of IAuthleteApi interface, but the task will become much easier if you use utility classes in Authlete.Handler namespace.

You can find the usage of the handlers in csharp-oauth-server and csharp-resource-server. They are sample implementations of an authorization server and a resource server. OAuth 2.0 and OpenID Connect implementation in C# (Authlete) is an article about the two sample servers.

How To Test

$ cd Authlete.Tests
$ dotnet test

Docker Support

Building the Docker Image with Detailed Output

This project supports building and running inside a Docker container. The instructions below guide you through the process of building the Docker image, running the container, and retrieving test results with detailed build output.

Building the Docker Image

To build the Docker image with detailed build output, use the following command:

docker build -t authlete-test --progress=plain --no-cache --target build .

This command performs the following actions:

-t authlete-test tags the built Docker image as authlete-test.
--progress=plain displays the build output in plain text, providing detailed information during the build process.
--no-cache ensures that Docker does not use any cached layers from previous builds, forcing all steps to be re-executed.
--target build specifies that the Docker build process should stop after completing the build stage. This is particularly useful if you want to run tests without deploying the final application as part of the build process.

Retrieving Test Results

The Dockerfile is configured to generate test results in TRX format during the build process. To extract these test results from the Docker image to your host system, follow these steps:

Create a Temporary Container from the Image: Create a container named temp-container from your authlete-test image without starting it:
```
docker create --name temp-container authlete-test
```
Copy Test Results to Host: Copy the test results from the temp-container to a directory on your host machine:
```
docker cp temp-container:/test-results ./test-results
```
This copies the test results stored at /test-results inside the container to a ./test-results directory on your host.
Cleanup: Remove the temporary container:
```
docker rm temp-container
```

Now, you'll find the .trx test result files in the ./test-results directory on your host machine, ready for review.

How To Release

1. Update Documents

Update CHANGES.md and CHANGES.ja.md. Update README.md and README.ja.md, too, if necessary.

2. Update Version

In Visual Studio, open "Options" menu of the Authlete project. In the window titled "Project Options - Authlete", go to "NuGet Package" -> "Metadata" -> "General" tab. Update the value in the "Version:" field.

Or, edit the value of <PackageVersion> in Authlete/Authlete.csproj file directly.

3. Commit Version

$ git add Authlete/Authlete.csproj
$ git commit -m 'Updated PackageVersion to X.Y.Z.'
$ git push

4. Generate Package

$ dotnet pack

A .nupkg file will be created under bin/Debug directory.

5. Publish Package

$ nuget push bin/Debug/Authlete.Authlete.X.Y.Z.nupkg $KEY \
    -Source https://api.nuget.org/v3/index.json

The value of $KEY on the command line is an API key issued by nuget.org. See Publishing packages for details.

The published package will appear at https://www.nuget.org/packages/Authlete.Authlete, but it will take some minutes.

6. Update API Reference

$ cd ..
$ rm -rf html
$ doxygen

7. Publish API Reference

$ mkdir -p ../docs
$ cd ../docs
$ git clone https://github.com/authlete/authlete-csharp
$ cd authlete-csharp
$ git checkout gh-pages
$ rm -rf *
$ cp -r ../../authlete-csharp/html/* .
$ git add .
$ git commit -m 'Updated for version X.Y.Z'
$ git push origin gh-pages

Contact

Purpose	Email Address
General	info@authlete.com
Sales	sales@authlete.com
PR	pr@authlete.com
Technical	support@authlete.com