Glossary of terms in authorization

authorization server

An instance of Firely Auth that can provide a access token and potentially refresh token to a client

user

The patient, practitioner or other person that uses a client to access resources on Firely Server. In OAuth terms this is the ‘resource owner’.

client

An app or website that accesses resources on Firely Server, either on behalf of a user or directly.

fhir server

An instance of Firely Server hosting resources that can be accessed by a client on behalf of a user. In OAuth terms this is usually referred to as a ‘resource server’.

access token

A string issued by the authorization server to the requesting client, that the client then needs to present to the fhir server to get access to resources. The fhir server will check the validity of the token. The client need not understand the token or its format and is not supposed to read it.

An access token issued by Firely Auth can be in one of two forms: a JWT, or a reference token.

JWT

JWT is an abbreviation for JSON Web Token. It defines a structure for an access token, based on JSON, with a predefined list of elements. A JWT is self contained, so it has all the data in it for the fhir server to check its validity. This however means that the token cannot be revoked in case of malicious use. The token remains valid until its expiration time is past.

A JWT is encoded into a single string. You can easily decode it on JWT.io.

JWK

JWK is an abbreviation of JSON Web Key. It defines a JSON structure for a key. A client can sign requests with a private key and publish a JWK for the corresponding public key for Firely Auth to use when validating the signature. Multiple JWKs are usually published on a url in the form of a JWKS - a JSON Web Key Set. Multiple keys allow for key rotation without downtime.

reference token

A reference token is a string that does not contain any information about what is granted. Instead it is a reference to the actual token that is kept within Firely Auth. For Firely Server to check a reference token it sends the token to the token introspection endpoint of Firely Auth. Firely Auth will then send the validity along with relevant claims to Firely Server. A reference token is slower to validate than a JWT because of the roundtrip to Firely Auth. But it is safer than a JWT because the client cannot read any information from the token and the token can be revoked before its original expiration time.

authorization code

A code (a string) returned by Firely Auth to a client as part of an authorization code flow. The client can then exchange the authorization code for an access token.

authorization code flow

A flow to authorize a client to request an access token from Firely Auth. Typically used for a public client. See https://oauth.net/2/grant-types/authorization-code/. It can be further secured by the use of PKCE.

PKCE

Abbreviation of Proof Key for Code Exchange. A protocol used in conjunction with authorization code flow to prevent certain attacks. It uses temporary secrets generated by the client.

grant type

A way of authorizing a client to request an access token from Firely Auth. Also referred to as authorization flows. Firely Auth supports two grant types:

client credentials

A confidential client may use credentials (similar to username / password, but for software) to request an access token directly from Firely Auth.

claim

An element in an access token that tells Firely Server that the client claims to have access to certain resources. A client requests a claim. Then Firely Auth will optionally as the user for consent to grant this claim to the client. Then Firely Auth includes the claim in the access token. The client presents the access token as part of its request to Firely Server. Finally Firely Server must understand the claim and will restrict access to resources accordingly.

Firely Server and Firely Auth understand the claims as defined by SMART on FHIR (v1 and v2).

refresh token

The Refresh Token grant type is used by clients to exchange a refresh token for an access token when the access token has expired. This allows clients to continue to have a valid access token without further interaction with the user.

token introspection endpoint

Endpoint offered by Firely Auth to inspect a reference token.

confidential client

A client that can guard a shared secret. E.g. a web application, where the code lives on a well managed server. See also SMART on FHIR clients.

public client

A client that cannot guard a shared secret, e.g. because its code is public. Like in native apps or some Single Page Applications. See also SMART on FHIR clients.