From 24ee4f6870283066f9ef4ba92757f1ca044ab726 Mon Sep 17 00:00:00 2001 From: TomPallister Date: Sat, 5 Nov 2016 13:39:50 +0000 Subject: [PATCH] half decent readme --- README.md | 113 ++++++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 105 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index 06ff1e18..5674cac0 100644 --- a/README.md +++ b/README.md @@ -19,6 +19,11 @@ to handle the IdentityServer reference tokens. We would rather use the IdentityServer code that already exists to do this. +## Contributing + +Pull requests, issues and commentary welcome! No special process just create a request and get in +touch either via gitter or create an issue. + ## How to install Ocelot is designed to work with ASP.NET core only and is currently @@ -122,23 +127,108 @@ in the future with an options to make Ocelot case sensitive per ReRoute. ## Authentication -TBC... +Ocelot currently supports the use of bearer tokens with Identity Server (more providers to +come if required). In order to identity a ReRoute as authenticated it needs the following +configuration added. + + "AuthenticationOptions": { + "Provider": "IdentityServer", + "ProviderRootUrl": "http://localhost:52888", + "ScopeName": "api", + "AdditionalScopes": [ + "openid", + "offline_access" + ], + "ScopeSecret": "secret" + } + +In this example the Provider is specified as IdentityServer. This string is important +because it is used to identity the authentication provider (as previously mentioned in +the future there might be more providers). Identity server requires that the client +talk to it so we need to provide the root url of the IdentityServer as ProviderRootUrl. +IdentityServer requires at least one scope and you can also provider additional scopes. +Finally if you are using IdentityServer reference tokens you need to provide the scope +secret. + +Ocelot will use this configuration to build an authentication handler and if +authentication is succefull the next middleware will be called else the response +is 401 unauthorised. ## Authorisation -TBC... +Ocelot supports claims based authorisation which is run post authentication. This means if +you have a route you want to authorise you can add the following to you ReRoute configuration. -## Claims to Headers Tranformation + "RouteClaimsRequirement": { + "UserType": "registered" + }, -TBC... +In this example when the authorisation middleware is called Ocelot will check to see +if the user has the claim type UserType and if the value of that claim is registered. +If it isn't then the user will not be authorised and the response will be 403 forbidden. -## Claims to Claims Tranformation +## Claims Tranformation -TBC... +Ocelot allows the user to access claims and transform them into headers, query string +parameters and other claims. This is only available once a user has been authenticated. -## Claims to Query String Parameters Tranformation +After the user is authenticated we run the claims to claims transformation middleware. +This allows the user to transform claims before the authorisation middleware is called. +After the user is authorised first we call the claims to headers middleware and Finally +the claims to query strig parameters middleware. -TBC... +The syntax for performing the transforms is the same for each proces. In the ReRoute +configuration a json dictionary is added with a specific name either AddClaimsToRequest, +AddHeadersToRequest, AddQueriesToRequest. + +Note I'm not a hotshot programmer so have no idea if this syntax is good.. + +Within this dictionary the entries specify how Ocelot should transform things! +The key to the dictionary is going to become the key of either a claim, header +or query parameter. + +The value of the entry is parsed to logic that will perform the transform. First of +all a dictionary accessor is specified e.g. Claims[CustomerId]. This means we want +to access the claims and get the CustomerId claim type. Next is a greater than (>) +symbol which is just used to split the string. The next entry is either value or value with +and indexer. If value is specifed Ocelot will just take the value and add it to the +transform. If the value has an indexer Ocelot will look for a delimiter which is provided +after another greater than symbol. Ocelot will then split the value on the delimiter +and add whatever was at the index requested to the transform. + +#### Claims to Claims Tranformation + +Below is an example configuration that will transforms claims to claims + + "AddClaimsToRequest": { + "UserType": "Claims[sub] > value[0] > |", + "UserId": "Claims[sub] > value[1] > |" + }, + +This shows a transforms where Ocelot looks at the users sub claim and transforms it into +UserType and UserId claims. Assuming the sub looks like this "usertypevalue|useridvalue". + +#### Claims to Headers Tranformation + +Below is an example configuration that will transforms claims to headers + + "AddHeadersToRequest": { + "CustomerId": "Claims[sub] > value[1] > |" + }, + +This shows a transform where Ocelot looks at the users sub claim and trasnforms it into a +CustomerId header. Assuming the sub looks like this "usertypevalue|useridvalue". + +#### Claims to Query String Parameters Tranformation + +Below is an example configuration that will transforms claims to query string parameters + + "AddQueriesToRequest": { + "LocationId": "Claims[LocationId] > value", + }, + +This shows a transform where Ocelot looks at the users LocationId claim and add its as +a query string parameter to be forwarded onto the downstream service. ## Logging @@ -199,6 +289,13 @@ header. Sorry if this doesn't work for your use case! + Fowarding a host header - The host header that you send to Ocelot will not be forwarded to the downstream service. Obviously this would break everything :( +## Things that are currently annoying means + ++ The ReRoute configuration object is too large. + ++ The base OcelotMiddleware lets you access things that are going to be null +and doesnt check the response is OK. I think the fact you can even call stuff +that isnt available is annoying. Let alone it be null. ## Coming up