Endpoints and their URLs
Overview of an Endpoint
An endpoint is something that is used quite a lot in Curity and is referred to throughout the documentation, tutorials, and videos. The concept of an endpoint is probably understood by all developers and admins working with Curity; however, the product does some novel things with endpoints that need to be understood. For instance, you should be aware that:
- The URI or path part of the endpoint is configurable in Curity. This means that the actual URI that is used in any endpoint can be set to whatever value is desired. For instance, a token endpoint can be served from
/foobar; this creates more deployment options (e.g., you can use
/tenant1/tokenas well as
/tenant2/token); helps with backward compatibility when a pre-existing service is being replaced by Curity; and also obscures the usage of Curity.
- Endpoints are hosted on nodes or run-time servers. This "binding" of endpoints to a node is how configuration is deployed. Before an endpoint is actually configured to be served by a node, it is unavailable to any client application.
- Endpoints can be deployed "asymmetrically" in a cluster. In other words, not every node in a cluster has to host every endpoint. This is a very helpful capability for creating secure enclaves.
- Endpoints can have sub-paths or subroutes that are not configurable. These are subpaths like
logoutunder an authenticate endpoint or
Usersunder a user management's API endpoint.
- Some types of endpoints can be configured multiple times per profile. For instance, an OAuth profile can have any number of token endpoints or user info endpoints.
- Each profile has its own kinds of endpoints and each profile may define the same kind of endpoint and even use the same URI/path.
- Many endpoints allow a script to be configured (e.g., for input validation or token issuance); these will run when the endpoint is required.
It is also helpful to know that the admin node (the one listening on port
6749) does not host any endpoints.
https://localhost:6749/token will always result in an error.
Because an endpoint is not only a path but also a hostname, port and scheme, it is also important to understand some basics about run-time nodes.
Hosts and Run-time Nodes
Clustering is covered in other tutorials. In those, the idea of a run-time node is discussed. A cluster is made up of these and each is pre-defined in the configuration. You can find these in the admin UI under
System -> Deployments. When the example configuration is loaded, there is only one defined and it has an ID of
admin. In that particular case, the admin node is also a run-time node and is used to service OAuth and related requests. This is an atypical production deployment, but it helps as you get start with Curity. In any case, the scheme, port, and host/IP/domain can be determined from the run-time server node. Any node defines:
- A protocol or scheme --
- A listening interface (labeled
Hostin the UI)
- A port
- A (possibly empty) set of endpoints
These are shown in the following figure:
In the simplest case, the first three settings and the path of the hosted endpoints can be used to determine the actual URL that clients should interact with. It is important to note that the listening interface could require some extra detective work. For instance, if the interface that's used in
0.0.0.0, then the node is listening on all interfaces of the host machine. This means, any IP address for any interface of that machine or perhaps the host name itself can be used in the final URL. The host name can only be used if the IP can be resolved by the client (using DNS, for example). If the value is some IP address, say
192.168.1.10, then the node will only listen on the interface bound to that IP address; clients can only use names that resolve to it.
Given the example configuration, the
admin node is deployed on
https://0.0.0.0:8443. This means that it's various endpoints are accessible at
https://127.0.0.1:8443 and perhaps even
https://[::1]:8443/ (if IPv6 is enabled on the host); they are also available on the host's name (e.g.,
my-mac) or the hostname that resolves to one of those IP addresses (e.g.,
example.com). If the node's scheme or protocol is changed to
http, the endpoint URL would of course change to
http://localhost:8443.1 Similarly, the port that is configured also effects the URL; if the port is the default one for the configured protocol (
https), then the URL of the various endpoints do not require explicit inclusion of the port number.
All of the endpoints that are referenced in the
Endpoints sections, are accessible on the node. The widgets shown in the admin UI are the ID of those endpoints. To find the actual URI or path of these endpoints, go to the
Endpoints page of the profile in which the endpoint is defined. There, you can search for it, and you'll see the path, as shown in the following figure:
More Advanced Scenarios
It is also possible to configure a system-wide base URL. This will be used instead of the run-time node's settings. This is helpful when the nodes in a cluster are running behind a load balancer, for instance. It is also possible to define a base URL per authentication profile and to specify multiple such base URLs in the same authentication profile. This makes it possible to share an authentication profile across multiple OAuth server profiles and differentiate them at run-time using the incoming
Host header. For additional details about these more advanced scenarios that effect the actual endpoint URL, refer to the product documentation.
: Changing the scheme of a node does not require a restart.