Technical specification#

All the information related to the usage of multifactor authentication by a certain user must be stored directly in the user’s entry at the institutional directory. In order to accommodate such information without interfering with other attributes already in the directories, and to guarantee the technical and administrative requisites needed, Feide has extended the norEduPerson schema with two additional attributes:

norEduPersonServiceAuthnLevel: a multivalued attribute that lets the institution decide whether multifactor authentication is enabled or not for the current user, the strength of the authentication mechanism, and for which services.
norEduPersonAuthnMethod:: a multivalued attribute that lets the institution specify which multifactor methods can be used by the current user.

Enforcing multifactor authentication#

In order to allow someone to use multifactor authentication in Feide, one or more multifactor methods MUST be defined. However, this requirement is not sufficient, as multifactor authentication MUST also be enabled for the service being accessed or for a specific user. Institutions can configure which services should use multifactor authentication in Feide’s Customer Portal.

Alternatively, the general configuration can be overridden on a per-user basis by adding the norEduPersonServiceAuthnLevel attribute of the norEduPerson schema to the specific subject. The attribute consists of two strings separated by a white space. The first one is the fixed string urn:mace:feide.no:spid: followed by one of these values:

The keyword all, used to enforce multifactor authentication for all services.
A Service ID identifying a specific service, as found in Feide’s Customer Portal for that service. For SAML services this is a number, while for OIDC/OAuth services it is an UUID.

These values MUST be followed by another string representing the assurance level desired for either all or the particular services specified. Currently, Feide supports only the third level described by the Norwegian Framework for authentication and nonrepudiation in electronic communications with and in the public sector. The level of assurance can be expressed with the string urn:mace:feide.no:auth:level:fad08: followed by the numerical value identifying the level, in this case, 3.

Please note that none of the authentication methods currently supported by Feide provide level 4 according to this framework. Therefore, requiring that level would make it impossible for users to access the service or services affected.

SMS authentication#

Institutions can enable multifactor authentication based on text messages by enabling multifactor authentication as described in the previous section, and adding a norEduPersonAuthnMethod attribute to every user who should be able to use this mechanism. This attribute is multivalued and each value MUST contain:

The fixed string urn:mace:feide.no:auth:method:sms identifying the SMS multifactor method in Feide.
The mobile phone number associated with the user in international format, including the country code prefixed with the plus sign (+). Phone numbers MUST NOT have blank spaces, dashes or any other character different than numbers, with the only exception of the aforementioned international code prefix.

Optionally, a label identifying the device associated with the phone number can be added after these two mandatory elements. If no label is specified, the last digits of the phone number are displayed. Labels take the form label=value, where value is a string that we want to be displayed in order to identify the associated number. The value MUST be URL-encoded as defined by RFC 3986 and therefore comply with the following rules:

Equal signs (=) MUST be escaped according to percent encoding as defined by RFC 3986, that is, substituted by the string %3D.
Spaces MUST be escaped according to percent encoding as defined by RFC 3986, that is, substituted by the string %20.
Percent signs (%) MUST be escaped according to percent encoding as defined by RFC 3986, that is, substituted by the string %25.
No single or double quotes are allowed surrounding the values.

All parts of the norEduPersonAuthnMethod attribute MUST be separated by a single blank space and keep the order specified here, so that the resulting value has the following format:

urn:mace:feide.no:auth:method:sms +<COUNTRY_CODE><NUMBER> label=<A_LABEL>

Refer to Appendix 1 for examples of values that are correctly formatted and values that are not.

Authenticator#

In this section we present the technical details for storing and encrypting secrets in user directories, so that they can be used securely to perform multifactor authentication with the Authenticator method.

Authenticator secrets consist of 16 base32-encoded characters. This means that valid secrets can only contain:

Uppercase ASCII letters from A to Z, both included.
Digits from 2 to 7, both included.

There is no restriction on the proportion of letters or digits, though, so secrets can be random strings base32-encoded with the aforementioned fixed length of 16 characters.

It is therefore RECOMMENDED to randomly generate these secrets. Institutions MUST NOT use functions to derive the secret from known or guessable values like the user identifier or e-mail address. If the Authenticator secret can be derived from other information related to the user, it is then useless as anybody could guess the right secret for a specific person.

API for generating and encrypting secrets#

Feide provides a API for generation and encryption of Authenticator secrets. This API is described in the multi-factor authentication API document.

Note that this API is rate-limited.

Manual secret encryption#

Those willing to integrate Authenticator secret encryption with their own processes and systems can do it without depending on the API provided by Feide. Secrets are encrypted using the JSON Web Encryption specification with a public key specific for this use and published on the Feide metadata website. The secret used as input for the encryption algorithm MUST be encoded as a JSON object, with the form:

{"secret": "SECRET_TO_ENCRYPT"}

where SECRET_TO_ENCRYPT is the randomly generated secret that has been configured on the user’s device. The JWA specification defines multiple algorithms for key and content encryption. Currently, Feide supports only the RSA-OAEP key management algorithm and the A128CBC_HS256 content encryption algorithm. Appendix 2 presents code examples of how to encrypt the Authenticator secrets suitable for their use in Feide in different programming languages.

Storage of secrets#

Secrets for Authenticator instances MUST be stored in the user’s entry in the corporate directory. The secrets themselves will be stored in the norEduPersonAuthnMethod attribute defined by the norEduPerson schema. The values of this attribute MUST contain:

The fixed string urn:mace:feide.no:auth:method:ga identifying the Authenticator multifactor method in Feide.
The Authenticator secret encrypted with Feide’s public key as described in the previous section.

Optionally, a label identifying a specific instance of the Authenticator can be included. Labels are prefixed by the string label=, which is omitted if no label is attached to this Authenticator instance. All parts of the attribute value MUST be separated by a single blank space and keep the order, so that the resulting value has the following format:

urn:mace:feide.no:auth:method:ga <ENCRYPTED_SECRET> label=<A_LABEL>

Both the encrypted secret and the label (excluding its prefix) MUST comply with the following rules:

Equal signs (=) MUST be escaped according to percent encoding as defined by RFC 3986, that is, substituted by the string %3D.
Spaces MUST be escaped according to percent encoding as defined by RFC 3986, that is, substituted by the string %20.
Percent signs (%) MUST be escaped according to percent encoding as defined by RFC 3986, that is, substituted by the string %25.
No single or double quotes are allowed surrounding the values.

Azure AD#

Institutions can enable multifactor authentication based on AzureAD if the AzureAD login method has been enabled in the Customer Portal. A norEduPersonAuthnMethod attribute needs to be added to every user who should be able to use this mechanism.

This attribute is multivalued and MUST contain the following fixed string identifying the Azure AD multifactor method in Feide:

urn:mace:feide.no:auth:method:azuread -

This also indicates that the user has had their identity verified and that the multifactor authentication method has been provisioned to the user securely.

When we authenticate a Feide user using AzureAD we validate the following claims of the access token:

acr: Has to be the value 1.
amr: The list has to contain at least two values. One of the values must be mfa, while the other must signal which authentication method was used.

If and only if both of these are satisfied the multifactor authentication is successful.

For more details on the access token and claims, see the access token claims reference.