.. _firely_auth_glossary: Glossary of terms in authorization ================================== .. glossary:: authorization server An instance of Firely Auth that can provide a :term:`access token` and potentially :term:`refresh token` to a :term:`client` user The patient, practitioner or other person that uses a :term:`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 :term:`user` or directly. fhir server An instance of Firely Server hosting resources that can be accessed by a :term:`client` on behalf of a :term:`user`. In OAuth terms this is usually referred to as a 'resource server'. access token A string issued by the :term:`authorization server` to the requesting :term:`client`, that the client then needs to present to the :term:`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 :term:`JWT`, or a :term:`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 :term:`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 :term:`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 :term:`JWT` because of the roundtrip to Firely Auth. But it is safer than a :term:`JWT` because the :term:`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 :term:`client` as part of an :term:`authorization code flow`. The client can then exchange the authorization code for an :term:`access token`. authorization code flow A flow to authorize a :term:`client` to request an :term:`access token` from Firely Auth. Typically used for a :term:`public client`. See `https://oauth.net/2/grant-types/authorization-code/ `_. It can be further secured by the use of :term:`PKCE`. PKCE Abbreviation of Proof Key for Code Exchange. A protocol used in conjunction with :term:`authorization code flow` to prevent certain attacks. It uses temporary secrets generated by the :term:`client`. grant type A way of authorizing a :term:`client` to request an :term:`access token` from Firely Auth. Also referred to as authorization flows. Firely Auth supports two grant types: - :term:`client credentials` - :term:`authorization code flow` (optionally with :term:`PKCE`) client credentials A :term:`confidential client` may use credentials (similar to username / password, but for software) to request an :term:`access token` directly from Firely Auth. claim An element in an :term:`access token` that tells Firely Server that the :term:`client` claims to have access to certain resources. A client requests a claim. Then Firely Auth will optionally as the :term:`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 :term:`reference token`. confidential client A :term:`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 :term:`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`_. .. _SMART on FHIR clients: http://hl7.org/fhir/smart-app-launch/app-launch.html#support-for-public-and-confidential-apps .. _SMART on FHIR claims: http://hl7.org/fhir/smart-app-launch/scopes-and-launch-context.html