You can integrate your solutions with Ditto
- via the HTTP API or
- via WebSocket.
On all APIs Ditto protects functionality and data by using
- Authentication to make sure the requester is the one he/she claims to be,
- Authorization to make sure the requester is allowed to see, use or change the information he wants to access.
Authentication
User authentication at the HTTP API
A user who calls the HTTP API can be authenticated using two mechanisms:
- Pre-authentication by an HTTP reverse proxy in front of Ditto, e.g. doing HTTP BASIC Authentication by providing username and password as documented in the installation/operation guide.
- A JWT issued by Google or other OpenID Connect providers as documented in the installation/operation guide.
Authenticated subjects
Every request to one of Ditto’s API is done in scope of already authenticated subjects.
This authentication may be provided via nginx (like mentioned above), a
JWT or in a connection via the
configured authorizationContext
in scope of the connection’s authorization.
For each of the possibilities of authenticating subjects, the command or message processed by Ditto will contain one or more of the “authenticated subjects” which e.g. might be user IDs.
Single sign-on (SSO)
By configuring an arbitrary OpenID Connect provider (as mentioned above) it is possible for Ditto to participate in SSO for the following browser based requests:
- HTTP API invocations
- sending along a JWT token as
Authorization
header withBearer
value
- sending along a JWT token as
- Establishing a WebSocket connection for bidirectional communication with
Ditto via Ditto Protocol JSON messages
- sending along a JWT token as
Authorization
header withBearer
value (recommended) - sending along a JWT token as query parameter
access_token
(use only if the websocket client does not support setting http headers e.g. plain WebSocket API of browsers)
- sending along a JWT token as
- Opening a Server sent event connection in order to receive change notifications of twins in the
browser
- passing the
withCredentials: true
option when creating the SSE in the browser
- passing the
Authorization
Authorization is implemented with a Policy (in API version 2).
Please find details at Policies.
Authorization Context in DevOps Commands
An authorizationContext
which is passed to DevOps Commands needs
to be a subject known to Ditto’s authentication. In the simplest case, it’s nginx:{username}
where {username}
is a user
that is configured for basic auth in the included nginx’s nginx.htpasswd
file (where the nginx:
prefix comes from).
If you are using the provided docker quickstart example from Getting Started you
can simply use nginx:ditto
, then the commands that are passed from the connection are executed as if they
were issued via HTTP from the user ditto
.