Developerguide_BackgroundInformation
- User must be authenticated using one of the providers (e.g. bankid, helseId) (Mandatory)
- User may have a hpr-number (Option)
- User may be in one of the specified health user categories (e.g. Doctor) (Option)
- It uses Authorization Code Flow
- Backend handles for Frontend
- The Flow is automatically handled
- Have a default set of policies
- Default is implemented to be easily changed, and can be done manually instead
- Built-in logging, based on Microsoft logging abstractions
- The packages are controlled through configuration
- There are a series of feature flags in the configuration, to turn on/off based on need or environment
The package has trace logging in multiple places, to be turned on/off through the configuration
- The user access the front end
- Front end calls backend
- Backend used the Fhi.HelseId.Web component, triggered through the call event to call up to STS HelseId to start an authentication
- The login box appears. Normally a selection first of different possible providers are given, once the user have selected this, the appropriate login box is opened
- The user enters his/hers credentials
- Control is returned to the STS, which check the credentials. If the are not passed the user is informed, and 4-6 is repeated
- Once the user is accepted, the identity token and a code is sent back to the Fhi.HelseId component in the backend. The identity token will include a Hpr number, if the user has a such.
- The Fhi.HelseId.Web will start using the code to get an access token. This is repeated automatically to get refreshes.
- The Web backend starts a call to the respective Web Api using the access token it was given
- The Web Api uses its own Fhi.HelseId.Api to verify the access token.
After the identity-token and code has been received, the Fhi.HelseId will, if configured to do so though - this is optional, call the Hpr register (7b) to get the authorization data for the given Hpr number of the user, and verify that against the configured requirements for the application.
When the client access the applications url, it will start a load of the front end. The front end execution on the client will get a cookie from the backend. The backend will normally start an authentication flow with the STS, invoking a Client Authentication session as explained above.
The backend will get two tokens, an identity-token (marked red) and an access token (marked green). The access token is used to access the underlying APIs.
There are 3 built-in policies:
- You must be authenticated
- You must have an Hpr-number
- You must be in an approved Hpr category
Policy 2 og 3 can be turned off using one of the feature flags in the configuration
The package has the possibility for adding an approval listing. This will then be used if enabled and any user in this list will override the default authentication.
It is meant for persons that will do testing and maintenance on the production environment.
The approval list uses pseudonyms from HelseId.
The approval list is a part of the configuration
- Files and endpoints can be “protected”
- Can be controlled by code or configuration
- Uses a set of default filenames for typical cases: Forbidden, Error, LoggedOut and StatusCode
- These four can be explicitly controlled through configuration
- See further down for skeleton-code for call to an API, also see Step by step guide
The package can be used both for the Web Backend and for any API. It has two seperate parts for each of these. The setup changes for each are shown below as Web and Api respectively.
Web backend (Note: This is older information, see link list in the main page for up-to-date information)
Red marked is what you must change. Yellow marked is what you probably already have in, but ensure it is there. Green marked is whatever server option you use, in our case we use the one marked below in green.
Notice the ConfigureGateway. This is a method handling our specific setup for underlying APIs. Yours might differ, but the essentials below should be done:
In order to call an API you must include the access token in the header:
This is the configuration needed on any APIs to be called. This will ensure the access token is properly validated.
It is very useful to use explicit configuration classes. The Fhi.HelseId component has base classes you can inherit from, so that you get good names with a clear meaning. You can then also add your own configuration to these as appropriate.
The NHN hosting has multiple environments, which goes to either the Test or the Production STS.
- HelseId itself can be accessed from both HelseNett and from internet
- If you use the Hpr, it is not accessible on the internet (Test might be), so then you just turn the Hpr access off using the appropriate feature flag in the config.
-
Your web application must be registered as a client in the test-STS for HelseID
-
You do this using Nhn HelseId Selvbetjening
-
API’s must also be regoistered, as APIs.
-
The Web app need a client ID and a client secret, which is generated by Selvbetjening.
-
The Application need one set for Test STS and one for Production STS.
- Building on Microsoft OpenIdConnect and components from the Open Source project Identityserver
- Have a series of extension methods, which easily can be split up, if you need to use only parts of it.
- Simple to expand with your own policies
- The extension methods have entry points for expansion (feel free to contribute more if needed, we do take Pull Requests)
- Configuration controlled
- Skeleton code for easy use