mirror of
https://github.com/nsnail/Ocelot.git
synced 2025-04-20 17:42:50 +08:00
updated docs to advise you need Ocelot.Administration when using admin API (#552)
This commit is contained in:
Tom Pallister
GitHub
parent
18ded25b0e
commit
e909cf9ce7
@ -1,133 +1,139 @@
|
|||||||
Administration
|
Administration
|
||||||
==============
|
==============
|
||||||
|
|
||||||
Ocelot supports changing configuration during runtime via an authenticated HTTP API. This can be authenticated in two ways either using Ocelot's
|
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
|
internal IdentityServer (for authenticating requests to the administration API only) or hooking the administration API authentication into your own
|
||||||
IdentityServer.
|
IdentityServer.
|
||||||
|
|
||||||
Providing your own IdentityServer
|
The first thing you need to do if you want to use the administration API is bring in the relavent NuGet package..
|
||||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
||||||
|
``Install-Package Ocelot.Administration``
|
||||||
All you need to do to hook into your own IdentityServer is add the following to your ConfigureServices method.
|
|
||||||
|
This will bring down everything needed by the admin API.
|
||||||
.. code-block:: csharp
|
|
||||||
|
Providing your own IdentityServer
|
||||||
public virtual void ConfigureServices(IServiceCollection services)
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||||
{
|
|
||||||
Action<IdentityServerAuthenticationOptions> options = o => {
|
All you need to do to hook into your own IdentityServer is add the following to your ConfigureServices method.
|
||||||
// o.Authority = ;
|
|
||||||
// o.ApiName = ;
|
.. code-block:: csharp
|
||||||
// etc....
|
|
||||||
};
|
public virtual void ConfigureServices(IServiceCollection services)
|
||||||
|
{
|
||||||
services
|
Action<IdentityServerAuthenticationOptions> options = o => {
|
||||||
.AddOcelot()
|
// o.Authority = ;
|
||||||
.AddAdministration("/administration", options);
|
// o.ApiName = ;
|
||||||
}
|
// etc....
|
||||||
|
};
|
||||||
You now need to get a token from your IdentityServer and use in subsequent requests to Ocelot's administration API.
|
|
||||||
|
services
|
||||||
This feature was implemented for `issue 228 <https://github.com/TomPallister/Ocelot/issues/228>`_. It is useful because the IdentityServer authentication
|
.AddOcelot()
|
||||||
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.
|
.AddAdministration("/administration", options);
|
||||||
|
}
|
||||||
Internal IdentityServer
|
|
||||||
^^^^^^^^^^^^^^^^^^^^^^^
|
You now need to get a token from your IdentityServer and use in subsequent requests to Ocelot's administration API.
|
||||||
|
|
||||||
The API is authenticated using bearer tokens that you request from Ocelot iteself. This is provided by the amazing
|
This feature was implemented for `issue 228 <https://github.com/TomPallister/Ocelot/issues/228>`_. It is useful because the IdentityServer authentication
|
||||||
`Identity Server <https://github.com/IdentityServer/IdentityServer4>`_ project that I have been using for a few years now. Check them out.
|
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.
|
||||||
|
|
||||||
In order to enable the administration section you need to do a few things. First of all add this to your
|
Internal IdentityServer
|
||||||
initial Startup.cs.
|
^^^^^^^^^^^^^^^^^^^^^^^
|
||||||
|
|
||||||
The path can be anything you want and it is obviously reccomended don't use
|
The API is authenticated using bearer tokens that you request from Ocelot iteself. This is provided by the amazing
|
||||||
a url you would like to route through with Ocelot as this will not work. The administration uses the
|
`Identity Server <https://github.com/IdentityServer/IdentityServer4>`_ project that I have been using for a few years now. Check them out.
|
||||||
MapWhen functionality of asp.net core and all requests to {root}/administration will be sent there not
|
|
||||||
to the Ocelot middleware.
|
In order to enable the administration section you need to do a few things. First of all add this to your
|
||||||
|
initial Startup.cs.
|
||||||
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!
|
|
||||||
|
The path can be anything you want and it is obviously reccomended don't use
|
||||||
.. code-block:: csharp
|
a url you would like to route through with Ocelot as this will not work. The administration uses the
|
||||||
|
MapWhen functionality of asp.net core and all requests to {root}/administration will be sent there not
|
||||||
public virtual void ConfigureServices(IServiceCollection services)
|
to the Ocelot middleware.
|
||||||
{
|
|
||||||
services
|
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!
|
||||||
.AddOcelot()
|
|
||||||
.AddAdministration("/administration", "secret");
|
.. code-block:: csharp
|
||||||
}
|
|
||||||
|
public virtual void ConfigureServices(IServiceCollection services)
|
||||||
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). This can be done as follows..
|
services
|
||||||
|
.AddOcelot()
|
||||||
If you want to run on a different host and port locally..
|
.AddAdministration("/administration", "secret");
|
||||||
|
}
|
||||||
.. code-block:: json
|
|
||||||
|
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
|
||||||
"GlobalConfiguration": {
|
to global configuration if it is not default (http://localhost:5000). This can be done as follows..
|
||||||
"BaseUrl": "http://localhost:55580"
|
|
||||||
}
|
If you want to run on a different host and port locally..
|
||||||
|
|
||||||
or if Ocelot is exposed via dns
|
.. code-block:: json
|
||||||
|
|
||||||
.. code-block:: json
|
"GlobalConfiguration": {
|
||||||
|
"BaseUrl": "http://localhost:55580"
|
||||||
"GlobalConfiguration": {
|
}
|
||||||
"BaseUrl": "http://mydns.com"
|
|
||||||
}
|
or if Ocelot is exposed via dns
|
||||||
|
|
||||||
Now if you went with the configuration options above and want to access the API you can use the postman scripts
|
.. code-block:: json
|
||||||
called 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.
|
"GlobalConfiguration": {
|
||||||
|
"BaseUrl": "http://mydns.com"
|
||||||
|
}
|
||||||
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.
|
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. Obviously these
|
||||||
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.
|
will need to be changed if you are running Ocelot on a different url to http://localhost:5000.
|
||||||
|
|
||||||
In order to do this you need to add two more environmental variables for each Ocelot in the cluster.
|
|
||||||
|
The scripts show you how to request a bearer token from ocelot and then use it to GET the existing configuration and POST
|
||||||
``OCELOT_CERTIFICATE``
|
a configuration.
|
||||||
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.
|
|
||||||
``OCELOT_CERTIFICATE_PASSWORD``
|
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.
|
||||||
The password for the certificate.
|
|
||||||
|
In order to do this you need to add two more environmental variables for each Ocelot in the cluster.
|
||||||
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!
|
|
||||||
|
``OCELOT_CERTIFICATE``
|
||||||
|
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.
|
||||||
Administration API
|
``OCELOT_CERTIFICATE_PASSWORD``
|
||||||
^^^^^^^^^^^^^^^^^^
|
The password for the certificate.
|
||||||
|
|
||||||
**POST {adminPath}/connect/token**
|
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!
|
||||||
|
|
||||||
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.
|
|
||||||
|
Administration API
|
||||||
The body of the request is form-data as follows
|
^^^^^^^^^^^^^^^^^^
|
||||||
|
|
||||||
``client_id`` set as admin
|
**POST {adminPath}/connect/token**
|
||||||
|
|
||||||
``client_secret`` set as whatever you used when setting up the administration services.
|
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.
|
||||||
|
|
||||||
``scope`` set as admin
|
The body of the request is form-data as follows
|
||||||
|
|
||||||
``grant_type`` set as client_credentials
|
``client_id`` set as admin
|
||||||
|
|
||||||
**GET {adminPath}/configuration**
|
``client_secret`` set as whatever you used when setting up the administration services.
|
||||||
|
|
||||||
|
``scope`` set as admin
|
||||||
This gets the current Ocelot configuration. It is exactly the same JSON we use to set Ocelot up with in the first place.
|
|
||||||
|
``grant_type`` set as client_credentials
|
||||||
**POST {adminPath}/configuration**
|
|
||||||
|
**GET {adminPath}/configuration**
|
||||||
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.
|
|
||||||
|
|
||||||
The body of the request is JSON and it is the same format as the FileConfiguration.cs that we use to set up
|
This gets the current Ocelot configuration. It is exactly the same JSON we use to set Ocelot up with in the first place.
|
||||||
Ocelot on a file system.
|
|
||||||
|
**POST {adminPath}/configuration**
|
||||||
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.
|
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.
|
||||||
|
|
||||||
**DELETE {adminPath}/outputcache/{region}**
|
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.
|
||||||
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.
|
|
||||||
|
Please note that if you want to use this API then the process running Ocelot must have permission to write to the disk
|
||||||
The region is whatever you set against the Region field in the FileCacheOptions section of the Ocelot configuration.
|
where your ocelot.json or ocelot.{environment}.json is located. This is because Ocelot will overwrite them on save.
|
||||||
|
|
||||||
|
**DELETE {adminPath}/outputcache/{region}**
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
The region is whatever you set against the Region field in the FileCacheOptions section of the Ocelot configuration.
|
||||||
|
|||||||
Loading…
x
Reference in New Issue
Block a user