The shiny web world - a primer
This is work in progress
We are constantly working on improving Domino REST API's functionality and documentation. You have a documentation page which is not quite ready. Feel free to feedback what you would like to see here.
Communication between clients and servers require an address and a port (akin to building name and unit number). There is an official list to look at. In Notes/Domino land we usually deal with client access (1352), SMTP (25), http (80) and https(443).
Only one service can listen on a specific port at a given address. So when you have two web servers, only one can use the default ports.
The official port to protocol mapping serves as a simple shortcut when specifying destination locations:
http://someserver.com/is short for
https://someserver.com/is short for
The Domino REST API adds additional ports to be used. When a non-standard port is used, it can be any protocol, so
https://someserver.com:8880 is equally valid as
http://someserver.com:8880. Valid doesn't mean working. Which protocol responds depends on the server configuration.
Practical pranks you can play: reconfigure an http server, such as Domino's http task, to use port 443 for http and port 80 for https and watch the confusion. Don't do that to a production system.
key value pairs
JSON is a set of case-sentitive key-value pairs
The keys are strings and the values can be only a few data types: string, number, boolean, null, or JSON. Notably absent are integers and date/time formats or binary data.
The Domino REST API makes heavy use of the JSON based OpenAPI specification
JSON Web Token (JWT)
A JWT is a string with a fixed structure. It's composed of 3 strings in Base64 encoding joined by a
. (dot). When decoded, the first part is JSON describing the signature algorithm and token type. The second part is also JSON, providing the actual information, while the third part is a digital signature.
JWT are not encrypted, so they are not suitable to carry confidential information.
- The signature "only" guarantees that the token hasn't been altered since signing.
- For verification, you need access to the public key of the signer. For more information, see OAuth.
- The actual information could be anything JSON, but has defined elements like issue date and expiry when used as access token.
There is more to learn about JWT, including an easy tool to check.
JWT is often used, including in the Domino REST API, as Access Tokens to gain authorized access to a server. To serve as an access token, it gets presented with the Authorization http(s) header as
Bearer [JWT Token].
A reasonable good analogy:
The JWT token is your concert ticket. At the entrance of the concert hall, security checks if the ticket is valid. They don't care how you did get it: ordered online, queued at the ticket booth, got it from an authorized reseller or won it from the local radio morning show. They only care if it's genuine.
The same principle applies to JWT as access token. As long as the token is signed by a trusted issuer, commonly referred to as an Identity Provider or IdP, and is still valid, security lets you through. Of course, a valid "Adele" ticket won't get you into the "Taylor Swift" concert, so the content of the ticket matters.
From the official documentation
OAuth 2.0 is the industry-standard protocol for authorization. OAuth 2.0 focuses on client developer simplicity while providing specific authorization flows for web applications, desktop applications, mobile phones, and living room devices. This specification and its extensions are being developed within the IETF OAuth Working Group.
In OAuth, two parties are usually involved. One is an Identity Provider (IdP), the place you log in and consent, and the other is a Service Provider (SP), the application that does the actual work.
In an OAuth sequence, (colloquially referred to as OAuth dance) to obtain permission to act on a user's behalf (called an OAuth grant), the users get directed to the IdP, where, after authentication, they're asked for consent that the application (the SP) acts on their behalf (the exact flow depends on the grant type).
The result of the dance is at least an access token and quite commonly a refresh token. The application uses the access token for interaction with the API. Ideally, access tokens are short lived, minutes rather than hours. On expiration, the application would use the refresh token to obtain a new access token without the need of user interaction. Refresh tokens can be issued with long validity, ranging from days, weeks, or months. If a refresh token is suspected to be compromised, it can be invalidated, so obtaining a new access token would fail and trigger the consent dialogue.
Lots to learn
Make sure to learn more about this complex topic!
Certificates (nothing new to Notes people, we had them in the
notes.id for decades) in the internet world come in three flavors:
- Issued by a recognized certificate authority CA like LetsEncypt
- Issued by a private or unrecognized CA
- Self signed
Don't self sign
Sounds like easy for test system, not worth the headache, go for your own private CA
The important term here is recognized. All browsers ship with a list of recognized CA, by having a copy of their Public keys. One can amend this list by adding or removing public keys, something one better leaves to automated tooling.
When dealing with other clients, for example your venerable Tomcat, the known CA list in the browser doesn't help. You need to add the cert where the application can find it. For example for Java, that's the Java keystore (remember keytool).
If you use self-signed (please don't), you have to add each and every cert to all the clients, using a private CA, only the CA's public keys.
There is much to learn, worth your time.
TLS, SSL & HTTP/2
Any application available on the intranet or internet needs secure communication. The standard means for that is TLS - Transport-Layer-Security. Colloquially, the term SSL is used with cert vendors, but implementation is almost always TLS - and should be. SSL is considered compromisable.
Use a wildcard cert for internal systems
Obtain a wildcard cert (*.yourdomain.net) using an internet facing system and use it for the internsl systems too. Does require proper local DNS setup
The current prevalent version of HTTP is HTTP1.1, a standard introduced last century (1995). Modern browsers (read: no IE) and contemporary web servers support HTTP/2. HTTP/2 requires a TLS connection, so you can't try it out using
http://localhost. The Domino REST API uses HTTP/2 if a client supports it. All browsers do, but at the time of writing, Postman didn't.
HTTP/2 offers better security and shorter response times.
The OpenAPI specification describes in a standardized way what to expect from an API. The specification, expressed in JSON or YAML, is both machine readable and human readable (using a UI). It defines:
- The available endpoint URLs and supported methods
- Authentication required if any
- mandatory and optional parameters
- data formats to expect or provide
- external meta data
There is a rich eco system of tooling that allows to produce or consume OpenAPI specifications, here's just a small selection:
- UI to read and try the specs: Swagger UI and ReDoc
- UI to create and edit: Apicurio Studio and Swagger Editor
- Tools to generate code from a spec
- Libraries that consume a spec, create routes and enforce the defined constrains. For example Java, NodeJS, Python. There are many more.