Available Endpoints

An endpoint is a specific location that is capable of accepting incoming requests, and is usually a specific URL (Uniform Resource Locator) that is provided by an API (Application Programming Interface). An API is a set of programming instructions and standards for accessing a web-based software application or web tool. APIs allow different software systems to communicate with each other, and enable functionality such as requesting data from a server, or sending data to a server for storage.

OAuth (Open Authorization) is an open standard for authorization that provides a secure method for API authentication. OAuth endpoints are specific URLs that are used in the OAuth authorization process to request and grant access tokens to API resources. There are two main OAuth endpoints:

1. Authorization endpoint: This is the URL where the user is redirected to in order to grant authorization to the client application.
2. Token endpoint: This is the URL where the client application exchanges the authorization code for an access token.

In OAuth two additional endpoints should be mentioned:

3. Redirection endpoint: This is the URL where the user is redirected after they grant or deny authorization to the client application.
4. Resource endpoint: This is the URL of the API resource that the client application is trying to access.

Besides the authorisation endpoint and the token endpoint Uitsmijter do provide endpoints for monitoring and metrics as well.

This page describes the technical details of the available endpoints and shows some basic examples how to use them. This information is importend if you are writing your own client library implementation, but you will not need to know all the details when using an already existent client library like 🔗 oidc-client-ts.

Authorize a client to use a resource. The /authorize endpoint will redirect to a callback url with an authorization code if the user logs in successfully.

You can find an example setup in our quick start guide

Recommendation:

Use PKCE to request an authorization code.

Example: Request an authorization code with PKCE SHA265 code

    /authorize
        ?response_type=code
        &client_id=9095A4F2-35B2-48B1-A325-309CA324B97E
        &redirect_uri=https://example.com/
        &scope=read,learn
        &state=Za8uR
        &code_challenge=3VpzZL3DpqEwubIbIVsrOUbvB19kk4yGP7gGaxU/cyQ=
        &code_challenge_method=S256

Parameter description:

In case the authorisation process succeeded the authorisation server responds with a redirect:

HTTP/1.1 302 Found
Location: https://example.com/?code=KJH876GFED&state=Za8uR

This response includes the following parameters:

• code: This is the authorization code that the client application can use to request an access token.
• state: This is the same state value that was included in the original authorization request. It is returned as part of the response so that the client application can verify that the response was generated in response to the correct request.

This response is a 302 Found status code, which indicates that the user is being redirected to the URL specified in the Location header. In this case, the user is being redirected to the redirect_uri that was specified in the original authorization request, along with the code and state parameters.

Access tokens are used for applications to perform API requests on behalf of a user. The access token represents the authorization of a specific application to access specific parts of a user’s data.

Access tokens must be kept confidential in transit and in storage. The only parties that should ever see the access token are the application itself, the authorization server and the resource server.

Uitsmijter implements different grant types that a client may support. For example, the authorisation code grant can be requested with a proper call to the /token endpoint and a grant type authorisation_code:

{
  "grant_type": "authorization_code",
  "client_id": "9095A4F2-35B2-48B1-A325-309CA324B97E",
  "scope": "read write admin_list",
  "code": "KJH876GFED"
}

For legacy applications an implicit grant flow can be turned on in the client configuration.

{
  "grant_type": "password",
  "client_id": "9095A4F2-35B2-48B1-A325-309CA324B97E",
  "scope": "read write admin_list",
  "username": "Julia@example.com",
  "password": "eis6Ooth3oDa"
}

If the client needs to be authenticated, then a client_secret is mandatory.

Even if the example for a password grant type is chosen, it is NOT RECOMMENDED to use this type of grant type. The ability to serve a password grant type must be enabled explicitly.

Parameter description:

A possible response from the authorization server for the first example:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "access_token": "V7vZQbJNNY7zR8IWyV7vZQbJNNY7zR8IW",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "read write admin_list",
  "refresh_token": "E2yCQ4yJ0E2yCQ4yJ0"
}

This response includes the following parameters:

• access_token: The access token that the client application can use to access the API resources.
• token_type: Specifies the type of the access token. In this case, the value is Bearer, which means that the access token is a bearer token and can be used to access the API resources as long as it is presented to the API server.
• expires_in: specifies the number of seconds until the access token expires.
• scope: The scope of the authorization that was granted to the client application. It should match the scope value that was included in the original request. If a client does not support all the requested scopes, an allowed subset is returned.
• refresh_token: A refresh token that the client application can use to obtain a new access token after the current one expires. (In the response of an authorization_code grant type request only!)

The refresh_token parameter is only present in the authorization_code grant type request response, because it is only used in certain grant types. The refresh_token is used to obtain a new access token after the current one expires, without having to prompt the user for their login credentials again. That is strictly forbidden with the password grant type.

Even the /token/info endpoint is not a standard endpoint in OAuth, it is widely used to provide information about access tokens.

To use this endpoint, you will need to make a GET request to the /token/info endpoint and include the access token in the request. For example, you can use the curl command to make a request like this:

curl --request GET \
  --url https://YOUR_AUTH0_DOMAIN/token/info \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

This will return a JSON object containing information about the access token, such as its expiration time and the scope of the authorization that it represents. For example:

{
  "name": "John Doe"
}

Customise the profile:

The JSON object returned can be customised by the user backend provider. Everything that is returned from the userProfile getter is encoded in the JWT and will be decoded in the response of teh /token/info call.

Monitoring endpoints are endpoints that are used to monitor the health and status of Uitsmijter. These endpoints can be accessed via HTTP requests and return information about the current state of the system, such as its uptime, performance metrics, and login amounts as well as error counts.

Monitoring endpoints are often used by monitoring tools to check the health of the system on a regular basis. This can help to identify potential issues or outages before they become serious problems, and can also be used to track the performance and reliability of the system over time.

Uitsmijter implements two endpoints that are ready to use for a cluster environment.

Kubernetes (and other orchestration tools) uses a number of different health check mechanisms to monitor the health of various components and services. One common mechanism is to use a /health endpoint that can be accessed via an HTTP request. This endpoint is used to check the health of the component by making a request to it and examining the response.

Uitsmijter supports the /health endpoint.

Uitsmijter return a 200 OK status code if the application is healthy, or it may return a 500-status code if there is a problem. In this case the logs will have detailed information about the problem.

Kubernetes for example uses the information returned by the /health endpoint to determine the health of the authorisation server to take appropriate action if there is a problem. For example, if the /health endpoint indicates that Uitsmijter is unhealthy, Kubernetes may restart it or take other measures to try to restore it to a healthy state.

The /metrics endpoint is an endpoint that exposes metrics data that can be collected and stored by a 🔗 Prometheus server. This endpoint can be accessed via an HTTP request (the request must include the Accept: application/openmetrics-text header) and returns a text-based format called the “Prometheus text format” that contains the metric data.

Prometheus is a popular open-source monitoring and alerting system that is designed to collect and store metric data from various sources.

Uitsmijter provides several metrics about http request duration, error counts and logins to tenants and clients. The installation precess has a Grafana dashboard attached, that can be used to see business metrics about each tenant as well as about the overall system status over time.

• Client side JWT Decoding
• Authorization Code Flow with Proof Key for Code Exchange