Merge pull request #3 from DSorlov/dev

Dev to Master v0.0.1

Author: DSorlov

CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog for eid-provider-net
+
+The format is based on [Keep a Changelog][keep-a-changelog]
+<!-- and this project adheres to [Semantic Versioning][semantic-versioning]. -->
+
+## [Unreleased]
+- Nothing right now
+
+## [0.0.1] (2020-09-12)
+
+### Library
+- Initial release
+- Support for bankid, frejaeid and frejaorgid
+
+### Powershell
+- Initial release
+- Support for bankid, frejaeid and frejaorgid
+
+[keep-a-changelog]: http://keepachangelog.com/en/1.0.0/
+[Unreleased]: https://github.com/DSorlov/eid-provider-net/compare/master...dev
+[0.0.1]: https://github.com/DSorlov/eid-provider-net/releases/tag/v0.0.1

README.md

@@ -5,21 +5,25 @@
 [![License](https://img.shields.io/badge/License-MIT-blue.svg)](https://img.shields.io/github/license/DSorlov/eid-provider)
 
 # eid-provider-net
-This module is developed to enable rapid deployment of identity based authentication for .NET by creating a common interface to most of the suppliers for official electronic identification and it allows you to mix and match your suppliers. This is a .NET port from code that I have contributed in [eid-provider](https://github.com/DSorlov/eid-provider) and that is used in multiple projects. Documentation will be updated closer to release.
-
-| :warning:  This library is not relased yet for production and lacking documentation!   |
-|----------------------------------------------------------|
+This code is developed to enable rapid deployment of identity based authentication for .NET by creating a common interface to most of the suppliers for official electronic identification and it allows you to mix and match your suppliers. This is a .NET port from code that I have contributed in [eid-provider](https://github.com/DSorlov/eid-provider) and that is used in multiple projects.
 
 | :warning:  This library requires .NET 5.0 to run!   |
 |----------------------------------------------------------|
 
-The code in this repo consists of two projects (binary releases will be available once I get a bit further into the project). The first is the C# library that is performing all the operations towards the modules as outlined below and the other is a powershell cmdlet project that provides a module for use with PowerShell to make sure simple admin devops easily can be used to interact with the library.
+### eid-provider-net library
+A .net library that is performing all the operations towards the modules as outlined in the table below and the working horse of this project.
+See the [basic method documentation](docs/methods.md) or the [basic examples](docs/examples.md).
+
+### eid-provider-net powershell module
+A powershell cmdlet project that provides a module for use with PowerShell to make sure simple admin devops easily can be used to interact with the library in scripts and wherever else it is needed, makes output more powershell friendly and is allaround a bit nicer to work with for interactive or scripting purposes.
+See [powershell examples](docs/powershell_examples.md).
 
-There are basically right now two main types of integrations: one is working directly with the service apis and the other kind is working with a broker service. The broker services can be usefull if you have many integrations or other sources in your enterprise and you wish to use the same sources for these. Right now I am working on moving over and adapting the code for the providers for [eid-provider](https://github.com/DSorlov/eid-provider) and these will all be availiable before first stable release.
+### Supported integrations
+There are basically right now two main types of integrations: one is working directly with the service apis and the other kind is working with a broker service. The broker services can be usefull if you have many integrations or other sources in your enterprise and you wish to use the same sources for these. Right now I am working on moving over and adapting the code for the providers for [eid-provider](https://github.com/DSorlov/eid-provider) and will be added as they are needed and updated, submit an issue if you need to get one of them prioritized.
 
 | ID-Type | Module | Vendor | Authentication | Signing | Geographies | Readiness |
 | --- | --- | --- | --- | --- | --- | --- |
 | BankID | [bankid](docs/bankid.md) | BankID | :heavy_check_mark: | :heavy_check_mark: | :sweden: | Production |
-| Freja eID | [frejaeid](docs/frejaeid.md) | BankID | :heavy_check_mark: | :heavy_check_mark: | :sweden: | Production |
+| Freja eID and Freja Org ID | [frejaeid](docs/frejaeid.md) | Freja eID | :heavy_check_mark: | :heavy_check_mark: | :sweden: | Production |
 
 

docs/bankid.md

@@ -0,0 +1,29 @@
+## BankID (bankid)
+
+### Description
+This module works directly with the BankID api.
+It is supplied with working testing credentials and basic production details.
+
+### Inputs and outputs
+
+**Extra fields on completion**
+* `autostart_token` the token used for autostart
+* `autostart_url` code for invoking authorization
+
+### Default Configuration
+>**Default production configuration (settings.production)**
+```
+endpoint:  'https://appapi2.bankid.com/rp/v5',
+client_cert:  '',
+ca_cert:  'builtin://certs/bankid_prod.ca',
+allowFingerprint:  true,
+password:  ''
+```
+>**Default testing configuration (settings.testing)**
+```
+endpoint:  'https://appapi2.test.bankid.com/rp/v5',
+client_cert:  'builtin://certs/bankid_test.pfx',
+ca_cert:  'builtin://certs/bankid_test.ca',
+allowFingerprint:  true,
+password:  'qwerty123'
+```

docs/examples.md

@@ -0,0 +1,46 @@
+## Examples
+
+Very simple examples. All methods are available in Async versions also and supporting IProgress for long running operations.
+
+### Simple C# example for frejaeid
+This is a very simple example of calling authentication via frejaeid for the ssn 200101011212 and when final results are in dump them out on the console.
+```csharp
+EIDClientInitializationData config = new frejaeid.InitializationData(EIDEnvironment.Testing);
+EIDClient client = new frejaeid.Client((frejaeid.InitializationData)config);
+EIDResult = client.AuthRequest("200101011212");
+Console.WriteLine(EIDResult.ToString());
+```
+
+### Simple C# example for bankid
+This is a very simple example of calling authentication via bankid for the ssn 200101011212 and when final results are in dump them out on the console.
+```csharp
+EIDClientInitializationData config = new bankid.InitializationData(EIDEnvironment.Testing);
+EIDClient client = new bankid.Client((bankid.InitializationData)config);
+EIDResult = client.AuthRequest("200101011212");
+Console.WriteLine(EIDResult.ToString());
+```
+
+### Simple C# example for frejaeid with event callback
+This is a very simple example of calling authentication via frejaeid for the ssn 200101011212 and when final results are in dump them out on the console and also listen to events while it is processing
+```csharp
+EIDClientInitializationData config = new frejaeid.InitializationData(EIDEnvironment.Testing);
+EIDClient client = new frejaeid.Client((frejaeid.InitializationData)config);
+
+//Attach a event listener
+client.RequestEvent = (e) => { Console.WriteLine(e.EIDResult.ToString(); }; 
+
+EIDResult = client.AuthRequest("200101011212");
+Console.WriteLine(EIDResult.ToString());
+```
+
+### Simple C# example configuring options in config
+This is a very simple example of calling authentication via frejaeid for the ssn 200101011212 and when final results are in dump them out on the console.
+```csharp
+EIDClientInitializationData config = new bankid.InitializationData(EIDEnvironment.Testing);
+config["client_cert"] = YourX509Certificate2();
+
+EIDClient client = new bankid.Client((bankid.InitializationData)config);
+EIDResult = client.AuthRequest("200101011212");
+Console.WriteLine(EIDResult.ToString());
+```
+

docs/frejaeid.md

@@ -0,0 +1,55 @@
+## Freja eID (frejaeid)
+
+### Description
+This module works directly with the Freja eID REST API and Freja eID Org ID REST API.
+It is supplied with working testing credentials and basic production details.
+
+This module exposes extra functions also (and async variants also):
+- **AddOrgIdRequest(string id, string title, string attribute, string value)** Creates a new orgidadd and returns after result is received
+- **InitAddOrgIdRequest(string id, string title, string attribute, string value)** Initiates orgidadd and returns a initialization object
+- **PollAddOrgIdResult(string id)** Checks the status of a orgidadd operation
+- **CancelAddOrgIdRequest(string id)** Cancels a pending orgidadd
+- **DeleteOrgId(string id)** Removes a orgid from an existing eid
+- **CreateCustomIdentifier(string id, string customid)** Creates a custom identifier for a specific eid
+- **DeleteCustomIdentifier(string customid)** Removes a custom identifier for a specific eid
+
+### Inputs and outputs
+
+**Extra fields on completion**
+* `autostart_token` the token used for autostart
+* `autostart_url` code for invoking authorization
+
+### Default Configuration
+attribute_list is a comma separated list of EMAIL_ADDRESS,RELYING_PARTY_USER_ID,BASIC_USER_INFO,SSN,ADDRESSES,DATE_OF_BIRTH,ALL_EMAIL_ADDRESSES
+minimum_level is one of BASIC,EXTENDED,PLUS
+id_type is one of SSN,EMAIL,PHONE
+>**Default production configuration (settings.production)**
+```
+endpoint:  'https://services.prod.frejaeid.com',
+client_cert:  '',
+ca_cert:  'builtin://certs/frejaeid_prod.ca',
+jwt_cert: {
+    'aRw9OLn2BhM7hxoc458cIXHfezw': 'builtin://certs/frejaeid_prod_aRw9OLn2BhM7hxoc458cIXHfezw.jwt'),
+    'onjnxVgI3oUzWQMLciD7sQZ4mqM': 'builtin://certs/frejaeid_prod_onjnxVgI3oUzWQMLciD7sQZ4mqM.jwt')
+},
+minimum_level:  'EXTENDED',
+password:  '',
+default_country: 'SE',
+id_type: 'SSN',
+attribute_list: 'EMAIL_ADDRESS,RELYING_PARTY_USER_ID,BASIC_USER_INFO'        
+```
+>**Default testing configuration (settings.testing)**
+```
+endpoint:  'https://services.test.frejaeid.com',
+client_cert:  'builtin://certs/frejaeid_test.ca',
+ca_cert:  'builtin://certs/frejaeid_test.pfx',
+jwt_cert:  {
+    '2LQIrINOzwWAVDhoYybqUcXXmVs': 'builtin://certs/frejaeid_test_2LQIrINOzwWAVDhoYybqUcXXmVs.jwt'),
+    'HwMHK_gb3_iuNF1advMtlG0-fUs': 'builtin://certs/frejaeid_test_HwMHK_gb3_iuNF1advMtlG0-fUs.jwt')
+},
+minimum_evel:  'EXTENDED',
+password:  'test',
+default_country: 'SE',
+id_type: 'SSN',
+attribute_list: 'EMAIL_ADDRESS,RELYING_PARTY_USER_ID,BASIC_USER_INFO'        
+```

docs/methods.md

@@ -0,0 +1,124 @@
+## Methods
+
+This is the general description of the methods availiable to you.
+I'm still struggling a bit to make this really readable in a good way, so perhaps easier to check with the [examples](examples.md).
+This as close a replication of the original library as possible, it is using language specific features and sports some nice taskbased interfaces.
+
+### constructor(initialization data)
+
+Configures the module according to the object sent in.
+Example configs can be obtained by accessing the `settings` properties of each module.
+
+>**Inputs**
+
+object(mandatory): A object containing configuration.
+
+>**Outputs**
+
+None
+
+### PollAuthStatus(string) or PollSignStatus(string)
+
+>**Inputs**
+
+string(mandatory): A string containing the id of the authentication or signing you wish to check
+
+>**Outputs**
+
+A status object as one of the below:
+
+```javascript
+{
+    status: 'error' or 'pending',
+    code: string,
+    description: string,
+    [details: string]
+}
+```
+
+The description field is a user friendly error message in english. The details is a optional field that if it exists contains more information about the error. More generic error types often have a details field.
+
+| Status | Possible Codes |
+| --- | --- |
+| error | system_error<br/>request_id_invalid<br/>api_error<br/>expired_transaction<br/>cancelled_by_user<br/>cancelled_by_idp | 
+| pending | pending_notdelivered<br/>pending_user_in_app<br/>pending_delivered | 
+
+```javascript
+{
+    status: 'completed',
+    user: {
+        firstname: string,
+        lastname: string,
+        fullname: string,
+        ssn: string
+    },
+    extra: {..}
+}
+```
+
+When the status is completed extra information may be in the extra block depending on which module you are using.
+
+### Task AuthRequest(string, ProcessIProgress<EIDResult>, CancellationToken) or Task SignRequest(string, string, ProcessIProgress<EIDResult>, CancellationToken)
+
+>**Inputs**
+
+string: this is the ssn most probably put could be a object with special properties for that module.
+ProcessIProgress<EIDResult>: A ProcessIProgress to report back events and updates as they unfold
+CancellationToken: Standard CancellationToken to cancel the running task
+
+>**Outputs**
+
+Same as PollAuthStatus(string) or PollSignStatus(string) but wrapped in a awaitable Task
+
+### InitAuthRequest(string) or InitSignRequest(string,string)
+
+>**Inputs**
+
+string(mandatory): this is the ssn most probably put could be a object with special properties for that module.
+string(only for signing): this is the text most probably put could be a object with special properties for that module.
+
+>**Outputs**
+
+A status object as one of the below:
+
+```javascript
+{
+    status: 'error',
+    code: string,
+    description: string,
+    [details: string]
+}
+```
+
+The description field is a user friendly error message in english. The details is a optional field that if it exists contains more information about the error. More generic error types often have a details field.
+
+| Status | Possible Codes |
+| --- | --- |
+| error | system_error<br/>already_in_progress<br/>request_ssn_invalid<br/>request_text_invalid<br/>api_error | 
+
+```javascript
+{
+    status: 'initialized',
+    id: string,
+    description: string,
+    extra: {..}
+}
+```
+
+When the status is completed extra information may be in the extra block depending on which module you are using.
+
+### CancelAuthRequest(string) or CancelSignRequest(string)
+
+>**Inputs**
+
+string(mandatory): A string containing the id of the authentication or signing you wish to cancel
+
+>**Outputs**
+
+```javascript
+{
+    status: 'cancelled',
+    id: string,
+    description: string,
+    extra: {..}
+}

docs/powershell_examples.md

@@ -0,0 +1,27 @@
+## Powershell Examples
+
+Very simple examples.
+
+### Simple power example for frejaeid
+This is a very simple example of calling authentication via frejaeid for the ssn 200101011212 and print the results console.
+
+```powershell
+    $config = Get-EIDConfig frejaeid -Enviroment Testing
+    Request-EIDOperation $config -Type auth -Id 200101011212 -Wait
+```
+
+### Simple powershell example for bankid
+This is a very simple example of calling authentication via frejaeid for the ssn 200101011212 and print the results console.
+
+```powershell
+    $config = Get-EIDConfig bankid -Enviroment Testing
+    Request-EIDOperation $config -Type auth -Id 200101011212 -Wait
+```
+
+### Add an organizational id to a existing eid via freja eid orgid
+This is a very simple example of calling authentication via frejaeid for the ssn 200101011212 and print the results console.
+
+```powershell
+    $config = Get-EIDConfig frejaeid -Enviroment Testing
+    Start-EIDRequest $s -Type orgid -Id 200101011212 -Title "Corp Id" -Attribute "Employee #" -Value "123456" -Wait
+```

eid-provider-library/EIDClientEvent.cs

@@ -8,7 +8,7 @@ namespace com.sorlov.eidprovider
 {
     public class EIDClientEvent : EventArgs
     {
-        public EIDResult Result
+        public EIDResult EIDResult
         {
             get => result;
         }

eid-provider-library/EIDResult.cs

@@ -13,7 +13,8 @@ public enum ResultStatus
             initialized,
             completed,
             pending,
-            cancelled
+            cancelled,
+            ok
         }
 
         public ResultStatus Status
@@ -69,6 +70,22 @@ internal static EIDResult CreateErrorResult(string code, string description)
             return new EIDResult(ResultStatus.error, data);
         }
 
+        internal static EIDResult CreateOKResult(string code, string description)
+        {
+            JObject data = new JObject();
+            data["code"] = code;
+            data["description"] = description;
+            return new EIDResult(ResultStatus.ok, data);
+        }
+        internal static EIDResult CreateOKResult(string code, string description, JObject extra)
+        {
+            JObject data = new JObject();
+            data["code"] = code;
+            data["description"] = description;
+            data["extra"] = extra;
+            return new EIDResult(ResultStatus.ok, data);
+        }
+
         internal static EIDResult CreatePendingResult(string code, string description)
         {
             JObject data = new JObject();