You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardexpand all lines: README.md
+17-21
Original file line number
Diff line number
Diff line change
@@ -6,7 +6,7 @@
6
6
7
7
# Ocelot
8
8
9
-
Ocelot is a .NET API Gateway. This project is aimed at people using .NET running a micro services / serviceoriented architecture
9
+
Ocelot is a .NET API Gateway. This project is aimed at people using .NET running a microservices / service-oriented architecture
10
10
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.
11
11
12
12
In particular I want easy integration with IdentityServer reference and bearer tokens.
@@ -15,7 +15,11 @@ We have been unable to find this in my current workplace without having to write
15
15
16
16
Ocelot is a bunch of middlewares in a specific order.
17
17
18
-
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!
18
+
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.
19
+
The middleware that makes the request is the last thing in the Ocelot pipeline. It does not call the next middleware.
20
+
The response from the downstream service is retrieved as the requests goes back up the Ocelot pipeline.
21
+
There is a piece of middleware that maps the `HttpResponseMessage` onto the `HttpResponse` object and that is returned to the client.
22
+
That is basically it with a bunch of other features!
19
23
20
24
## Features
21
25
@@ -39,19 +43,21 @@ A quick list of Ocelot's capabilities for more information see the [documentatio
39
43
* Configuration / Administration REST API
40
44
* Platform / Cloud Agnostic
41
45
42
-
## How to install
46
+
## Install
43
47
44
48
Ocelot is designed to work with ASP.NET and it targets `net7.0`.
45
49
46
-
Install Ocelot and it's dependencies using NuGet.
50
+
Install Ocelot and its dependencies using NuGet Package Manager:
51
+
```powershell
52
+
Install-Package Ocelot
53
+
```
47
54
48
-
`Install-Package Ocelot`
55
+
Or via the .NET CLI:
56
+
```shell
57
+
dotnet add package Ocelot
58
+
```
49
59
50
-
Or via the .NET Core CLI:
51
-
52
-
`dotnet add package ocelot`
53
-
54
-
All versions can be found [here](https://www.nuget.org/packages/Ocelot/)
60
+
All versions can be found [here](https://www.nuget.org/packages/Ocelot/).
55
61
56
62
## Documentation
57
63
@@ -67,16 +73,6 @@ We love to receive contributions from the community so please keep them coming :
67
73
68
74
Pull requests, issues and commentary welcome!
69
75
70
-
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 :)
76
+
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 in case 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 :)
71
77
72
78
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 :)
73
-
74
-
## Donate
75
-
76
-
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.
77
-
78
-
[](https://www.paypal.me/ThreeMammals/)
79
-
80
-
## Things that are currently annoying me
81
-
82
-
[ Get more details at **codescene.io**.](https://codescene.io/projects/697/jobs/latest-successful/results)
Copy file name to clipboardexpand all lines: docs/building/building.rst
+4-3
Original file line number
Diff line number
Diff line change
@@ -3,8 +3,9 @@ Building
3
3
4
4
* You can also just run `dotnet tool restore && dotnet cake` locally!. Output will got to the `./artifacts` directory.
5
5
6
-
* The best way to replicate the CI process is to build Ocelot locally is using the Dockerfile.build file which can be found in the docker folder in Ocelot root. Use the following command `docker build --platform linux/amd64 -f ./docker/Dockerfile.build .` for example. You will need to change the platform flag depending on your platform.
6
+
* The best way to replicate the CI process is to build Ocelot locally is using the Dockerfile.build file which can be found in the docker folder in Ocelot root.
7
+
Use the following command ``docker build --platform linux/amd64 -f ./docker/Dockerfile.build .`` for example. You will need to change the platform flag depending on your platform.
7
8
8
-
* There is a Makefile to make it easier to call the various targers in `build.cake`. The scripts are called with .sh but can be easily changed to ps1 if you are using Windows.
9
+
* There is a Makefile to make it easier to call the various targets in `build.cake`. The scripts are called with **.sh** but can be easily changed to **.ps1** if you are using Windows.
9
10
10
-
* Alternatively you can build the project in VS2022 with the latest .NET 7.0 SDK.
11
+
* Alternatively you can build the project in VS2022 with the latest .NET 7.0 SDK.
Copy file name to clipboardexpand all lines: docs/features/administration.rst
+38-25
Original file line number
Diff line number
Diff line change
@@ -3,16 +3,19 @@ Administration
3
3
4
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
5
6
-
The first thing you need to do if you want to use the administration API is bring in the relavent NuGet package..
6
+
The first thing you need to do if you want to use the administration API is bring in the relavent NuGet package:
7
7
8
-
``Install-Package Ocelot.Administration``
8
+
.. code-block:: powershell
9
9
10
-
This will bring down everything needed by the admin API.
10
+
Install-Package Ocelot.Administration
11
+
12
+
This will bring down everything needed by the administration API.
11
13
12
14
Providing your own IdentityServer
13
-
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
15
+
---------------------------------
14
16
15
-
All you need to do to hook into your own IdentityServer is add the following to your ConfigureServices method.
17
+
All you need to do to hook into your own IdentityServer is add the following configuration options with authentication to your ``ConfigureServices`` method.
18
+
After that we must pass these options to ``AddAdministration()`` extension of the ``OcelotBuilder`` being returned by ``AddOcelot()`` [#f1]_ like below:
16
19
17
20
.. code-block:: csharp
18
21
@@ -26,7 +29,7 @@ All you need to do to hook into your own IdentityServer is add the following to
26
29
{
27
30
ValidateAudience=false,
28
31
};
29
-
// etc....
32
+
// etc...
30
33
};
31
34
32
35
services
@@ -36,18 +39,21 @@ All you need to do to hook into your own IdentityServer is add the following to
36
39
37
40
You now need to get a token from your IdentityServer and use in subsequent requests to Ocelot's administration API.
38
41
39
-
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.
42
+
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.
43
+
If you are using the internal IdentityServer it might not always be possible to have the Ocelot URL.
40
44
41
45
Internal IdentityServer
42
-
^^^^^^^^^^^^^^^^^^^^^^^
46
+
-----------------------
43
47
44
-
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.
48
+
The API is authenticated using Bearer tokens that you request from Ocelot itself. 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.
45
49
46
-
In order to enable the administration section you need to do a few things. First of all add this to yourinitial Startup.cs.
50
+
In order to enable the administration section you need to do a few things. First of all add this to your initial **Startup.cs**.
47
51
48
-
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.
52
+
The path can be anything you want and it is obviously recommended don't use a URL you would like to route through with Ocelot as this will not work.
53
+
The administration uses the ``MapWhen`` functionality of ASP.NET Core and all requests to "**{root}/administration**" will be sent there not to the Ocelot middleware.
49
54
50
55
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!
56
+
In order to pass this secret string as parameter we must call the ``AddAdministration()`` extension of the ``OcelotBuilder`` being returned by ``AddOcelot()`` [#f1]_ like below:
51
57
52
58
.. code-block:: csharp
53
59
@@ -58,30 +64,33 @@ The secret is the client secret that Ocelot's internal IdentityServer will use t
58
64
.AddAdministration("/administration", "secret");
59
65
}
60
66
61
-
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..
67
+
In order for the administration API to work, Ocelot / IdentityServer must be able to call itself for validation.
68
+
This means that you need to add the base URL of Ocelot to global configuration if it is not default (http://localhost:5000).
69
+
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.
70
+
Anyway, this can be done as follows.
62
71
63
-
If you want to run on a different host and port locally..
72
+
If you want to run on a different host and port locally:
64
73
65
74
.. code-block:: json
66
75
67
76
"GlobalConfiguration": {
68
77
"BaseUrl": "http://localhost:55580"
69
78
}
70
79
71
-
or if Ocelot is exposed via dns
80
+
or if Ocelot is exposed via DNS:
72
81
73
82
.. code-block:: json
74
83
75
84
"GlobalConfiguration": {
76
85
"BaseUrl": "http://mydns.com"
77
86
}
78
87
79
-
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.
80
-
88
+
Now if you went with the configuration options above and want to access the API you can use the Postman scripts called **ocelot.postman_collection.json** in the solution to change the Ocelot configuration.
89
+
Obviously these will need to be changed if you are running Ocelot on a different URL to http://localhost:5000.
81
90
82
-
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.
91
+
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.
83
92
84
-
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
+
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.
85
94
86
95
In order to do this you need to add two more environmental variables for each Ocelot in the cluster.
87
96
@@ -90,11 +99,11 @@ In order to do this you need to add two more environmental variables for each Oc
90
99
``OCELOT_CERTIFICATE_PASSWORD``
91
100
The password for the certificate.
92
101
93
-
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!
94
-
102
+
Normally Ocelot just uses temporary signing credentials but if you set these environmental variables then it will use the certificate.
103
+
If all the other Ocelot instances in the cluster have the same certificate then you are good!
95
104
96
105
Administration API
97
-
^^^^^^^^^^^^^^^^^^
106
+
------------------
98
107
99
108
**POST {adminPath}/connect/token**
100
109
@@ -117,15 +126,19 @@ This gets the current Ocelot configuration. It is exactly the same JSON we use t
117
126
118
127
**POST {adminPath}/configuration**
119
128
120
-
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
+
This overwrites the existing configuration (should probably be a put!). I recommend getting your config from the GET endpoint, making any changes and posting it back...simples.
121
130
122
-
The body of the request is JSON and it is the same format as the FileConfiguration.cs that we use to set up
123
-
Ocelot on a file system.
131
+
The body of the request is JSON and it is the same format as the FileConfiguration.cs that we use to set up Ocelot on a file system.
124
132
125
-
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.
133
+
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.
134
+
This is because Ocelot will overwrite them on save.
126
135
127
136
**DELETE {adminPath}/outputcache/{region}**
128
137
129
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.
130
139
131
140
The region is whatever you set against the Region field in the FileCacheOptions section of the Ocelot configuration.
141
+
142
+
""""
143
+
144
+
.. [#f1] The ``AddOcelot`` method adds default ASP.NET services to DI-container. You could call another more extended ``AddOcelotUsingBuilder`` method while configuring services to build and use custom builder via an ``IMvcCoreBuilder`` interface object. See more instructions in :doc:`../features/dependencyinjection`, "**The AddOcelotUsingBuilder method**" section.
Copy file name to clipboardexpand all lines: docs/features/authentication.rst
+1-1
Original file line number
Diff line number
Diff line change
@@ -172,6 +172,6 @@ NOTE: In order to get Ocelot to view the scope claim from Okta properly, you hav
172
172
Allowed Scopes
173
173
^^^^^^^^^^^^^
174
174
175
-
If you add scopes to AllowedScopes Ocelot will get all the user claims (from the token) of the type scope and make sure that the user has all of the scopes in the list.
175
+
If you add scopes to AllowedScopes Ocelot will get all the user claims (from the token) of the type scope and make sure that the user has at least one of the scopes in the list.
176
176
177
177
This is a way to restrict access to a Route on a per scope basis.
0 commit comments