SuisseID Digitaler Pass und Unterschrift

Schritte zu Ihrer SuisseID

IdP Integration Guide - Technote

Introduction (this document is only available in English)

This article is intended for organizations that investigate or plan to integrate user authentication SuisseID services in their environment or software. The SuisseID Identity Provider provides authentication and qualified attribute services.

The authentication services include SuisseID Smartcard and SuisseID Mobile Service (2-Factor authentication with username / password and SMS passcode). User attributes are qualified based on official documents (e.g. passport) and a face-to-face validation.

Transport of authentication and attribute information between the SuisseID Identity Provider and the relying parties is based on the SAML2 specification.

(Detailed technical information)



  • SAML: Security Assertion Markup Language is an XML-based open standard data format for exchanging authentication data between parties, in particular, between an identity provider and a service provider.[1]
  • SP / Service Provider / Relying Party: The service provider requests and obtains an identity assertion from the identity provider [1]. The service provider is typically a web portal, for instance or the citizen portal of the Canton of Jura (
  • IDP / Identity Provider: The SuisseID identity provider authenticates the user and sends a security token to the service provider which indicates authentication circumstances (time, method, etc.) and might contain qualified user data.
  • Assertion: A SAML assertion contains a packet of security information.[1] The SuisseID IDP issues digitally signed assertions which contain the user's SuisseID number, qualified user attributes, authentication time and method.


IDP Login vs. X509 Certificate Login

The IDP Login is different from the "direct" X.509 authentication. Many applications(e.g. Apache HTTPD) provide certificate login capabilities directly. However the IDP Login is based on the SAML2 HTTP-Post Browser Profile. With IDP Login, the user still authenticates using the SuisseID certificate (or Mobile Service), but against the IDP, not the application. The IDP then generates a signed SAML token which is consumed by the application. This approach allows to better support mobile devices and allows the application to retrieve qualified user attributes from the Identity Provider.


Prior to looking into how integration can be done, it is useful to examine the following questions :

  1. What are my drivers to integrate SuisseID ?
  2. Sounds trivial, but most design choices will be derived from the answer to this essential question. Are your drivers strong authentication, qualified user attributes or the use of SuisseID service like the SuisseID signing service.
  3. What downstream applications shall benefit from SuisseID ?
  4. Depict the inventory of applications that shall benefit from SuisseID integration - and their particular requirements. Which application needs user attributes ? Are there requirements concerning end user devices ?
  5. What does the current security framework require and provide ?
  6. Companies existing security frameworks often have another set of requirements with regards to specific authentication methods. x509 certificate authentication can sometimes be supported and sufficient. On the other hand, security and in particular identity and access management systems provide SAML functionality. However often with limitations or specific requirements.
  7. What end user devices must be supported ?
  8. Especially examine if mobile devices like smartphones and tablets must be supported. If this is the case, then also consider using the SuisseID Mobile Service which is specifically targeted to devices that do not allow the installation of "middleware" and the plugging-in of USB token.

Typical Scenarios

Requirements to SuisseID integration can be multiple and existing environments diverse. Here are some typical scenarios where integration and choice of SAML frameworks are similar.

Internet Portal

Internet facing portals (e.g, offer or mandate SuisseID IDP authentication. This type of portal often integrates programmatically SuisseID authentication either via the SuisseID SDK/Java or the SuisseID SDK/.Net or any other SAML2 capabable SDK (opensaml, oiosaml, simplesamlphp, shibboleth) . The advantage of this approach is that it provides great flexibility in how to use the SAML protocols.

Enterprise Security

SuisseID authentication can be added to existing enterprise security frameworks (i.e. identity and access management). In this process, the technical integration depends on the existing technology. Often there is very limited flexibility as existing technologies rarely provide programmatic extension points. The SuisseID IDP is typically integrated as a standard SAML2 identity provider. For guidelines on how to integrate Microsoft Active Directory Federation Services (ADFS), see the resources section [2] [3].

Cloud Applications

Cloud services like GoogleApps, provide standard SAML interfaces for 3rd party authentication. These applications are "black-boxs" supporting only a subset of SAML. Thus the integration is application specific. For guidelines on how to integrate GoogleApps, see the resources section [4].

The User Perspective

In a fully integrated internet portal scenario, the user will typically find a SuisseID button on the web application to trigger login via SuisseID. A SuissID smartcard (e.g. via USB reader) should be inserted prior to opening the web browser. This example from illustrates a SuisseID login button on the front page:


After clicking the SuisseID login button, the user browser is re-directed to the SuisseIDP IDP authentication URL. If the Smartcard was inserted, the browser will prompted for the PIN (otherwise the user might reach the SuisseID Mobile Service context). After successful authentication at the SuisseID IDP, the user must agree to disclose data to the web portal which initiated the Login. The confirmation dialogue is a post process of the authentication and mandatory before sending user data to the relying party.


After confirming the disclosure of data by the user, the user finds the initiating web portal again.


The Relying Party / Service Provider Perspective

The diagram depicts the process of the SAML Login via the HTTP-POST binding. The user initiates the process, the Service Provider issues a SAML AuthnRequest to the Identity Provider. After successful user authentication, the Identity Provider provides a digitally signed SAML token back to the Service Provider so that the user can be logged in locally.

Integration Points

A Service Provider generally has to address the following areas for a successful SuisseID IDP Login integration:

  1. User Interface: Login Button to allow user to initiate SuisseID IDP login (also see CI/CD-Manual)
  2. SAML Framework: Component to generate AuthnRequests and consumer SAML assertions issued by the SuisseID IDP. Probably one of the most challenging aspects of integration. This will be addressed further in more detail.
  3. User mapping: After successful authentication via the Identity Provider, the user must typically be mapped to a local account at the Service Provider. This can either be done through a user attribute obtained from the IDP, like emailAddress or by linking the user's SuisseID number to the local account.
  4. User attributes: The Service Provider might want to extract user attributes from the assertion for further processing.

Linking the SuisseID number to a local account

As stated earlier, the user authenticated by the SuisseID IDP can be mapped to a local account at the service provider by an attribute known and verified by both sides, for instance the email address. However it cannot be assured that even verified email addresses are not used by multiple people (e.g. Diese E-Mail-Adresse ist vor Spambots geschützt! Zur Anzeige muss JavaScript eingeschaltet sein!).
A common approach to map a user to a local account at the Service Provider is by the SuisseID number. If the user has already enrolled at the service provider and possesses username and password, a preliminary step is that the user links the SuisseID number to this account. This typically requires a specific process at the Service Provider involving a login with username and password at the Service Provider and, within the same session, a SuisseID login either through the IDP or via the X.509 certificate directly. Then the local account can be linked to a SuisseID number and user for the account mapping process.

User registration with SuisseID

User registration (or enrollment) at the Service Provider can also integrate a SuisseID IDP login prior to the registration finalization. The advantage here is that the IDP provides qualified user attributes like email address, firstname, lastname, date of birth, nationality, etc., so that the user does not need to type them again. The Service Provider has the benefit that these attributes are verified. In this case, the linking of the local account to a SuisseID number can be done during the registration process.

Service Provider Registration at IDP

Before utilizing the IDP for authentication, a Service Provider must register at the Service Provider Registration page (see [8]). Note that some parameters might depend on the SAML framework used (e.g. assertion consumer URL, issuer name).

Programmatic Integration

A great level of flexibility is offered by SAML software development kits. This allows to control the request generation and the response validation as opposed to "black-box" SAML implementations which typically allow only configuration, but not programmatic customization.

The SuisseID SDK (in Java and .Net) is available specifically to those Service Providers who wish to use SuisseID specific extensions, like requesting attributes in an AuthnRequest or validating QC-signed attributes transmitted by the IDP. [9]

Integration through classic SAML frameworks like OpenSAML or SimpleSAMLphp is equally possible. Note that the SuisseID SDK/Java is based on OpenSAML.

References and Resources

[1] Security Assertion Markup Language. (2014, May 22). In Wikipedia, The Free Encyclopedia. Retrieved 13:33, May 22, 2014, from;;oldid=609667390

[2] Technote: Integrating the SuisseID IDP as an ADFS Claims Provider

[3] Technote: SuisseID IDP Claims Mapping into ADFS

[4] Technote: GoogleApps Integration with SuisseID IDP Authentication

[5] SuisseID 1.5 Specification:

[6] SAML 2 Core Specification:

[7] SAML 2 Bindings Specification:

[8] Service Provider Registration:

[9] SuisseID SDK/Java and .Net:

[10] OpenSAML2:

SuisseID ist eine eingetragene Marke der SwissSign AG.