Monitoring the Authorization Server

HTTP Monitoring

There are different ways to monitor the functioning of the FPX Authorization server.

Public HTTP Endpoint

One of the methods is through a public HTTP endpoint that will indicate whether the application is running properly or not. This method uses the following endpoint:

/.well-known/fpx/version

A request to the above endpoint returns an HTTP 200 status code with information about the application (version, name, release date, etc).

Sample response:

{
  "version":"2.x.x",
  "name":"The Federated Privacy Exchange Authorization Server was built by Identos",
  "release_date":"yyyy-mm-dd",
  "homepage":"https://identos.ca"
}

note

There are also additional endpoints available that can be used to test the functionality of the FPX Authorization Server that do not require authentication such as the public registry endpoints. However, these should be avoided as their use can cause additional load on the server.

Spring Actuator

Spring Actuator can be used to monitor the health of the application. Spring Actuator, a sub-project of the Spring Boot Framework, has various features that allow us to monitor and manage an application. One of those features is the actuator endpoints. The actuator endpoints, based on the endpoints that are enabled, allow us to retrieve specific information about the application.

In order to monitor the health of the Authorization Server using Spring Actuator, you can enable the health endpoint and make use of the built-in "liveness" and "readiness" health checks. These health checks are designed to provide information about the availability of your application. The information on the liveness and readiness of your application is retrieved from "ApplicationAvailability". This information is then presented as Health Indicators called LivenessStateHealthIndicator and ReadinessStateHealthIndicator, which you can access at the global health endpoint /actuator/health.

The /actuator/health endpoint returns a JSON response (as shown below) that includes information on the liveness and readiness states, allowing you to gauge the current health status of your application.

{
    "status": "UP",
    "groups": [
        "liveness",
        "readiness"
    ]
}

This information is also exposed through separate HTTP Probes using Health Groups such as /actuator/health/liveness and /actuator/health/readiness, as elaborated below.

Liveness State

The liveness status indicates whether an application's internal state allows it to work properly or recover if it's failing. A broken liveness state means the application cannot recover and should be restarted.

The following response is received when making a call to the /actuator/health/liveness endpoint.

{
    "status": "UP"
}

Readiness State

The readiness status indicates whether an application is ready to handle traffic. A failing readiness state means that traffic should not be routed to the application.

The following response is received when making a call to the /actuator/health/readiness endpoint.

{
    "status": "UP"
}

Configuration

The Spring Actuator feature is configured through the Admin API. Refer to the following link for configuration details.

Logs

The logs output by the Authorization Server can also be used to monitor the usage of the Authorization Server. It is important to monitor all instances of the Authorization Server that are running and aggregate the logs into a SIEM product of choice.

Alert Levels

Logs will include two pieces of information including alert level and error code that can be used to analyze the logs. Alert level can be extracted using the regular expression

Alert\-Level: [1,2,3]

As an example:

01-10-2020 20:43:10.469 [https-jsse-nio-8080-exec-7] ERROR audit.error - Activity: GET https://authserver.identos.ca/registry/resource/resource_definition/identos-client, Alert-Level: 1, Message: No such resource identos-client found, Code: 40280, Request-Address: 100.117.182.129

There are three different alert levels that can be generated:

• Level 1: malicious user or simple security breach attempt (eg: invalid username/password combo), incorrect configuration.
• Level 2: partner using bad program logic (no such permission), bad state (resource does not exist), more serious bad configuration (IDP signature incorrect), an authenticated user with bad data
• Level 3: bad state, bad configuration, authenticated user or system attempting dangerous action (the scope was not requested/authorized), potential malicious actor successfully impersonating user/system (refresh token has already been refreshed).

Alert levels of 3 should trigger action to remedy and/or investigate the issue.

Authorization Server Exception Types

The following tables list the different Exception Type messages that are part of the Authorization Server log output along with the alert severity levels:

note

The Alert Level of 0 indicates an informational message and does not have any severity level associated with it.

IDN Exceptions and Show Error Page Exception

Alert Level	Lookup Code	Message
1	01.001.001	"An internal server error occurred: {0}"
1	01.001.002	"Resource of type [{0}] is invalid."
1	01.001.003	"Ticket [{0}] was not found"
2	01.001.004	"The JWT could not be parsed"
1	01.001.005	"Invalid Request: {0}"
1	01.001.006	"Access denied"
1	01.002.001	"No scope named [{0}] was found in the access token"
1	01.002.002	"Permission [{0}] was not found on the ID token."
3	01.002.003	"The permission uses a resource type not requested in the ticket."
3	01.002.004	"The scope [{0}] was not required in the ticket"
2	01.002.005	"No access to a permission with ID [{0}]"
1	01.002.006	"Permission/permissions were not found: {0}"
3	01.002.007	"Client is not able to request the requested resource"
1	01.003.001	"The scope [{0}] is not allowed to be used on this resource type"
2	01.003.002	"Resource with ID [{0}] was not found"
3	01.003.003	"No resource was found of resource definition type [{0}] at Resource Server [{1}]"
2	01.003.004	"No resource definition of the type [{0}] has been found"
3	01.003.005	"Non-unique resource was found of resource definition type [{0}] at Resource Server [{1}]"
1	01.004.001	"The requested resource capability for resource ID [{0}] was not found."
2	01.005.001	"Resource Server corresponding to audience claim [{0}] is not registered."
2	01.006.001	"The identity request is invalid: {0}"
1	01.007.001	"No scope named [{0}] found"
2	01.007.002	"The Resource Server does not provide the [{0}] scope"
1	01.008.001	"The Request ID is invalid: {0}"
1	01.009.001	"The login hint [{0}] is invalid."
2	01.009.002	"Wallet with ID [{0}] is not registered."
2	01.009.003	"OAuth Client with ID [{0}] is not registered as a Wallet."
1	01.010.001	"Administrator has disabled entity used in the request"
1	01.010.002	"This Wallet has been disabled by an administrator"
3	01.011.001	"No data converter is suitable to convert the data to or from the internal data format. {0}"
2	01.011.002	"The requested scope [{0}] is currently not supported"
1	01.011.003	"The permission request was invalid: {0}"
2	01.011.004	"The resource was not found for resource server [{0}] and resource definition of type [{1}]."
2	01.011.005	"The scope [{0}] is not allowed to be used on this resource type"
1	01.012.001	"Uma Client with ID [{0}] was not found"
2	01.012.002	"OAuth Client with ID [{0}] is not set up as an UMA client"
1	01.013.001	"No claims gathering request was found with ID [{0}]"
3	01.013.002	"Unauthorized access to Capability Ticket [{0}] by OAuth Client [{1}]"
1	01.013.003	"The client credentials were not valid: {0}"
1	01.014.001	"Ticket [{0}] has been redeemed or is not the most recent ticket"
3	01.014.002	"Ticket [{0}] was redeemed by another client"
1	01.015.001	"The requested permission was not found: {0}"
3	01.016.001	"JTI has already been redeemed"
2	01.016.002	"JTI claim must be present in JWT"
2	00.000.000	"Internal server error occurred"

OAuth2 Exceptions

Alert Level	Lookup Code	Message
2	01.009.001	"invalid_client"
1	01.009.002	"invalid_grant"
2	01.009.003	"invalid_client_metadata"
1	01.009.004	"invalid_grant"
2	01.009.005	"invalid_resource_id"
2	01.009.006	"invalid_scope"
0	01.009.007	"need_info"
2	01.009.008	"request_denied"
2	01.009.009	"unsupported_grant_type"

OAuth Provider Exceptions

Alert Level	Lookup Code	Message
3	06.001.000	"An internal server error occurred."
2	06.001.001	"Malformed application/x-www-form-urlencoded request"
3	06.001.002	"An internal server error occurred. {0}"
2	06.001.003	"Authorization header was invalid."
2	06.001.004	"No matching access token found."
2	06.001.005	"No matching refresh token found."
1	06.001.006	"Access token has expired."
1	06.001.007	"Access token has been disabled and is no longer valid."
1	06.001.008	"Refresh token has expired."
1	06.001.009	"The refresh token provided is invalid, please obtain authorization again"
2	06.001.010	"Client with ID [{0}] was not found."
2	06.001.011	"Proof Key for Code Exchange (PKCE) authentication failed."
2	06.001.012	"The code challenge is invalid - must be between 43 and 128 characters."
2	06.001.013	"Code challenge is required"
2	06.001.014	"The code verifier is invalid."
2	06.001.015	"Code challenge method is missing or must be set to S256"
2	06.001.016	"Authorization code was not found or has been redeemed"
2	06.001.017	"Authorization code is expired."
3	06.001.018	"This authorization code is for a different client."
3	06.001.019	"This refresh token is for a different client."
3	06.001.020	"This token was issued for a different client and cannot be revoked by the requesting client with ID [{0}]"
2	06.001.021	"This response type [{0}] is not supported."
2	06.001.022	"No request authorization could be retrieved."
2	06.001.023	"The client credentials were not valid or not supported: {0}"
3	06.001.024	"Failed to retrieve the tokens."
2	06.001.025	"The redirect URI [{0}] is not registered for OAuth Client with ID [{1}]"
1	06.001.026	"The redirect_uri cannot be empty or null"
2	06.001.027	"The redirect_uri does not match the initial request redirect_uri"
3	06.001.028	"The request is invalid"
2	06.001.029	"The client secret is incorrect."
2	06.001.030	"The provided grant type [{0}] is not supported."
2	06.001.031	"This access token does not provide sufficient scopes."
3	06.001.032	"The requested scope [{0}] is invalid or exceeds the scope granted by the resource owner."
3	06.001.033	"No data converter is suitable to convert the data to or from an internal data format."
2	06.001.034	"Invalid parameter or malformed request supplied, no request type found."
2	06.001.035	"Invalid parameter or malformed request supplied: {0}"
1	06.001.036	"The request is invalid: {0}"
3	06.001.037	"No suitable request converter, {0}"

OAuth Client Exceptions

Alert Level	Lookup Code	Message
2	04.001.100	"Unable to retrieve the access token"
3	04.001.101	"Unable to create client auth for token endpoint"
3	04.001.102	"No ongoing transaction found for this state value: [{0}]"
2	04.001.103	"OAuth transaction has expired, please try again"
2	04.001.104	"UMA transaction took too many trips without completing"
3	04.001.105	"Unable to retrieve provider metadata from well-known endpoint"
3	04.001.106	"OAuth Provider did not have a JWK set registered."
3	04.001.107	"OAuth Provider with issuer URI [{0}] is not registered."
2	04.001.108	"Unable to fetch UserInfo"
2	04.002.001	Message from an OAuth Client Token Error varies, returned from downstream provider.

Service Provider Exceptions and Need Info Exception

Alert Level	Lookup Code	Message
3	05.001.001	"Could not parse FPX RPT. The subject of the RPT did not match the ticket_value of the Permission Ticket"
3	05.001.002	"Could not parse FPX RPT. The resource_type and/or resource_location of an Access Token are null."
3	05.001.003	"Could not parse FPX RPT. Please contact your administrator."
3	05.002.001	"Received unexpected response from RS: {0}"
2	05.003.001	"Could not find Capability Ticket with name [{0}]"
3	05.003.002	"Could not exchange Capability Ticket at the Authorization Server."
2	05.004.001	"No active transactions found for state value: [{0}]"
0	05.000.001	"need_info"

Claim Restriction Exceptions

Alert Level	Lookup Code	Message
2	06.000.001	"claim has been restricted"

JWT Exceptions

Alert Level	Lookup Code	Message
3	07.001.001	"unable to load jwks from url"
3	07.001.002	"provided jwt is invalid"
3	07.001.003	"JWT could not be parsed"
3	07.001.004	"JWT signature is invalid"
3	07.001.005	"Issuer does not match JWT."
3	07.001.006	"JWT could not be signed"
3	07.001.007	"provided JWT was not signed"
3	07.001.008	"idtoken did not validate"

Framework and HTTP Exceptions

Alert Level	Lookup Code	Exception Name	Example Message
1	00.000.001	Authentication Exception	"Access denied - unauthenticated"
1	00.000.002	Access Denied Exception	"Access denied - unauthorized"
1	00.000.003	HTTP Request Method Not Supported	"HTTP method not supported. Check the 'Allow' response header to see supported methods."
1	00.000.004	Missing Servlet Request Parameter	"Required request parameter 'request_param_1' for method parameter type int is not present"
1	00.000.005	Request Rejected	"The request was rejected because the URL contained a potentially malicious String \"//\""
1	00.000.006	No Handler Found	"Not found - no handler for GET /non-existent-path"
1	00.000.007	HTTP Message Not Readable	"HTTP message could not be read: if this is a POST request, check that you included a request body."
1	00.000.008	HTTP Media Type Not Supported	"Content type 'text/html' not supported"
1	00.000.009	Method Argument Type Mismatch	"Invalid boolean value [not-a-boolean]"
1	00.000.010	Binding Error	"Binding error: see the error_list for details"
1	00.000.010	Constraint Violation	"Constraint violation: [request_arg must not be blank, request_arg size must be between 2 and 3]"