Endpoints and their URLs

Overview of an Endpoint

An endpoint is something that is used quite a lot in the Curity Identity Server 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 the Curity Identity Server; 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 the Curity Identity Server. 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/token as well as /tenant2/token); helps with backward compatibility when a pre-existing service is being replaced by the Curity Identity Server; and also obscures the usage of the Curity Identity Server.
• Endpoints are hosted on run-time services. 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 service role nor 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 logout under an authenticate endpoint or Users under 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 kind of endpoint 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 Services

Clustering is covered in other tutorials. In those, the idea of a run-time service is discussed. A cluster is made up of these nodes and each is pre-defined in the configuration. You can find these in the admin UI under System -> Deployments. When the basic setup wizard runes, there is only one defined and it has an ID of default. In this 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 service node. Any node defines:

• A protocol or scheme -- http or https (the default)
• A listening interface (labeled Host in the UI)
• A port
• A (possibly empty) set of endpoints

These are shown in the follow 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 is used is 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://localhost:8443, 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., ubuntu or 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 (80 for http and 443 for 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 section, are accessible on run-time services that assume that role. The widgets shown in the admin UI are the ID of those endpoints. To find the actual URI or patconceptse 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.

1 Changing the scheme of a node does not require a restart. ↩