Skip to content

Commit 798af07

Browse files
ismcagdasismcagdas
authored
Merge pull request #269 from aspnetzero/feat/openIddict-integration-documents
OpenIddict integration documents
2 parents 4d6ce67 + 7a0d980 commit 798af07

8 files changed

+309
-67
lines changed

‎docs/en/Infrastructure-Core-Angular-Identity-Server4-Integration.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,8 @@
11
# Identity Server 4 Integration
22

3+
**\*\*IMPORTANT NOTICE\*\***
4+
Identity Server 4 maintainance stopped on November 2022, see [official announcement](https://identityserver4.readthedocs.io/en/latest/). Because of that, it is removed from ASP.NET Zero. We suggest migrating to OpenIddict. Check out ASP.NET Zero's [OpenIddict integration document](Infrastructure-Core-Angular-OpenIddict-Integration.md).
5+
36
[IdentityServer4](http://identityserver.io/) is an OpenID Connect and OAuth 2.0 framework for ASP.NET Core. ASP.NET Zero is integrated to IdentityServer4. It's **disabled by default**. Its located in `*.Web.Host` project.
47

58
## Configuration

‎docs/en/Infrastructure-Core-Angular-OpenIddict-Integration.md

Lines changed: 114 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,114 @@
1+
# Identity Server 4 Integration
2+
3+
[OpenIddict](https://documentation.openiddict.com/) aims at providing a versatile solution to implement OpenID Connect client, server and token validation support in any ASP.NET Core 2.1 (and higher) application.
4+
5+
## Configuration
6+
7+
You can enable/disable or configure it from **appsettings.json** file
8+
9+
```json
10+
"OpenIddict": {
11+
"IsEnabled": "true",
12+
"Applications": [{
13+
"ClientId": "client",
14+
"ClientSecret": "def2edf7-5d42-4edc-a84a-30136c340e13",
15+
"DisplayName": "AbpZeroTemplate_App",
16+
"ConsentType": "Explicit",
17+
"RedirectUris": ["https://oauthdebugger.com/debug"],
18+
"PostLogoutRedirectUris": [],
19+
"Scopes": [
20+
"default-api",
21+
"profile"
22+
],
23+
"Permissions": [
24+
"ept:token",
25+
"ept:authorization",
26+
"gt:password",
27+
"gt:client_credentials",
28+
"gt:authorization_code",
29+
"rst:code",
30+
"rst:code id_token"
31+
]
32+
}]
33+
}
34+
```
35+
36+
* **IsEnabled**: Indicates if OpenIddict integration is enabled or not.
37+
* **Applications**: List of OpenIddict applications.
38+
* **ClientId**: The client identifier associated with the current application.
39+
* **ClientSecret**: The client secret associated with the current application.
40+
* **DisplayName**: The display name associated with the current application.
41+
* **ConsentType**: The consent type associated with the current application (see [possible values](https://github.com/openiddict/openiddict-core/blob/dev/src/OpenIddict.Abstractions/OpenIddictConstants.cs#L178)).
42+
* **RedirectUris**: The callback URLs associated with the current application, serialized as a JSON array.
43+
* **PostLogoutRedirectUris**: The logout callback URLs associated with the current application, serialized as a JSON array.
44+
* **Scopes**: The scopes associated with the current authorization, serialized as a JSON array (see [possible values](https://github.com/openiddict/openiddict-core/blob/dev/src/OpenIddict.Abstractions/OpenIddictConstants.cs#L402). You can also use custom values).
45+
* **Permissions**: The permissions associated with the current application, serialized as a JSON array (see [possible values](https://github.com/openiddict/openiddict-core/blob/dev/src/OpenIddict.Abstractions/OpenIddictConstants.cs#L360)).
46+
47+
## Testing with Client
48+
49+
ASP.NET Zero solution has a sample console application (ConsoleApiClient) that can connects to the application, authenticates through OpenIddict and calls an API.
50+
51+
52+
## Testing with Web Client
53+
54+
You can use [https://oauthdebugger.com/](https://oauthdebugger.com/) website to test openIddict with a web client.
55+
56+
Add a new Application to `*.Web.Host` appsettings.json
57+
58+
```json
59+
...
60+
{
61+
"ClientId": "client",
62+
"ClientSecret": "def2edf7-5d42-4edc-a84a-30136c340e13",
63+
"DisplayName": "AbpZeroTemplate_App",
64+
"ConsentType": "Explicit",
65+
"RedirectUris": ["https://oauthdebugger.com/debug"],
66+
"PostLogoutRedirectUris": [],
67+
"Scopes": [
68+
"default-api",
69+
"profile"
70+
],
71+
"Permissions": [
72+
"ept:token",
73+
"ept:authorization",
74+
"gt:password",
75+
"gt:client_credentials",
76+
"gt:authorization_code",
77+
"rst:code",
78+
"rst:code id_token"
79+
]
80+
}
81+
...
82+
```
83+
84+
Then, go to [https://oauthdebugger.com/](https://oauthdebugger.com/) and create a URL for authorization code flow. A sample URL should be something like this;
85+
86+
```bash
87+
https://localhost:44301/connect/authorize
88+
?client_id=client
89+
&redirect_uri=https://oauthdebugger.com/debug
90+
&scope=default-api
91+
&response_type=code
92+
&response_mode=query
93+
&state=krd0ddufuw
94+
&nonce=fbhw5it86l6
95+
```
96+
97+
Visit this URL using a browser. If you are not logged into your ASP.NET Zero application, you will be redirected to Login page. If you are already logged in, you will be redirected back to [https://oauthdebugger.com/](https://oauthdebugger.com/). Here, you will see the result of the request as shown below;
98+
99+
![oauthdebugger code](images/openiddict_oauthdebugger_code.png)
100+
101+
You can use this code to request an access token. You need to send a request to [https://localhost:44301/connect/token](https://localhost:44301/connect/token) endpoint. Here is a sample request using Postman.
102+
103+
![openiddict token endpoint](images/openiddict_token_endpoint.png)
104+
105+
Using this token, you can get details of the user using [https://localhost:44301/connect/userinfo](https://localhost:44301/connect/userinfo) endpoint or you can make a request to any ASP.NET Zero API service (for example [https://localhost:44301/api/services/app/User/GetUsers](https://localhost:44301/api/services/app/User/GetUsers)).
106+
107+
## OpenId Connect Integration
108+
109+
Once OpenIddict integration is enabled, Web.Host application becomes an OpenId Connect server. That means another web application can use standard OpenId Connect protocol to authenticate users with your
110+
application and get permission to share their information (a.k.a. consent screen).
111+
112+
## More
113+
114+
See [OpenIddict's own documentation](https://documentation.openiddict.com/) to understand and configure OpenIddict.

‎docs/en/Infrastructure-Core-Mvc-Identity-Server4-Integration.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,8 @@
11
# Identity Server 4 Integration
22

3+
**\*\*IMPORTANT NOTICE\*\***
4+
Identity Server 4 maintainance stopped on November 2022, see [official announcement](https://identityserver4.readthedocs.io/en/latest/). Because of that, it is removed from ASP.NET Zero. We suggest migrating to OpenIddict. Check out ASP.NET Zero's [OpenIddict integration document](Infrastructure-Core-Mvc-OpenIddict-Integration.md).
5+
36
[IdentityServer4](http://identityserver.io/) is an OpenID Connect and OAuth 2.0 framework for ASP.NET Core. ASP.NET Zero is integrated to IdentityServer4. It's **enabled by default**.
47

58
## Configuration

‎docs/en/Infrastructure-Core-Mvc-OpenIddict-Integration.md

Lines changed: 114 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,114 @@
1+
# Identity Server 4 Integration
2+
3+
[OpenIddict](https://documentation.openiddict.com/) aims at providing a versatile solution to implement OpenID Connect client, server and token validation support in any ASP.NET Core 2.1 (and higher) application.
4+
5+
## Configuration
6+
7+
You can enable/disable or configure it from **appsettings.json** file
8+
9+
```json
10+
"OpenIddict": {
11+
"IsEnabled": "true",
12+
"Applications": [{
13+
"ClientId": "client",
14+
"ClientSecret": "def2edf7-5d42-4edc-a84a-30136c340e13",
15+
"DisplayName": "AbpZeroTemplate_App",
16+
"ConsentType": "Explicit",
17+
"RedirectUris": ["https://oauthdebugger.com/debug"],
18+
"PostLogoutRedirectUris": [],
19+
"Scopes": [
20+
"default-api",
21+
"profile"
22+
],
23+
"Permissions": [
24+
"ept:token",
25+
"ept:authorization",
26+
"gt:password",
27+
"gt:client_credentials",
28+
"gt:authorization_code",
29+
"rst:code",
30+
"rst:code id_token"
31+
]
32+
}]
33+
}
34+
```
35+
36+
* **IsEnabled**: Indicates if OpenIddict integration is enabled or not.
37+
* **Applications**: List of OpenIddict applications.
38+
* **ClientId**: The client identifier associated with the current application.
39+
* **ClientSecret**: The client secret associated with the current application.
40+
* **DisplayName**: The display name associated with the current application.
41+
* **ConsentType**: The consent type associated with the current application (see [possible values](https://github.com/openiddict/openiddict-core/blob/dev/src/OpenIddict.Abstractions/OpenIddictConstants.cs#L178)).
42+
* **RedirectUris**: The callback URLs associated with the current application, serialized as a JSON array.
43+
* **PostLogoutRedirectUris**: The logout callback URLs associated with the current application, serialized as a JSON array.
44+
* **Scopes**: The scopes associated with the current authorization, serialized as a JSON array (see [possible values](https://github.com/openiddict/openiddict-core/blob/dev/src/OpenIddict.Abstractions/OpenIddictConstants.cs#L402). You can also use custom values).
45+
* **Permissions**: The permissions associated with the current application, serialized as a JSON array (see [possible values](https://github.com/openiddict/openiddict-core/blob/dev/src/OpenIddict.Abstractions/OpenIddictConstants.cs#L360)).
46+
47+
## Testing with Client
48+
49+
ASP.NET Zero solution has a sample console application (ConsoleApiClient) that can connects to the application, authenticates through OpenIddict and calls an API.
50+
51+
52+
## Testing with Web Client
53+
54+
You can use [https://oauthdebugger.com/](https://oauthdebugger.com/) website to test openIddict with a web client.
55+
56+
Add a new Application to `*.Web.Mvc` appsettings.json
57+
58+
```json
59+
...
60+
{
61+
"ClientId": "client",
62+
"ClientSecret": "def2edf7-5d42-4edc-a84a-30136c340e13",
63+
"DisplayName": "AbpZeroTemplate_App",
64+
"ConsentType": "Explicit",
65+
"RedirectUris": ["https://oauthdebugger.com/debug"],
66+
"PostLogoutRedirectUris": [],
67+
"Scopes": [
68+
"default-api",
69+
"profile"
70+
],
71+
"Permissions": [
72+
"ept:token",
73+
"ept:authorization",
74+
"gt:password",
75+
"gt:client_credentials",
76+
"gt:authorization_code",
77+
"rst:code",
78+
"rst:code id_token"
79+
]
80+
}
81+
...
82+
```
83+
84+
Then, go to [https://oauthdebugger.com/](https://oauthdebugger.com/) and create a URL for authorization code flow. A sample URL should be something like this;
85+
86+
```bash
87+
https://localhost:44302/connect/authorize
88+
?client_id=client
89+
&redirect_uri=https://oauthdebugger.com/debug
90+
&scope=default-api
91+
&response_type=code
92+
&response_mode=query
93+
&state=krd0ddufuw
94+
&nonce=fbhw5it86l6
95+
```
96+
97+
Visit this URL using a browser. If you are not logged into your ASP.NET Zero application, you will be redirected to Login page. If you are already logged in, you will be redirected back to [https://oauthdebugger.com/](https://oauthdebugger.com/). Here, you will see the result of the request as shown below;
98+
99+
![oauthdebugger code](images/openiddict_oauthdebugger_code.png)
100+
101+
You can use this code to request an access token. You need to send a request to [https://localhost:44302/connect/token](https://localhost:44302/connect/token) endpoint. Here is a sample request using Postman.
102+
103+
![openiddict token endpoint](images/openiddict_token_endpoint.png)
104+
105+
Using this token, you can get details of the user using [https://localhost:44302/connect/userinfo](https://localhost:44302/connect/userinfo) endpoint or you can make a request to any ASP.NET Zero API service (for example [https://localhost:44302/api/services/app/User/GetUsers](https://localhost:44302/api/services/app/User/GetUsers)).
106+
107+
## OpenId Connect Integration
108+
109+
Once OpenIddict integration is enabled, Web.Mvc application becomes an OpenId Connect server. That means another web application can use standard OpenId Connect protocol to authenticate users with your
110+
application and get permission to share their information (a.k.a. consent screen).
111+
112+
## More
113+
114+
See [OpenIddict's own documentation](https://documentation.openiddict.com/) to understand and configure OpenIddict.

‎docs/en/images/openiddict_oauthdebugger_code.png

55.7 KB
Loading

‎docs/en/images/openiddict_token_endpoint.png

100 KB
Loading

0 commit comments

Comments
 (0)