Skip to content

Commit

Permalink
flowchart redirect to github.com
Browse files Browse the repository at this point in the history
  • Loading branch information
@AndrewDonkin-Gallagher
AndrewDonkin-Gallagher committed Dec 1, 2023
1 parent 6609917 commit 45bf974
Showing 1 changed file with 70 additions and 66 deletions.
136 changes: 70 additions & 66 deletions training/rest_training.adoc
View file
Original file line number Diff line number Diff line change
@@ -1,4 +1,5 @@
= Command Centre REST API training material
// Github does not render a table of contents in a frame on the left. But Asciidoctor does, so:
:toc: left
:source-highlighter: rouge
// highlighters are coderay highlight.js Pygments rouge. Asciidoctor ships with highlight.js, but
Expand All @@ -22,9 +23,7 @@
// Editors, please stick to a maximum line length of 100.

[.lead]
WORK IN PROGRESS.

This document is an AsciiDoc port of a document used internally at Gallagher Group to train
This document is used internally at Gallagher Group to train
developers in the use of Command Centre’s REST API. This version is not yet suitable for
publication, but if you are using the REST API, and like the sound of 60-odd more pages of reading
material, and are tolerant of casual language and a choppy structure meant to help a live speaker
Expand Down Expand Up @@ -1220,14 +1219,73 @@ your integration.

=== The request process

This is shown in a
https://github.com/GallagherSecurity/cc-rest-docs/blob/master/training/auth_flow.md[rough
flowchart].
All HTTPS requests start like this:

[arabic]
. The client and server establish an encrypted channel. Part of that is
a certificate exchange. The channel makes the following conversation
safe from eavesdroppers but does not confirm the identity of either
side.
. Unless you have configured your client not to, it verifies the
identity of the server (authenticates it) by examining the contents of
the certificate that came from the server during the previous step. If
the client does not like the certificate that came from the server, it
drops the connection. Command Centre will complain to its log file when
this happens but because it did not receive a request, will not create
an event.
. If the client trusts the server it sends its request along with a
secret that proves it is who it says it is. In our case that is an HTTP
header containing the API key.

So far that has been a normal HTTPS conversation, the same as what
happens with every web site you visit in a browser. From here on is
specific to Command Centre.

[arabic, start=4]
. The server looks for the API key in the `Authorization` header and
finds the matching REST Client (footnote: capitalised to mean the
configuration item in Command Centre, not the REST client software on
the other end of the TCP connection) in the database. If it cannot find
one, it will raise an alarm "A REST connection was attempted with an
invalid API key".
. If you did not disable pinned client certificates in the server
properties (Web Services tab), or if you are running 8.50 and the REST
Client item has a thumbprint on it (in the API Key tab), it checks the
thumbprint of the request’s certificate against the one on the REST
Client item. If they do not match, it responds with a 401 and raises an
alarm "A REST connection was attempted with an invalid client
certificate". The server does not check the client certificate’s chain
of trust. <<Client-side certificates>> has all the
details of why you would want your server to check client certificates
and how to create them.
. It checks the source host’s IP number against the REST Client item’s
IP filters. If it does not match, it responds with a 401 and raises an
alarm "A REST connection was refused because of the connecting IP
address does not match the IP filter on the REST Client __name of your
REST Client__".
. It checks that it has a license for the controller that will handle
the request. If it does not, it sends a 403 response containing the
string "Feature not licensed".
. It creates a new session for the operator, if there isn’t one ready,
then compares what the request is asking for against the REST Client’s
operator’s privileges from the session. If the privileges do not allow
the operation that the client requested, the server will respond with a
400-level error and a message in the body.

If all those steps succeed, the API controller processes the request,
logs an operator event if something changed, and returns a result.

In chart form, it looks like this:

(if looks like a

[source,mermaid]
....
flowchart TD
%% Since you are reading this, the flowchart has not rendered. Please try
%% https://github.com/GallagherSecurity/cc-rest-docs/blob/master/training/rest_training.adoc#the-request-process
classDef red fill:#ff9090
o_noapikey([Raise invalid API key alarm,\nreturn 401]):::red
o_needacert(["Raise alarm\n'client item needs a thumbprint',\nreturn 401"]):::red
Expand Down Expand Up @@ -1300,66 +1358,9 @@ flowchart TD
....


All HTTPS requests start like this:

[arabic]
. The client and server establish an encrypted channel. Part of that is
a certificate exchange. The channel makes the following conversation
safe from eavesdroppers but does not confirm the identity of either
side.
. Unless you have configured your client not to, it verifies the
identity of the server (authenticates it) by examining the contents of
the certificate that came from the server during the previous step. If
the client does not like the certificate that came from the server, it
drops the connection. Command Centre will complain to its log file when
this happens but because it did not receive a request, will not create
an event.
. If the client trusts the server it sends its request along with a
secret that proves it is who it says it is. In our case that is an HTTP
header containing the API key.

So far that has been a normal HTTPS conversation, the same as what
happens with every web site you visit in a browser. From here on is
specific to Command Centre.

[arabic, start=4]
. The server looks for the API key in the `Authorization` header and
finds the matching REST Client (footnote: capitalised to mean the
configuration item in Command Centre, not the REST client software on
the other end of the TCP connection) in the database. If it cannot find
one, it will raise an alarm "A REST connection was attempted with an
invalid API key".
. If you did not disable pinned client certificates in the server
properties (Web Services tab), or if you are running 8.50 and the REST
Client item has a thumbprint on it (in the API Key tab), it checks the
thumbprint of the request’s certificate against the one on the REST
Client item. If they do not match, it responds with a 401 and raises an
alarm "A REST connection was attempted with an invalid client
certificate". The server does not check the client certificate’s chain
of trust. <<Client-side certificates>> has all the
details of why you would want your server to check client certificates
and how to create them.
. It checks the source host’s IP number against the REST Client item’s
IP filters. If it does not match, it responds with a 401 and raises an
alarm "A REST connection was refused because of the connecting IP
address does not match the IP filter on the REST Client __name of your
REST Client__".
. It checks that it has a license for the controller that will handle
the request. If it does not, it sends a 403 response containing the
string "Feature not licensed".
. It creates a new session for the operator, if there isn’t one ready,
then compares what the request is asking for against the REST Client’s
operator’s privileges from the session. If the privileges do not allow
the operation that the client requested, the server will respond with a
400-level error and a message in the body.

If all those steps succeed, the API controller processes the request,
logs an operator event if something changed, and returns a result.

The alarms above have a default priority of medium-high. The server
raises them for two reasons: while developing, it is useful to have a
little more diagnosis coming out of the server, and in production, it is
good to know when your API is being probed.
The alarms raised in the red terminal states above have a default priority of medium-high. The
server raises them for two reasons: while developing, it is useful to have a little more diagnosis
coming out of the server, and in production, it is good to know when your API is being probed.

If too many bad requests arrive too quickly, the server will assume it
is under attack and will log an alarm at maximum priority, then will
Expand All @@ -1368,6 +1369,9 @@ remain silent on the matter until the attack stops.
Errors also go to
`%PROGRAMDATA%\Gallagher\Command Centre\Command_centre.log`.

Unless the client rejected the server's certificate and dropped the connection before sending
anything, the request will also go to `%PROGRAMDATA%\Gallagher\Command Centre\RESTAccess.log`.

== First POST and search

=== Create a cardholder
Expand Down

0 comments on commit 45bf974

Please sign in to comment.