GithubHelp home page GithubHelp logo

swedenconnect / technical-framework Goto Github PK

View Code? Open in Web Editor NEW
25.0 18.0 3.0 50.43 MB

Technical Specifications for the Swedish eID Framework

HTML 7.09% CSS 73.21% Shell 19.69%
swedish-eid-framework technical-specifications saml2 eidas eid

technical-framework's Introduction

Technical Specifications for the Swedish eID Framework

This repository comprises the specifications of the Swedish eID Framework.

About

The specifications in this branch are the latest development of the Swedish eID Framework. The latest official release can be found in the november-2021 branch.

Feedback and Questions

If you have feedback or questions regarding the Technical Framework join the Sweden Connect Slack Workspace.

Click here to ask for an invitation.

The Working Group

The Working Group for the Swedish eID Framework is responsible of development of future versions of the framework.

Releases

For official and draft releases of the Swedish eID Framework, see the releases section.

The releases can also be found under https://docs.swedenconnect.se/technical-framework/.

Contents

Introduction to the Swedish eID Framework

An overview document that describes the different parts of the Swedish eID Framework.

Introduction to the Swedish eID Framework (in English)

Tekniskt ramverk - Introduktion (in Swedish)

Swedish eID Framework - Registry for identifiers

This document defines the structure for identifiers assigned by the Swedish Agency for Digital Government (DIGG) and provides a registry for assigned identifiers.

03 - Registry for Identifiers

Authentication Specifications

Below follows a listing of all specifications concerning user authentication.

OpenID Connect will be introduced as an alternative to SAML. Therefore we point out the protocol for the specifications below.

SAML: Deployment Profile for the Swedish eID Framework

This is the main specification for the Swedish eID Framework. It defines a SAML profile including metadata, request- and response processing as well as extensions for signature services.

02 - Deployment Profile for the Swedish eID Framework

SAML: Attribute Specification for the Swedish eID Framework

This document specifies an attribute profile for the Swedish eID Framework. The attribute profile defines attributes for use within the Swedish eID Framework, and a number of defined attribute sets that may be referenced by other documents as means to specify specific attribute release requirements.

04 - Attribute Specification for the Swedish eID Framework

SAML: Entity Categories for the Swedish eID Framework

This specification contains the Entity Category definitions that are defined for the Swedish eID Framework and that should be supported by Service Providers and Identity Providers that are part of the federation.

06 - Entity Categories for the Swedish eID Framework

eIDAS Constructed Attribute Specification for the Swedish eID Framework

This document extends “Attribute Specification for the Swedish eID Framework”, providing specifications for constructed attributes.

The concept of constructed attributes is introduced in Swedish national authentication nodes (proxy nodes) delivering identity assertions to Swedish Service Providers based on user authentication with a foreign eID.

11 - eIDAS Constructed Attributes Specification for the Swedish eID Framework

SAML: Implementation Profile for BankID Identity Providers within the Swedish eID Framework

SAML implementation profile for Identity Providers implementing BankID support.

12 - BankID Profile for the Swedish eID Framework

SAML: Principal Selection in SAML Authentication Requests

This specification defines an element that may be included in the Extensions element of a SAML AuthnRequest where the requesting Service Provider can specify matching criteria that may be used by the Identity Provider to select the particular user that should be authenticated.

14 - Principal Selection in SAML Authentication Requests

SAML: User Message Extension in SAML Authentication Requests

This specification defines an element that may be included in the Extensions element of a SAML AuthnRequest where the requesting Service Provider can specify a "user message" that is to be displayed for the user by the Identity Provider during the authentication phase.

18 - User Message Extension in SAML Authentication Requests

Signature Specifications

Below follows a listing of the specifications we define for Federated Central Signing Services.

Implementation Profile for using OASIS DSS in Central Signing Services

This document specifies an implementation profile for exchange of sign requests and responses using the OASIS DSS protocol, enhanced by the DSS Extensions for Federated Central Signing Services.

07 - Implementation Profile for using DSS in Central Signing Services

Certificate Profile for Certificates Issued by Central Signing Services

This document specifies a certificate profile for certificates issued by a signature service.

08 - Certificate Profile for Central Signing Services

DSS Extension for Federated Central Signing Services

This specification defines elements that extend the <dss:SignRequest> and <dss:SignResponse> elements of the OASIS DSS protocol.

09 - DSS Extension for Federated Signing Services

Signature Activation Protocol for Federated Signing

This document specifies a Signature Activation Protocol (SAP) and its data elements for implementation of Sole Control Assurance Level 2 (SCAL2) according the European standards prEN 419241 - Trustworthy Systems Supporting Server Signing.

13 - Signature Activation Protocol for Federated Signing

Signature Validation Tokens

The draft specifications "15 - Signature Validation Token", "16 - PDF Profile for Signature Validation Tokens" and "17 - XML Profile for Signature Validation Tokens" are no longer part of the Swedish eID Framework specifications, and have been replaced by the following IETF drafts:

See https://github.com/swedenconnect/IETF-SVT for the repository that is hosting this work.


Older versions

Older version of the specifications are stored in the following branches:


Copyright © The Swedish Agency for Digital Government (DIGG), 2015-2024. All Rights Reserved.

technical-framework's People

Contributors

araskazemi avatar martin-lindstrom avatar razumain avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

technical-framework's Issues

Validation of SAD JWT:s will not work if a Proxy-IdP is used.

The SAD specified in Signature Activation Protocol for Federated Signing is supposed to be verified by the recipient (i.e., an Signature Service). The Signature Service does that by performing the following steps:

  1. Verify that JWT signature by using the IdP signature certificate(s) found in its metadata entry.
  2. Assert that the aud (audience) claim equals the SAML entityID of the Signature Service.
  3. Assert that the iss (issuer) contains the entityID of the issuing IdP.
  4. Validate that the SAD has not expired by checking the exp and iat claims.
  5. Assert that the irt (in response to) extension claim holds the ID of the AuthnRequest containing the SADRequest that the Signature Service sent to the IdP.
  6. Assert that the ID of the reqid corresponds to the ID of the SignRequest that led to this communication.
  7. Assert that the user-ID in the SAD (sub and attr) matches an attribute from the received Assertion.
  8. Assert that the value of the loa claim matches what was received in the Assertion.

Suppose that the Signature Service communicates with a Proxy Service, P, that proxies the request to an IdP, X, that performs the user authentication, displaying of SignMessage and issuance of the SAD. The Proxy, P, will when it receives the SAML response from the IdP, create a new Assertion, include attributes issued from P, sign it with its own key and return the response to the Signature Service.

Now. Since the SAD attribute is proxied, the Signature Service will run into problems when verifying the SAD.

  • Check number 1 will fail since the Signature Service will use the Proxy IdP's certificate(s) when verifying the signature. This will of course not work.
  • Check number 2 will fail since the X IdP will set the aud claim to the entityID of the requester, which is the Proxy IdP.
  • Check number 3 will fail since it will contain the entityID of IdP X. The Signature Service will assume that it is IdP P.
  • Check number 5 will fail since the Proxy IdP created a new AuthnRequest (with another ID) when communicating with the X IdP.
  • Check number 7 may fail if the Proxy IdP does not send this attribute back in its response.
  • The LoA-check (8) may also fail if the X IdP and Proxy IdP works under different profiles.

Error in Deployment Profile regarding Level of Assurance URI:s in AuthnStatement

Section 6.3.4, "The Authentication Statement", of the Deployment profile, states the following:

The Service Provider MUST assert that the saml2:AuthnStatement contains a saml2:AuthnContext element that holds a saml2:AuthnContextClassRef element having as its value the authentication context URI indicating under which Level of Assurance the authentication was performed. The Level of Assurance declared in the assertion MUST be equal to, or stronger3 than, the Level of Assurance requested by the Service Provider.

This is not correct since we require "exact" matching in RequestedAuthnContext:s, see section 5.3, "Message Context".

Update references to SAML specifications

As part of releasing the next version of the specifications for the Swedish eID Framework we should update references to underlying SAML specifications. Some of the current references are outdated.

For example MDUI.

Revise certificate profile for use within eIDAS

When a signature is requested and the user is authenticated against the Swedish eIDAS node, the assertion may not contain a personal identity number. We need to update the certificate profile so that other primary identities may be represented (such as the provisional id).

Add URI:s for representing countries

We need to add URI:s for representing countries for communication between eIDAS Proxy Service and the national IdP:s.

Currently we have representation of countries but those have the prefix http://id.swedenconnect.se/eidas/1.0/proxy-service/{country-code} and should be used by Swedish SP:s when sending requests to the eIDAS connector.

@Razumain

Review BankID Relying Party Guidelines v3

Check what we need to update in the "Implementation Profile for BankID Identity Providers within the Swedish eID Framework" specification based on the updated BankID Relying Party Guidelines (v3).

Update signing specifications

Two new proposals to store transaction related evidence in signing certificates.

  • Store transaction identifier as subject attribute: 1.2.752.201.3.2 with a mapping to the SAML attribute in AuthContext extension

  • Store the SAD payload in the AuthnContext extension

An Identity Provider may need to know if the user agent is executed in an app

Depending on the way an Identity Provider authenticates users there may be cases where the IdP would benefit of knowing if the user agent (web browser) is executed from within an app (iOS or Android). This is especially true for an Identity Provider implementing BankID authentication where the BankID app is started differently depending on if the user is using an ordinary web browser or an app (that has an encapsulated web browser).

We should investigate what support we need to introduce in the technical framework to solve this issue.

One suggestion is to introduce a new service type entity category, mobile-app, and have the Service Providers that use apps include this in their metadata.

Do we need anything more? There are differences between iOS and Android, and we also have the issue of whitelisting URLs.

Forum för diskussioner om E-legitimationsnämndens tekniska ramverk

I detta forum diskuterar vi E-legitimationsnämndens tekniska ramverk och andra tekniska frågor som rör framtagandet av en gemensam federation.

För att starta en ny "tråd", skapa en "issue"!

Har ni förslag på hur forumet kan förbättras, tveka inte att föreslå det.

Prevent fingerprint during BankID signature operations

We should update "Implementation Profile for BankID Identity Providers within the Swedish eID Framework" so that we include a text that states "the IdP SHOULD prevent fingerprint authentication from being used during BankID signature operations".

Det är viktigt att svenska export företag har möjlighet att lämna e-anbud

Comfact får frekvent frågor från export företag som vill lämna anbud på projekt i annat EU land. De behöver vid dessa anbud ett kvalificerat certifikat, dels för åtkomst, men främst för underskrift av anbud. Vi känner frustration att vi inte kan assistera dessa svenska exportföretag i hur de skall gå till väga för att vara kvalificerade i upphandlingen. Risken är att svenska konkurrenskrfatioga anbud avvisas pga. formalia/process.

En fråga till Nämnden är därför vad vi skall svara svenska exportföretag som måste lämna elektroniska anbud?

En annan tanke är om vi/ni kan tillhandahålla en tillfällig lösning så att vi inte förlorar mer exportinkomster?

Include attributes in eIDAS assertions for traceability

When a SP receives an assertion via the eIDAS connector it should receive enough information to be able to, if needed, later contact the issuing party in the foreign country. That is, we want to ensure that the assertions contain enough information so that we don't have to rely on logging in the Swedish eIDAS connector.

Typically, we want to include among the attributes passed from the eIDAS connector to the SP the following attributes:

  • The ID for the response, or assertion, sent from the foreign eIDAS node to the connector, and,
  • The entityID of the foreign eIDAS node.

Specify requirements on signature key for SAD JSON Web Tokens

Section 3.2, "Signature Activation Data", specifies the contents of the SAD token and mentions that it should be signed, but it doesn't specify any requirements on the signature key used. If the consuming service lacks information about the signature key validation will not be possible.

Suggestion: Specify that the IdP MUST sign using any of the signature keys (certificates) that is has listed in its metadata.

Use appropriate example URI:s

In the deployment profile, section 6.2, the domain "company.com" as an example of an identifier.

"saml2:AuthenticatingAuthorityhttp://idp.company.com/auth</saml2:AuthenticatingAuthority>"

It is inappropriate to use domain names that are in use as real domains. Example domains such as "example.com" should be used instead.

Nit in Deployment profile 6.1: Inconsistent requirement language for encrypted assertions

The following text:

Identity Providers SHALL utilize XML Encryption and return a saml2:EncryptedAssertion element in the saml2p:Response message. The elements saml2:EncryptedID and saml2:EncryptedAttribute MUST NOT be used; instead the entire assertion should be encrypted.

In the end. Change "should be encrypted" to "MUST be encrypted".

Reason:
There is a slight risk that someone may interpret "should" as if this is only recommended.

Signature Services should use the Scoping element in AuthnRequests

An Identity Provider serving an AuthnRequest sent from a signature service has no way of figuring out information about the actual service provider that invoked the signature service.

One organization may have several service providers, and they may all be using the same instance of signature service to provide signature services. The service providers may be differently configured. One may be intended for mobile devices (apps) and another one for an ordinary desktop. An IdP receiving requests from these service providers may then implement its services differently depending on what it knows about the service provider (it may even have configuration that is obtained by other means that reading SP metadata).

Now, the problem arises when one SP with a particular configuration at the IdP (and in SAML metadata) invokes a signature flow which eventually will lead to that the organization signature service generates an AuthnRequest and passes the user and request to the IdP. How will the IdP know which configuration to apply when the user should authenticate for signature? The organization signature service SP cannot be configured to suit all SP:s.

The suggestion is to recommend Signature Service SP:s to include the entityID of the SP that the user has authenticated at in the AuthnRequest (if available). An IdP may then, if needed, apply different behaviour for different calls from the same Signature Service SP by looking the the passed "orig SP entityID".

For this purpose the Signature Service SP should use the <saml2p:Scoping> element and in this element include a <saml2p:RequesterID> holding the entityID of the SP that initiated the call.

<saml2p:Scoping>
  <saml2p:RequesterID>http://www.origsp.com/sp</saml2:RequesterID>
</saml2p:Scoping>

Also see this thread in the discussion forum.

Swedish to eIDAS LoA mapping requires a new identifier for eIDAS low-notified

The eIDAS regulation allow notification of eID schemes at Assurance level Low.

Implementation of mapping logic has demonstrated that we need to define Swedish eDIAS identifier for LoA low with notified eID in the same manner as we have provided for level substantial and high.

Not doing so would require us to apply a completely different logic for mapping eIDAS low compared to what is used for eIDAS substantial and high. Making implementations complex and prone to generate errors.

Clearify BankID IdP behaviour when user cancels authentication

Section 3.4 of the "Implementation Profile for BankID Identity Providers within the Swedish eID Framework - version 1.0" specification should be updated to clarify that an IdP makes sure that there are no dangling BankID-session.

If the user clicks "Cancel" in the IdP UI after giving his or hers personal identity number but before starting the BankID-app, the BankID-session will be left hanging and preventing the user from using its BankID for the next couple of minutes (until the session times out). This is because the IdP initiates the BankID operation after it has been given the personal identity number.

A solution may be that the IdP initiates a new BankID-operation just to make sure to kill the previous one (the newly created will also be invalidated by the BankID server).

Of course, the best solution would be if the BankID-API defined a Cancel-method, but this will have to be communicated in other channels.

Issue with saved personal identity numbers for BankID IdP:s

Section 3.3 and 4.2.2 of the Implementation Profile for BankID Identity Providers within the Swedish eID Framework - version 1.0 specification recommends that the IdP should save (in a cookie) a personal identity number entered during authentication for later use when the users "authenticates for signature" (BankID signature). The reason for this recommendation is that we want to avoid prompting the user for the personal identity number when he or she is performing a signature within the same web session.

Now, use cases where this recommendation may mess up the desired behaviour have been reported. Without going into any details, the problem is that a service provider wishes to let two different persons sign a contract within the same web session. One person logs in, and the two persons fill in the contract/agreement together and at the end both parties sign the contract. It is a special case, but, in either way, when person number 2 is about to sign the contract there is no way for the service provider to get the IdP to understand that it should prompt for the personal identity number. The IdP has already written the first persons personal identity number to a session cookie that resides in the browser.

The only bullet proof solution to this problem is to extend the AuthnRequest message so that signature services may pass information to the IdP about the user in question. By introducing this kind of extension we get a solution that is more dynamic for any use case and any type of technique implemented by the Identity Provider.

CEN EN 419241-1 on remote signature approved

"December 8th, Essen (DE), the CEN experts workgroup on protection profiles (WG17) has approved the final version of the remote signing standard part 1 (EN 419 241-1)."
"It will allow to setup a remote signature/seal system for advanced and qualified levels."

Behöver den svenska Normativa specifikationen uppdateras pga. detta? I så fall - i vilken utsträckning?

Dedikerad felkod för PossibleFraudDetected?

Som ni säkert känner till så lurar bedragare (t.ex. inom fondförvaltning) användare via telefon genom att be dessa knappa in sin PIN-kod för Mobilt BankID, och bedragaren som startat en BankID autentisering mot en tjänst kan då loggas in.

Det finns två huvudsakliga "attacker". I den ena loggar också användaren in, och då kan vissa fel mottas från BankID (typ, "du har redan en pågående inloggning"), och i den andra utför bara bedragaren en inloggning (och användaren ger bara sin PIN-kod). Den sistnämnda är den vanligaste, och också den som är svårast att skydda sig emot.

Hur en IdP skyddar sig täcks inte av Tekniskt ramverk, men det finns en starkt behov från myndigheter att notifieras om ett möjligt pågående bedrägeriförsök. Mitt förslag är därför att Tekniskt ramverk definierar en ny SAML-felkod, t.ex., http://id.elegnamnden.se/status/1.0/possibleFraud, vilken ska kunna användas för att indikera detta beteende. Felkoden används som en "sub"-felkod, vilket inte borde innebära problem för SP-instanser som använder hyllprodukter som inte förstår denna felkod.

SAML-profiler som används bl.a. i UK använder detta förfarande.

Vad tycker ni?

XML Schema error in SAD Request

In the specification, the element RequestedVersion is Optional.
In the XML schema, this element is required.

The specification is right and the Schema is wrong.

Support for QSCD according to CEN EN 419 241

Technical specifications for federated signing need to be updated in order to support the new requirements for Qualified Signature Creation Devices (QSCD) specified by the CEN EN 319 241 standards series.

In particular, the technical specifications must specify how IdP:s should produce Signature Activation Data (SAD) that must be validated by the signature service Signature Activation Module (SAM).

Add information about Discovery

Previous versions of the Technical framework contained a dedicated specification for IdP Discovery that no longer is valid. When setting up the Sweden Connect federation we will introduce a central discovery service and therefore we need to add information about how Discovery is performed.

We do this in the current specifications and do not introduce a new spec just for this.

Adding "typ" claim to SAD tokens

A new best practice recommendation for JWT suggests that JWT should include a type taclaration using the "typ" claim. This reduce the risk that one JWT of a particular type is mistaken for a JWT of another type. It is therefore suggested to add a "typ" claim to the SAD JWT, defining it to be a SAD token.

Deployment profile must handle algorithm support

Going into the Sweden Connect-federation has showed that we need to be more explicit concerning algorithm interoperability, especially regarding encryption of SignMessage extensions between signature service SP:s and IdP:s.

Therefore, we will add references to "SAML v2.0 Metadata Profile for Algorithm Support Version 1.0".

On swedenconnect.se we will also have to define the mandatory algorithms for the federation. Hard-wiring that into the technical framework isn't such a good idea.

Introduce new type of entity category

When setting up policies and processes for the Sweden Connect-federation we have ran into the following problem:

Not all IdP:s in the federation accepts requests from all the SP:s in the federation. Generally, an IdP will only support a certain SP's requests if they have some sort of mutual agreement (contract).

In order for IdP:s to easily see whether a request should be processed and for the sake of setting up a central discovery service we need some sort of "Service Contract" entity category. Looking for the presence of a given contract EC will help an IdP to know whether it has an agreement with a given SP.

IdP:s should deliver BirthDate if "samordningsnummer" is delivered

The eIDAS minimum dataset requires BirthDate to be delivered. For Swedish assertions we deduce the BirthDate from the personalIdentityNumber. However, if a Swedish eID delivers a "samordningsnummer" as the personalIdentityNumber we may not be able to deduce the BirthDate. Therefore, the requirements should be changed so that the BirthDate is delivered in those cases.

Extend requirements for MDUI

Section 2 of the "Deployment Profile for the Swedish eID Framework" lists a number of requirements for the inclusion of a <mdui:UIInfo> element. We should update this section and be more clear about things like logotypes (transparent, vector based) etc.

Translate ELN-0600 to English

The introduction document to the Swedish eID Framework is still only in Swedish. Requests have been made to have this document in English as well.

Change name to Sweden Connect

Currently the Swedish E-Identification Board is the owner of the Swedish eID Framework. Since the Swedish E-Identification Board will cease to exist and be part of a new authority, we will change all references from the Swedish E-Identification Board to Sweden Connect.

We will also change the logotypes.

Support for scoping for Proxy IdP:s

A Proxy-IdP should support the Scoping element where a SP may include an IDPList that is a requirement of which IdP, or IdP:s, that is required to perform the actual authentication.

Furthermore, we should look into using the same mechanism for an SP wanting to specify the desired country in the AuthnRequest sent to the eIDAS connector. For this we need to specify a set of entity identifier for countries, for example http://id.swedenconnect.se/countrycode/dk.

Consider removing "samordningsnummer" from personalIdentityNumber

The "Attribute Specification for the Swedish eID Framework" specification states that the personalIdentityNumber attribute can contain a Swedish "personnummer" or a "samordningsnummer". After discussions with Skatteverket, we have found out that the issuance process of a "samordningsnummer" can not be compared with the issuance of a "personnummer". Therefore, we should state that the personalIdentityNumber is a "personnummer" and nothing else.

If there is a need to represent "samordningsnummer", this should be done using a dedicated attribute for that purpose.

More clear requirements for Attribute Release

Section 6.2.1 of "Deployment Profile for the Swedish eID Framework" states:

An Identity Provider receiving a request for more attributes than it can provide SHOULD return an assertion with the attributes it can provide according to its defined attribute release policy, leaving it up to the Service Provider to decide how to proceed, e.g., by denying service to the authenticated user, provide limited services or to use other resources to collect necessary attributes.

This is contradictory with the meaning of the metadata element RequestedAttribute setting the isRequired-flag to true. Let's fix this.

Provisional ID for Base64 encoded Personal Identifiers

The current specification ELN-0611-v1.0 for provisional ID is based on the presumption that the PersonalIdentifier attribute received from another member state is a traditional identifier based on numbers and basic non-case-sensitive characters, like out personnummer "192512013212"

The current algoritm strips away delimiting characters from information carrying characters. That is. "192512013212" is considered equal to "19251201-3212"

This algoritm does not work when the ID from other member state is a Base64 encoded hash value, like we get from Austria.

The current specification is updated with a new algoritm for provisional ID generation that can be assigned to countries like Austria, where the identifier is a Base64 encoded hash.

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.