Skip to content

Commit fe3e8bd

Browse files
TomPallisterTomPallister
authored
Remove Ocelot specific Middleware to make Ocelot more compatible with kestrel middleware and get ready for YARP
1 parent 99a15d8 commit fe3e8bd

File tree

214 files changed

+9585
-9930
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

214 files changed

+9585
-9930
lines changed

‎.editorconfig‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@ root = true
44
end_of_line = lf
55
insert_final_newline = true
66

7-
[*.cs]
7+
[*.cs]
8+
end_of_line = lf
89
indent_style = space
910
indent_size = 4

‎.gitattributes‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# 2010
2+
*.txt -crlf
3+
4+
# 2020
5+
*.txt text eol=lf

‎Ocelot.sln‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@ EndProject
88
Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Solution Items", "Solution Items", "{3FA7C349-DBE8-4904-A2CE-015B8869CE6C}"
99
ProjectSection(SolutionItems) = preProject
1010
.dockerignore = .dockerignore
11+
.editorconfig = .editorconfig
1112
.gitignore = .gitignore
1213
build.cake = build.cake
1314
build.ps1 = build.ps1

‎README.md‎

Lines changed: 6 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -8,28 +8,16 @@
88

99
# Ocelot
1010

11-
Ocelot is a .NET API Gateway. This project is aimed at people using .NET running
12-
a micro services / service oriented architecture
11+
Ocelot is a .NET API Gateway. This project is aimed at people using .NET running a micro services / service oriented architecture
1312
that need a unified point of entry into their system. However it will work with anything that speaks HTTP and run on any platform that ASP.NET Core supports.
1413

15-
In particular I want easy integration with
16-
IdentityServer reference and bearer tokens.
14+
In particular I want easy integration with IdentityServer reference and bearer tokens.
1715

18-
We have been unable to find this in my current workplace
19-
without having to write our own Javascript middlewares
20-
to handle the IdentityServer reference tokens. We would
21-
rather use the IdentityServer code that already exists
22-
to do this.
16+
We have been unable to find this in my current workplacewithout having to write our own Javascript middlewares to handle the IdentityServer reference tokens. We would rather use the IdentityServer code that already existsto do this.
2317

2418
Ocelot is a bunch of middlewares in a specific order.
2519

26-
Ocelot manipulates the HttpRequest object into a state specified by its configuration until
27-
it reaches a request builder middleware where it creates a HttpRequestMessage object which is
28-
used to make a request to a downstream service. The middleware that makes the request is
29-
the last thing in the Ocelot pipeline. It does not call the next middleware.
30-
The response from the downstream service is retrieved as the requests goes back up the Ocelot pipeline.
31-
There is a piece of middleware that maps the HttpResponseMessage onto the HttpResponse object and that
32-
is returned to the client. That is basically it with a bunch of other features!
20+
Ocelot manipulates the HttpRequest object into a state specified by its configuration until it reaches a request builder middleware where it creates a HttpRequestMessage object which is used to make a request to a downstream service. The middleware that makes the request is the last thing in the Ocelot pipeline. It does not call the next middleware. The response from the downstream service is retrieved as the requests goes back up the Ocelot pipeline. There is a piece of middleware that maps the HttpResponseMessage onto the HttpResponse object and that is returned to the client. That is basically it with a bunch of other features!
3321

3422
## Features
3523

@@ -81,15 +69,13 @@ We love to receive contributions from the community so please keep them coming :
8169

8270
Pull requests, issues and commentary welcome!
8371

84-
Please complete the relevant template for issues and PRs. Sometimes it's worth getting in touch with us to discuss changes
85-
before doing any work incase this is something we are already doing or it might not make sense. We can also give
86-
advice on the easiest way to do things :)
72+
Please complete the relevant template for issues and PRs. Sometimes it's worth getting in touch with us to discuss changes before doing any work incase this is something we are already doing or it might not make sense. We can also give advice on the easiest way to do things :)
8773

8874
Finally we mark all existing issues as help wanted, small, medium and large effort. If you want to contribute for the first time I suggest looking at a help wanted & small effort issue :)
8975

9076
## Donate
9177

92-
If you think this project is worth supporting financially please make a contribution using the button below!
78+
If you think this project is worth supporting financially please make a contribution using the button below! We use the money to run the https://threemammals.com website.
9379

9480
[![Support via PayPal](https://cdn.rawgit.com/twolfson/paypal-github-button/1.0.0/dist/button.svg)](https://www.paypal.me/ThreeMammals/)
9581

‎docs/features/administration.rst‎

Lines changed: 128 additions & 140 deletions
Original file line numberDiff line numberDiff line change
@@ -1,140 +1,128 @@
1-
Administration
2-
==============
3-
4-
Ocelot supports changing configuration during runtime via an authenticated HTTP API. This can be authenticated in two ways either using Ocelot's
5-
internal IdentityServer (for authenticating requests to the administration API only) or hooking the administration API authentication into your own
6-
IdentityServer.
7-
8-
The first thing you need to do if you want to use the administration API is bring in the relavent NuGet package..
9-
10-
``Install-Package Ocelot.Administration``
11-
12-
This will bring down everything needed by the admin API.
13-
14-
Providing your own IdentityServer
15-
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
16-
17-
All you need to do to hook into your own IdentityServer is add the following to your ConfigureServices method.
18-
19-
.. code-block:: csharp
20-
21-
public virtual void ConfigureServices(IServiceCollection services)
22-
{
23-
Action<IdentityServerAuthenticationOptions> options = o => {
24-
// o.Authority = ;
25-
// o.ApiName = ;
26-
// etc....
27-
};
28-
29-
services
30-
.AddOcelot()
31-
.AddAdministration("/administration", options);
32-
}
33-
34-
You now need to get a token from your IdentityServer and use in subsequent requests to Ocelot's administration API.
35-
36-
This feature was implemented for `issue 228 <https://github.com/ThreeMammals/Ocelot/issues/228>`_. It is useful because the IdentityServer authentication
37-
middleware needs the URL of the IdentityServer. If you are using the internal IdentityServer it might not alaways be possible to have the Ocelot URL.
38-
39-
Internal IdentityServer
40-
^^^^^^^^^^^^^^^^^^^^^^^
41-
42-
The API is authenticated using bearer tokens that you request from Ocelot iteself. This is provided by the amazing
43-
`Identity Server <https://github.com/IdentityServer/IdentityServer4>`_ project that I have been using for a few years now. Check them out.
44-
45-
In order to enable the administration section you need to do a few things. First of all add this to your
46-
initial Startup.cs.
47-
48-
The path can be anything you want and it is obviously reccomended don't use
49-
a url you would like to route through with Ocelot as this will not work. The administration uses the
50-
MapWhen functionality of asp.net core and all requests to {root}/administration will be sent there not
51-
to the Ocelot middleware.
52-
53-
The secret is the client secret that Ocelot's internal IdentityServer will use to authenticate requests to the administration API. This can be whatever you want it to be!
54-
55-
.. code-block:: csharp
56-
57-
public virtual void ConfigureServices(IServiceCollection services)
58-
{
59-
services
60-
.AddOcelot()
61-
.AddAdministration("/administration", "secret");
62-
}
63-
64-
In order for the administration API to work, Ocelot / IdentityServer must be able to call itself for validation. This means that you need to add the base url of Ocelot
65-
to global configuration if it is not default (http://localhost:5000). Please note if you are using something like docker to host Ocelot it might not be able to
66-
call back to localhost etc and you need to know what you are doing with docker networking in this scenario. Anyway this can be done as follows..
67-
68-
If you want to run on a different host and port locally..
69-
70-
.. code-block:: json
71-
72-
"GlobalConfiguration": {
73-
"BaseUrl": "http://localhost:55580"
74-
}
75-
76-
or if Ocelot is exposed via dns
77-
78-
.. code-block:: json
79-
80-
"GlobalConfiguration": {
81-
"BaseUrl": "http://mydns.com"
82-
}
83-
84-
Now if you went with the configuration options above and want to access the API you can use the postman scripts
85-
called ocelot.postman_collection.json in the solution to change the Ocelot configuration. Obviously these
86-
will need to be changed if you are running Ocelot on a different url to http://localhost:5000.
87-
88-
89-
The scripts show you how to request a bearer token from ocelot and then use it to GET the existing configuration and POST
90-
a configuration.
91-
92-
If you are running multiple Ocelot instances in a cluster then you need to use a certificate to sign the bearer tokens used to access the administration API.
93-
94-
In order to do this you need to add two more environmental variables for each Ocelot in the cluster.
95-
96-
``OCELOT_CERTIFICATE``
97-
The path to a certificate that can be used to sign the tokens. The certificate needs to be of the type X509 and obviously Ocelot needs to be able to access it.
98-
``OCELOT_CERTIFICATE_PASSWORD``
99-
The password for the certificate.
100-
101-
Normally Ocelot just uses temporary signing credentials but if you set these environmental variables then it will use the certificate. If all the other Ocelot instances in the cluster have the same certificate then you are good!
102-
103-
104-
Administration API
105-
^^^^^^^^^^^^^^^^^^
106-
107-
**POST {adminPath}/connect/token**
108-
109-
This gets a token for use with the admin area using the client credentials we talk about setting above. Under the hood this calls into an IdentityServer hosted within Ocelot.
110-
111-
The body of the request is form-data as follows
112-
113-
``client_id`` set as admin
114-
115-
``client_secret`` set as whatever you used when setting up the administration services.
116-
117-
``scope`` set as admin
118-
119-
``grant_type`` set as client_credentials
120-
121-
**GET {adminPath}/configuration**
122-
123-
124-
This gets the current Ocelot configuration. It is exactly the same JSON we use to set Ocelot up with in the first place.
125-
126-
**POST {adminPath}/configuration**
127-
128-
This overrwrites the existing configuration (should probably be a put!). I reccomend getting your config from the GET endpoint, making any changes and posting it back...simples.
129-
130-
The body of the request is JSON and it is the same format as the FileConfiguration.cs that we use to set up
131-
Ocelot on a file system.
132-
133-
Please note that if you want to use this API then the process running Ocelot must have permission to write to the disk
134-
where your ocelot.json or ocelot.{environment}.json is located. This is because Ocelot will overwrite them on save.
135-
136-
**DELETE {adminPath}/outputcache/{region}**
137-
138-
This clears a region of the cache. If you are using a backplane it will clear all instances of the cache! Giving your the ability to run a cluster of Ocelots and cache over all of them in memory and clear them all at the same time / just use a distributed cache.
139-
140-
The region is whatever you set against the Region field in the FileCacheOptions section of the Ocelot configuration.
1+
Administration
2+
==============
3+
4+
Ocelot supports changing configuration during runtime via an authenticated HTTP API. This can be authenticated in two ways either using Ocelot's internal IdentityServer (for authenticating requests to the administration API only) or hooking the administration API authentication into your own IdentityServer.
5+
6+
The first thing you need to do if you want to use the administration API is bring in the relavent NuGet package..
7+
8+
``Install-Package Ocelot.Administration``
9+
10+
This will bring down everything needed by the admin API.
11+
12+
Providing your own IdentityServer
13+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
14+
15+
16+
17+
All you need to do to hook into your own IdentityServer is add the following to your ConfigureServices method.
18+
19+
.. code-block:: csharp
20+
21+
public virtual void ConfigureServices(IServiceCollection services)
22+
{
23+
Action<IdentityServerAuthenticationOptions> options = o => {
24+
// o.Authority = ;
25+
// o.ApiName = ;
26+
// etc....
27+
};
28+
29+
services
30+
.AddOcelot()
31+
.AddAdministration("/administration", options);
32+
}
33+
34+
You now need to get a token from your IdentityServer and use in subsequent requests to Ocelot's administration API.
35+
36+
This feature was implemented for `issue 228 <https://github.com/ThreeMammals/Ocelot/issues/228>`_. It is useful because the IdentityServer authentication middleware needs the URL of the IdentityServer. If you are using the internal IdentityServer it might not alaways be possible to have the Ocelot URL.
37+
38+
Internal IdentityServer
39+
^^^^^^^^^^^^^^^^^^^^^^^
40+
41+
The API is authenticated using bearer tokens that you request from Ocelot iteself. This is provided by the amazing `Identity Server <https://github.com/IdentityServer/IdentityServer4>`_ project that I have been using for a few years now. Check them out.
42+
43+
In order to enable the administration section you need to do a few things. First of all add this to yourinitial Startup.cs.
44+
45+
The path can be anything you want and it is obviously reccomended don't usea url you would like to route through with Ocelot as this will not work. The administration uses theMapWhen functionality of asp.net core and all requests to {root}/administration will be sent there not to the Ocelot middleware.
46+
47+
The secret is the client secret that Ocelot's internal IdentityServer will use to authenticate requests to the administration API. This can be whatever you want it to be!
48+
49+
.. code-block:: csharp
50+
51+
public virtual void ConfigureServices(IServiceCollection services)
52+
{
53+
services
54+
.AddOcelot()
55+
.AddAdministration("/administration", "secret");
56+
}
57+
58+
In order for the administration API to work, Ocelot / IdentityServer must be able to call itself for validation. This means that you need to add the base url of Ocelot to global configuration if it is not default (http://localhost:5000). Please note if you are using something like docker to host Ocelot it might not be able to call back to localhost etc and you need to know what you are doing with docker networking in this scenario. Anyway this can be done as follows..
59+
60+
If you want to run on a different host and port locally..
61+
62+
.. code-block:: json
63+
64+
"GlobalConfiguration": {
65+
"BaseUrl": "http://localhost:55580"
66+
}
67+
68+
or if Ocelot is exposed via dns
69+
70+
.. code-block:: json
71+
72+
"GlobalConfiguration": {
73+
"BaseUrl": "http://mydns.com"
74+
}
75+
76+
Now if you went with the configuration options above and want to access the API you can use the postman scriptscalled ocelot.postman_collection.json in the solution to change the Ocelot configuration. Obviously these will need to be changed if you are running Ocelot on a different url to http://localhost:5000.
77+
78+
79+
The scripts show you how to request a bearer token from ocelot and then use it to GET the existing configuration and POST a configuration.
80+
81+
If you are running multiple Ocelot instances in a cluster then you need to use a certificate to sign the bearer tokens used to access the administration API.
82+
83+
In order to do this you need to add two more environmental variables for each Ocelot in the cluster.
84+
85+
``OCELOT_CERTIFICATE``
86+
The path to a certificate that can be used to sign the tokens. The certificate needs to be of the type X509 and obviously Ocelot needs to be able to access it.
87+
``OCELOT_CERTIFICATE_PASSWORD``
88+
The password for the certificate.
89+
90+
Normally Ocelot just uses temporary signing credentials but if you set these environmental variables then it will use the certificate. If all the other Ocelot instances in thecluster have the same certificate then you are good!
91+
92+
93+
Administration API
94+
^^^^^^^^^^^^^^^^^^
95+
96+
**POST {adminPath}/connect/token**
97+
98+
This gets a token for use with the admin area using the client credentials we talk about setting above. Under the hood this calls into an IdentityServer hosted within Ocelot.
99+
100+
The body of the request is form-data as follows
101+
102+
``client_id`` set as admin
103+
104+
``client_secret`` set as whatever you used when setting up the administration services.
105+
106+
``scope`` set as admin
107+
108+
``grant_type`` set as client_credentials
109+
110+
**GET {adminPath}/configuration**
111+
112+
113+
This gets the current Ocelot configuration. It is exactly the same JSON we use to set Ocelot up with in the first place.
114+
115+
**POST {adminPath}/configuration**
116+
117+
This overrwrites the existing configuration (should probably be a put!). I reccomend getting your config from the GET endpoint, making any changes and posting it back...simples.
118+
119+
The body of the request is JSON and it is the same format as the FileConfiguration.cs that we use to set up
120+
Ocelot on a file system.
121+
122+
Please note that if you want to use this API then the process running Ocelot must have permission to write to the disk where your ocelot.json or ocelot.{environment}.json is located. This is because Ocelot will overwrite them on save.
123+
124+
**DELETE {adminPath}/outputcache/{region}**
125+
126+
This clears a region of the cache. If you are using a backplane it will clear all instances of the cache! Giving your the ability to run a cluster of Ocelots and cache over all of them in memory and clear them all at the same time / just use a distributed cache.
127+
128+
The region is whatever you set against the Region field in the FileCacheOptions section of the Ocelot configuration.

0 commit comments

Comments
 (0)