Available endpoints

Firely Auth provides endpoints for a variety of different operations related to the management of OAuth clients and tokens. The following section describes the REST API for these endpoints and summaries the intention of these interactions. For more details please refer to the corresponding RFCs.

OpenID Configuration

Similar to a CapabilityStatement in Firely Server, Firely Auth offers an endpoint to inspect and verify the available capabilities. The OpenID configuration endpoints returns a JSON document containing:

• URLs of all available endpoints of the service

• A URL pointing to the key material used to sign the access and identity tokens from Firely Auth, wrapped in a Json Web Key Set

• Additional flags to identify enabled features (e.g. supported grant types, supported signing algorithms)

Note

SMART on FHIR provides a compositional syntax for creating scopes, i.e. basic patient/user/system-scopes can be combined with search parameters to create more fine-granular scopes. Therefore not all combinations of supported scopes can be exposed in the “scopes_supported” element of the OpenID configuration.

For more information, see Duende Documentation - Discovery Endpoint.

Introspection endpoint

It is not uncommon that OAuth 2.0 clients do not contain functionality for checking the validity of a provided token, especially if the client is a webclient with reduced support for cryptographic libraries. Firely Auth provides an token introspection endpoint conforming to RFC7662 enabling clients to determine the validity and metadata of the token. This endpoint is actively used by Firely Server in case reference tokens are being provided by a FHIR REST API client.

The introspection endpoint can be access via an HTTP POST request and is protected with the secret provided in the Token introspection setting. The token to be inspected can be provided via the HTTP request body via x-www-urlencoded parameters.

POST /connect/introspect
Authorization: Basic xxxyyy
token=<token>

A successful response will return a status code of 200 and either an active or inactive token:

{
    "active": true,
    "sub": "123"
}

Unknown or expired tokens will be marked as inactive:

{
    "active": false,
}

An invalid request will return a 400, an unauthorized request 401.

Additionally, a valid request will contain meta-information about the token, including:

iss:

String representing the issuer of this token, as defined in JWT [RFC7519].

exp:

Integer timestamp, measured in the number of seconds since January 1 1970 UTC, indicating when this token will expire, as defined in JWT [RFC7519].

aud:

Service-specific string identifier or list of string identifiers representing the intended audience for this token, as defined in JWT [RFC7519].

client_id:

Client identifier for the OAuth 2.0 client that requested this token.

sub:

Subject of the token, as defined in JWT [RFC7519]. Usually a machine-readable identifier of the resource owner who authorized this token.

scope:

A JSON string containing a space-separated list of scopes associated with this token, in the format described in Section 3.3 of OAuth 2.0 [RFC6749].

active:

Boolean indicator of whether or not the presented token is currently active.

Note

Uing the introspection endpoint with reference tokens is the only way enabling a reliable way of revoking access tokens. Reference tokens will be checked by Firely Server on every request for validity and activeness. JWT tokens on the other hand will be valid until they expire.

For more information, see Duende Documentation - Introspection Endpoint.

LaunchContext endpoint

In SMART on FHIR’s EHR launch flow, a launch URL parameter is required when the EHR initiates a launch sequence. It is an identifier for this specific launch and any EHR context associated with it. For more information, see EHR Launch. Firely Auth offers an endpoint to request such identifier.

The launchContext endpoint can be accessed via an HTTP POST request and is protected with the secret provided in the Token introspection setting. The username used for basic auth is the same as the name of the FHIR Server. The password used for basic auth is the same as the introspection secret. The EHR context to be associated with can be provided via the HTTP request body via x-www-urlencoded parameters. FHIR resource ids that are of interest for the EHR launch can be submitted by the EHR to Firely Auth in the form of <resourceType>=<id>. Note that no “launch” prefix is used for the resourceType. Example below requests a launch identifier with patient context associated.

POST /connect/launchContext
Authorization: Basic xxxyyy
patient=<patient-id>

A successful response will return a status code of 200 and a launch identifier:

{
    "launchContextIdentifier": "b0599233-8548-4d56-ae4a-d31babc4ab82"
}

An unauthorized request will return a 401. For selecting the launch context during the token request, we provide the LaunchContextRegistration setting, for more information see EHR and standalone launch context settings.

Known Limitations

• In Firely Auth no Backchannel Authentication Endpoint is available, therefore Client Initiated Backchannel Authentication (CIBA) requests are not supported. For more information, see Duende Documentation - Client Initiated Backchannel Authentication (CIBA).

• A Device Authorization Flow is not supported by SMART on FHIR. Therefore it is not available in Firely Auth. For more information, see Duende Documentation - Device Authorization Endpoint.

Liveness and readiness

It can be useful to check whether Firely Auth is still up and running, and ready to handle requests. Either just for notification, or for automatic failover. A prominent use case is to start dependent services only after Firely Auth is up and running, e.g. in a docker-compose or in a Helm chart.

Firely Auth provides two endpoints, for different purposes:

• GET <base>/$liveness

• GET <base>/$readiness

These align - intentionally - with the use of liveness and readiness probes in Kubernetes, see Probes.

Results

The $liveness operation may return one of these http status codes:

1. 200 OK: Firely Auth is up and running.

2. 402 Payment Required: The license is expired or otherwise invalid.

3. 500 or higher: An unexpected error happened, the server is not running or not reachable (in the latter case the error originates from a component in front of Firely Auth).

The $readiness operation may return one of these http status codes:

1. 200 OK: Firely Auth is up and running and ready to process requests.

2. 402 Payment Required: The license is expired or otherwise invalid.

3. 500 or higher: An unexpected error happened, the server is not running or not reachable (in the latter case the error originates from a component in front of Firely Auth).

Security headers

Firely Auth provides a set of security headers in its responses to protect the application from common security vulnerabilities. These headers are set by default and cannot be configured. These are:

• X-Content-Type-Options: Prevents browsers from MIME-sniffing a response away from the declared content-type. Set to nosniff.

• Content-Security-Policy: Prevents a wide range of attacks, including Cross-Site Scripting and other cross-site injections. Set to:

  • default-src 'self';

  • script-src 'self' 'unsafe-eval' 'unsafe-inline';

  • style-src 'self' 'unsafe-inline';

  • img-src 'self' blob: data:;

  • font-src 'self';

  • object-src 'none';

  • base-uri 'self';

  • form-action 'self';

  • frame-ancestors 'none';

  • upgrade-insecure-requests;

Note

The headers X-Frame-Options, Referrer-Policy, and Permissions-Policy should be configured in the reverse proxy, as Firely Auth cannot set a generic value for these headers.